【鸿蒙心迹】分布式数据同步与跨设备接续:手机上记到一半的待办,平板上接着写完

前言

提醒篇收束时预告过,这一章聊"不在场"的另一半:应用在这台设备上不在场,但用户正在另一台设备上。具体到码上清单,是一个特别日常的画面——通勤路上用手机记了半条待办,标题敲了一半,标签还没选;到工位坐下,面前摆着平板。此刻最理想的体验是:平板任务中心里这个应用旁边有个接续入口,点一下,编辑现场原样搬过来,手机那半行字一个都不丢。

实现它之前,我以为要自己把"发现设备、建连接、传数据"整条链路写一遍,脑海里全是软总线的长文档。真翻进官方文档才发现,系统把这件事拆成了两个现成的能力:数据同步负责让数据出现在另一台设备上,应用接续负责把"现场"搬过屏幕。两件事各管一段,拼起来才是完整的跨设备体验。这一篇就按这两层来记录。

环境照旧: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,不判断来源就执行恢复逻辑,正常启动的初始化会被接续残留状态污染。

踩坑三条

  1. 权限声明了,弹窗没调:DISTRIBUTED_DATASYNC 声明在 module.json5 里、接口全部调通、日志没有任何报错,但设备列表永远是空的。user_grant 权限的授予只认 requestPermissionsFromUser 的弹窗结果,声明只是入场券——排查时先确认"弹窗出现过没有",比翻接口日志省一小时;
  2. onContinue 塞全量:第一版把整条待办连附件列表一起塞进 wantParam,目标端解析时直接丢字段。接续通道不是数据库同步,只传指针和真正悬空的未落盘内容,全量数据让数据层在另一端接住——两层各干各的活,这个设计在踩完坑之后才真正长进代码里;
  3. 漏判 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 的授权行为以权限文档为准。系列上一篇:《【鸿蒙心迹】通知与后台任务实战》。*

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐