【鸿蒙心迹】分布式数据同步与跨设备接续:手机上记到一半的待办,平板上接着写完
【鸿蒙心迹】分布式数据同步与跨设备接续:手机上记到一半的待办,平板上接着写完
前言
提醒篇收束时预告过,这一章聊"不在场"的另一半:应用在这台设备上不在场,但用户正在另一台设备上。具体到码上清单,是一个特别日常的画面——通勤路上用手机记了半条待办,标题敲了一半,标签还没选;到工位坐下,面前摆着平板。此刻最理想的体验是:平板任务中心里这个应用旁边有个接续入口,点一下,编辑现场原样搬过来,手机那半行字一个都不丢。
实现它之前,我以为要自己把"发现设备、建连接、传数据"整条链路写一遍,脑海里全是软总线的长文档。真翻进官方文档才发现,系统把这件事拆成了两个现成的能力:数据同步负责让数据出现在另一台设备上,应用接续负责把"现场"搬过屏幕。两件事各管一段,拼起来才是完整的跨设备体验。这一篇就按这两层来记录。
环境照旧:DevEco Studio 5.x、HarmonyOS NEXT(API 14+),接口以官方 ArkData(分布式数据)与 Ability Kit(应用接续)文档为准。
先立心智:两件事,别混成一件
最早的方案设计里,我把这两件事混成了一个需求,写出来的方案自然也是拧的——想让接续把整条待办的数据一起带过去。拆开之后心智清楚多了:
- 数据跟着走:两台设备各自都有一份数据,系统在组网内负责同步。用户在平板上打开应用,看到的是完整的待办列表,不需要任何"迁移"动作;
- 现场跟着走:应用接续(continuation)只在切换的那一刻发生一次,搬运的是"此刻正在编辑哪条、表单填了什么"这类现场状态,体量很小。
两层的关系一句话就能说清:接续只搬指针,全量数据靠同步铺路。源端在接续回调里塞一个待办 ID,目标端拿 ID 去(已经同步过来的)数据层取全量。谁越界谁出事——把全量塞进接续、或者指望数据同步实时搬现场,都是后面踩坑的源头。
三个前提,一个弹窗
分布式能力有硬前提,缺一个就是"代码全对、功能全无":两台设备登录同一个华为账号;处于同一局域网(WLAN,蓝牙只做辅助发现);必须真机——模拟器上没有分布式能力,开发期最容易在这里白耗半天,先拿两台真机把环境钉死再动代码。
然后是权限。跨设备同步需要 ohos.permission.DISTRIBUTED_DATASYNC,它和相机、麦克风一样是 user_grant 级别——在 module.json5 里声明只是拿到了"可以申请"的资格,不调用 requestPermissionsFromUser 弹窗,权限永远处于未授予状态。第一版我就栽在这里:声明写好了,接口也全调通了,设备列表拿到的却是空的,同步像被丢进了黑洞。权限篇立过规矩,user_grant 必须在场景化时机申请,这里原样适用:
import { abilityAccessCtrl, Permissions } from '@kit.AbilityKit';
const PERMS: Permissions[] = ['ohos.permission.DISTRIBUTED_DATASYNC'];
// 第一次真正要用分布式能力时调用,而不是应用一启动就弹
async function ensureDistributedPerm(): Promise<boolean> {
const atManager = abilityAccessCtrl.createAtManager();
const result = await atManager.requestPermissionsFromUser(
this.context, PERMS);
return result.authResults.every(r => r === 0);
}
申请时机放在用户第一次点击"同步到其他设备"或第一次触达接续功能的那一刻,跟权限篇"场景化申请"的原则完全一致。用户拒绝之后,分布式功能整体降级为单机模式——应用主体功能不受影响,这和权限篇的功能降级策略是同一套打法。
数据层:distributedKVStore,put 之后系统去同步
选型时面前有两条官方路:一条是 RelationalStore 的分布式表(setDistributedTables),适合把已有的关系型库整表同步;另一条是 distributedKVStore,键值形态,轻量灵活。码上清单的业务数据已经在 RelationalStore 里(持久化篇立过 DAO 层),但接续协同真正要共享的是"正在编辑谁"这类轻量协作状态,键值形态更对路——业务数据与协作状态分开存,各选各的形态,这个分界判断本身比接口用法更值得记下来。
用法三步:创建 KVManager、拿 KVStore、监听远端变更:
import { distributedKVStore } from '@kit.ArkData';
async function initSyncStore(context: common.UIAbilityContext): Promise<void> {
const config: distributedKVStore.KVManagerConfig = {
context: context,
bundleName: 'com.example.todoapp'
};
const kvManager = distributedKVStore.createKVManager(config);
const options: distributedKVStore.Options = {
createIfMissing: true,
encrypt: false,
backup: false,
autoSync: true, // 组网内自动同步,不用手动调 sync
kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION
};
const store = await kvManager.getKVStore<distributedKVStore.KVStore>(
'todo_collab', options);
// 只监听远端设备写入,本地写入走正常 UI 路径,不重复刷
store.on('dataChange', distributedKVStore.SyncType.REMOTE_ONLY,
(data) => {
[...data.insertEntries, ...data.updateEntries].forEach((entry) => {
const value = JSON.parse(
new TextDecoder().decode(entry.value as Uint8Array));
collabStore.applyRemote(entry.key as string, value);
});
});
syncStore = store;
}
// 写入:对象要自己过 JSON,再编成 Uint8Array
function publishEditingPointer(todoId: number): void {
const bytes = new TextEncoder().encode(
JSON.stringify({ todoId: todoId, device: 'phone' }));
syncStore?.put(`editing_${todoId}`, bytes);
}
两个容易忽略的细节。其一,普通 KVStore 的值是 Uint8Array,业务对象要自己过 JSON.stringify 和 TextEncoder——我最初的版本直接 put 一个对象,编译器拦下来的那一刻才意识到这层不存在。其二,autoSync: true 之下数据是最终一致:put 成功不代表对面立刻有,UI 侧以 dataChange 回调为准驱动更新,别在 put 之后立刻读另一台设备的值去断言。
接续层:一个布尔,一次回调,一次判断
数据铺好后,接续层反而是整条链路里代码量最少的。第一处改动在 module.json5,给 UIAbility 加一个声明:
"abilities": [{
"name": "EntryAbility",
"continuable": true,
// ...其余配置不变
}]
continuable: true 之后,系统任务中心里这个应用就会多出接续入口——入口是系统给的,应用不用自己画。
源端要做的事写在 onContinue 回调里:把现场状态填进 wantParam,然后表态。这个回调的返回值就是一场面试——返回 AGREE 迁移继续,返回 REJECT 用户侧收到取消,返回 MISMATCH 表示两端版本不匹配走不了:
import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
export default class EntryAbility extends UIAbility {
// 源端:迁移发起时系统回调,只搬指针
onContinue(wantParam: Record<string, Object>): AbilityConstant.OnContinueResult {
const editing = editStore.getCurrentEditing();
if (!editing) return AbilityConstant.OnContinueResult.AGREE;
wantParam['todoId'] = editing.todoId; // 指针:编辑哪条
wantParam['draft'] = editing.draftText; // 未落盘的半行字
return AbilityConstant.OnContinueResult.AGREE;
}
// 目标端:区分接续启动与普通冷启动
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
if (launchParam.launchReason === AbilityConstant.LaunchReason.CONTINUATION) {
this.restoreFromContinuation(want);
} else {
this.startAsNormalLaunch(want);
}
}
// 目标端已在运行:热接续走 onNewWant,同样的判断再来一遍
onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void {
if (launchParam.launchReason === AbilityConstant.LaunchReason.CONTINUATION) {
this.restoreFromContinuation(want);
}
}
private restoreFromContinuation(want: Want): void {
const todoId = want.parameters?.['todoId'] as number;
const draft = want.parameters?.['draft'] as string;
editStore.prepareRestore(todoId, draft);
// 按官方示例口径恢复窗口;页面栈状态一并还原
this.context.restoreWindowStage(new LocalStorage());
}
}
三个分支缺一不可,这是接续层真正的坑所在:onCreate 处理目标端冷启动的接续,onNewWant 处理目标端已经开着时的热接续——只写 onCreate,手机连平板时平板上的应用通常正开着,热接续就会静默落空;而 launchReason 的判断是防"误伤"——普通点击图标启动也会走 onCreate,不判断来源就执行恢复逻辑,正常启动的初始化会被接续残留状态污染。
踩坑三条
- 权限声明了,弹窗没调:
DISTRIBUTED_DATASYNC声明在module.json5里、接口全部调通、日志没有任何报错,但设备列表永远是空的。user_grant 权限的授予只认requestPermissionsFromUser的弹窗结果,声明只是入场券——排查时先确认"弹窗出现过没有",比翻接口日志省一小时; - onContinue 塞全量:第一版把整条待办连附件列表一起塞进
wantParam,目标端解析时直接丢字段。接续通道不是数据库同步,只传指针和真正悬空的未落盘内容,全量数据让数据层在另一端接住——两层各干各的活,这个设计在踩完坑之后才真正长进代码里; - 漏判 launchReason / 漏写 onNewWant:普通冷启动走了一遍接续恢复逻辑,把本地默认状态覆盖成了源端的残留;热接续又因为只写了
onCreate而静默失败。两个问题同根:把接续当成一种启动方式来处理,实际上它是每次启动都要面对的判断分支——onCreate 与 onNewWant 里各放一份同样的判断,才把两种路径都盖住。
收个尾
回头看,跨设备这条链路的工程量不在接口——分布式同步加接续,真正要写的代码不超过一百行——而在最开始那个分界问题:这一步过去之后,数据从哪来,现场怎么还原。数据层和接续层各管一段,谁也不越界,体验就完整了。剩下的都是前提工程:真机、账号、网络、弹窗,一个都不能少。
照例自查清单:
- 三硬前提(同账号、同局域网、真机)在开发期就钉死了吗?模拟器上验证分布式是白费时间吗?
DISTRIBUTED_DATASYNC的申请时机是场景化的吗?被拒后的单机降级路径存在吗?- 接续通道里搬的是指针还是全量?未落盘的草稿有没有单独跟上?
onCreate和onNewWant都有launchReason判断吗?普通冷启动会不会误入恢复分支?- UI 是靠
dataChange驱动的,还是 put 之后立刻读远端值去断言?
下一篇接着这条线往深处走:接续是把"现场"搬过去,而用户还有更主动的诉求——在手机上点一下,直接把任务派到平板上执行。聊鸿蒙的跨设备拉起与分布式流转。下篇见。
*本文环境:DevEco Studio 5.x / HarmonyOS NEXT(API 14+)。distributedKVStore 的选项与同步语义、应用接续的回调与恢复接口,以官方 ArkData 与 Ability Kit 文档为准;DISTRIBUTED_DATASYNC 的授权行为以权限文档为准。系列上一篇:《【鸿蒙心迹】通知与后台任务实战》。*
更多推荐




所有评论(0)