应用接续实战:从手机到平板,让用户的操作“跟着走”
一、引言:用户不想“重新来一遍”
你有没有遇到过这样的场景:手机上正在编辑一篇笔记,想换到平板上继续写,结果打开平板上的同一个应用,还得重新找到那篇笔记、重新打开、再滚动到刚才编辑的位置——用户的操作状态完全没有“跟过来”。
应用接续(Continuation) 要解决的就是这个问题。它让用户在一个设备上操作应用时,能够在另一个设备上快速切换并继续该应用的任务,实现无缝衔接的使用体验。比如在手机上浏览文章到一半,换到平板上接着看,浏览器的滚动位置、阅读进度都能完美同步。
今天这篇,我们从配置 → 数据保存 → 数据恢复,完整走一遍应用接续的落地流程。
二、先搞懂:应用接续的核心流程
应用接续的完整流程可以分为三步:
-
源端保存状态:用户触发迁移,系统回调源端 UIAbility 的
onContinue()接口,开发者在这里把当前页面的关键数据保存下来 -
系统传输数据:HarmonyOS 将保存的数据传输到目标设备
-
目标端恢复状态:目标设备上的 UIAbility 启动,开发者从
want中读取数据,恢复页面状态
关键认知:应用接续传输的数据量有限制。官方建议 wantParam 小于 100KB。如果数据量较大(如长文本、图片等),应使用分布式数据对象或分布式数据库来传输。
三、Step 1:开启应用接续能力
在 module.json5 文件的 abilities 中,将 continuable 标签配置为 true,表示该 UIAbility 可被迁移。
{
"module": {
"abilities": [
{
"name": "EntryAbility",
"continuable": true, // 开启应用接续
// ... 其他配置
}
]
}
}四、Step 2:源端保存状态(onContinue)
当应用触发迁移时,系统会回调源端 UIAbility 的 onContinue() 接口。开发者在这个接口中完成两件事:
-
保存关键数据:把当前页面的关键信息(如文本内容、当前页面路由、滚动位置等)通过键值对的方式保存在
wantParam中 -
版本兼容性检测:从
wantParam.version获取对端应用的版本号,与源端版本比对,判断是否支持此次迁移import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; export default class EntryAbility extends UIAbility { // 源端:保存迁移数据 async onContinue(wantParam: Record<string, Object>) { // 1. 版本兼容性检测 const targetVersion = wantParam.version as number; if (targetVersion < 3) { // 对端版本太低,不支持迁移 return AbilityConstant.OnContinueResult.MISMATCH; } // 2. 保存页面状态数据 // 从 NavPathStack 或页面状态中获取当前页面信息 wantParam['pagePath'] = this.currentPagePath; // 当前页面路由 wantParam['pageParams'] = this.currentPageParams; // 页面参数 wantParam['contentId'] = this.currentContentId; // 内容ID wantParam['scrollPosition'] = this.scrollPosition; // 滚动位置 // 3. 返回同意迁移 return AbilityConstant.OnContinueResult.AGREE; } }五、Step 3:目标端恢复状态(onCreate / onNewWant)
在目标端设备上,UIAbility 启动时通过
launchParam.launchReason判断是否为应用接续场景。如果是,就从want中读取保存的数据,恢复页面状态。onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { // 判断是否为应用接续场景 if (launchParam.launchReason !== AbilityConstant.LaunchReason.CONTINUATION) { // 非接续场景,走正常启动流程 return; } // 恢复迁移数据 this.restoreData(want); } private restoreData(want: Want) { const pagePath = want.parameters?.pagePath as string; const pageParams = want.parameters?.pageParams as Record<string, Object>; const contentId = want.parameters?.contentId as string; const scrollPosition = want.parameters?.scrollPosition as number; // 将数据保存到 AppStorage 或 LocalStorage AppStorage.setOrCreate('pagePath', pagePath); AppStorage.setOrCreate('pageParams', pageParams); AppStorage.setOrCreate('contentId', contentId); AppStorage.setOrCreate('scrollPosition', scrollPosition); }⚠️ 单实例应用(singleton 模式)的额外处理:如果 UIAbility 是单实例模式,在目标端设备上可能已经存在实例,此时系统会回调
onNewWant()而不是onCreate()。需要在onNewWant()中也做同样的数据恢复逻辑。onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void { if (launchParam.launchReason !== AbilityConstant.LaunchReason.CONTINUATION) { return; } this.restoreData(want); }六、进阶:快速拉起——让用户少等一会儿
常规的应用接续流程是:源端先保存数据,等数据传输完成,目标端再启动应用。如果数据量较大,用户可能需要等待几秒钟。
快速拉起(Quick Start) 功能支持在用户触发迁移、等待迁移数据返回的过程中,并行拉起目标应用,减小用户等待时间。
开启方式:在
module.json5配置文件的continueType标签的取值中添加"_ContinueQuickStart"后缀。{ "module": { "abilities": [ { "name": "EntryAbility", "continuable": true, "continueType": "migration_ContinueQuickStart" // 开启快速拉起 } ] } }开启后,目标端应用会在数据到达前先拉起界面占位,待数据传输完成后再刷新内容。配合
continueManager.on('prepareContinue', ...)可以监听快速拉起的结果。七、适用场景与数据量控制
典型适用场景:
-
笔记/文档编辑页面的进度同步
-
购物车内容跨设备继续下单
-
浏览器阅读进度同步
-
视频播放进度接续
-
数据量控制:
-
wantParam建议小于 100KB -
大数据(如长文本、图片、文件)使用分布式数据对象或分布式数据库
-
迁移时只传最小必要状态(如内容ID、页面路由、会话ID、版本号),目标端根据ID重新拉取完整数据
-
目标端已有 UIAbility 实例,迁移数据只在
onCreate中恢复,onNewWant没处理,导致数据丢失。✅ 解法:
onCreate和onNewWant都要做数据恢复。九、结语
应用接续的核心就是存状态、传数据、恢现场三步。配置好
continuable: true,在onContinue里保存最小必要数据,在目标端onCreate/onNewWant里恢复,就能让用户的操作“跟着走”。记住三个核心原则:
-
只传最小状态——ID+路由,大数据走分布式数据对象
-
版本要兼容——不兼容时返回 MISMATCH
-
单实例要双处理——
onCreate和onNewWant都要恢复数据 -
八、常见踩坑点
坑1:忘记在 module.json5 中配置 continuable: true
onContinue()不会被回调,迁移失败。✅ 解法:在 UIAbility 的配置中加上
"continuable": true。坑2:数据量太大导致迁移失败
在
wantParam里塞了十几 MB 的数据,迁移超时或失败。✅ 解法:只传最小必要状态(ID+路由),大数据用分布式数据对象。
坑3:目标端版本不兼容时没有返回 MISMATCH
对端版本太低,但
onContinue()返回了AGREE,导致目标端恢复数据时出错。✅ 解法:在
onContinue()中做版本兼容性检测,不兼容时返回MISMATCH。坑4:单实例应用忘记实现 onNewWant
- 为了保障您的信息安全,请勿上传您的敏感个人信息(如您的密码等信息)和您的敏感资产信息(如关键源代码、签名私钥、调试安装包、业务日志等信息),且您需自行承担由此产生的信息泄露等安全风险。
- 如您发布的内容为转载内容,请注明内容来源。
我要发帖子





































苏公安网备 32011402010933号