Skip to content

分布式能力:跨设备流转与协同 ​

本篇要点:能判断一个跨设备需求该用迁移、数据对象还是文件,并在设计阶段说清它的失败语义。 前置文章:《性能优化:布局、长列表与帧率分析》把单机页面调到了 59fps,这一章让同一份状态出现在第二台设备上。

为什么需要它 ​

2026 年 2 月到 5 月,一个团队做笔记应用的双端协同:手机写、平板接着看,中间还能双端同时标注同一份内容。三月底上线,五月底做了一次结构性削减,把其中两个功能从设计里删掉。

删掉的原因不是做不出来。做出来了,也能跑。是它的行为边界和向用户承诺的不一样,而修补的成本超过了收益。

回头看,返工三次才想明白的事只有一句:分布式软总线(distributed soft bus)在底下做的是发现、连接、传输、加密。它不提供分布式锁,不提供分布式事务,也不保证多端写入的顺序。

从 API 层面拿到的是四样东西:设备管理、跨端迁移、分布式数据对象、分布式文件。它们能做的只有一件事——把状态复制过去。

冲突怎么裁决,是业务要回答的问题。任何把分布式当远程过程调用(RPC,remote procedure call)用的设计,最终都会卡在一致性上。

版本说一句:截至 2026 年 11 月,基线是 HarmonyOS 6.0.0(API 20,2025 年 9 月 25 日 Release)。分布式数据对象的 create 从 API 9 起可用(@kit.ArkData),设备管理从 API 10 起(@kit.DistributedServiceKit),跨端迁移的两个回调在 API 12 之后趋于稳定。

核心概念 ​

四个能力面,一层共同前提 ​

先把关系摆清楚,如图 8-1 所示。

图 8-1 四个分布式能力面与共同前置条件

图 8-1 里那个“不报错”是最耗排查时间的地方。这套 API 的失败路径几乎都不抛异常:设备列表为空、数据没同步过去,代码照常往下走。

设备管理:先证明两台设备互相认识 ​

定义:设备管理(distributed device manager)负责拿到可信设备列表,并监听上下线。

前置条件有三条,缺一条就返回空数组:登录同一个华为账号、两台设备已互相认证、应用在两端都已安装。

这三条听起来像常识,但排查时最容易被跳过。空数组不是权限错误,不是 SDK 版本问题,也不会在日志里解释自己。

另一个必须记住的约束:networkId 标识“网络中的这台设备”,会随网络环境变化。拿它当业务主键,用户换一次 WiFi,对端就认不出来了。业务侧要用自己的账号体系做映射,networkId 只在当次会话里用。

跨端迁移:代码很少,触发不在你手里 ​

定义:跨端迁移(continuation)把当前 Ability 的任务状态交给另一台设备继续。

代码量小到让人以为漏了什么。半天能写完,然后要花三天回答产品经理的问题:怎么让用户触发它。

答案是:应用不能发起,只能声明。在 module.json5 的 abilities 里配 "continuable": true,入口在多任务、控制中心这些系统位置。官方文档写得很清楚,迁移由系统完成,应用只决定“迁不迁、迁什么、迁完源端退不退”。

onContinue(wantParam) 是源端的决策点。它返回 OnContinueResult,决定这次迁移要不要发生;wantParam 里放要带过去的数据,整体控制在 100KB 以下;version 与 targetDevice 是系统预置字段,不要覆盖。

目标端按 launchReason 分流。只写 onCreate 会漏掉热启动:应用还在后台时迁移过去是空白页,因为走的是 onNewWant。

还有一个比配 continuable 更实用的开关:context.setMissionContinueState(AbilityConstant.ContinueState.ACTIVE | INACTIVE)。编辑页设 ACTIVE,设置页设 INACTIVE,用户在毫无意义的页面上就触发不了迁移。

分布式数据对象:会话、复制与“尽力而为” ​

定义:分布式数据对象(distributed data object,DDO)把一个普通对象的属性变更复制到同会话的其他设备。

API 极简:create 建对象、setSessionId 设同一个会话号、on('change') 收变更。难的不是 API,是会话号怎么到对端。sessionId 必须由业务自己的信令通道同步——扫码、账号服务下发、已建立的 socket,框架帮不了你。

它只支持基本类型、数组与基本类型的嵌套。带方法的类实例、含循环引用的对象都过不去;把整个 Note 对象扔进 create,会直接失败。

还有一条官方明确提示:DDO 不解析用户数据内容、存储路径安全性较低,不建议传输个人敏感与隐私数据。

分布式文件:一次性传输,不当存储层 ​

定义:分布式文件(distributed file)让应用按对端给出的 fileUri 打开远端文件,读写接口与本地文件一致。

它适合“把一份文档传过去”这类一次性需求。每次打开都有握手,所以不适合高频小数据同步,也不该被当成实时协作的存储层。我们最后留下的功能就是它:把笔记导出成一个文件传到对端,简单、可预期,失败能明确告诉用户“传失败了”。

它也没有“离线补投”。A 端写的内容,B 端下次上线时能不能拿到?save 可以把对象存到对端,但对端不在线时不会排队。目前可行的做法是自己做一层本地落库、变更日志、上线后拉取差量,这套逻辑不依赖软总线。

动手实践 ​

第一步:把设备列表跑出来 ​

ts
// 前提:API 20;@kit.DistributedServiceKit
import { distributedDeviceManager } from '@kit.DistributedServiceKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG: string = 'DeviceMgr';
let dm: distributedDeviceManager.DeviceManager | undefined;

export function initDeviceManager(bundleName: string): void {
  dm = distributedDeviceManager.createDeviceManager(bundleName);

  // 必须监听上下线,否则拿到的是"打开页面那一刻"的快照
  dm.on('deviceStateChange', (data: distributedDeviceManager.DeviceStateChange) => {
    hilog.info(0x0000, TAG, 'device %{public}s state=%{public}d',
      data.device.deviceName, data.action);
  });

  const trusted: distributedDeviceManager.DeviceBasicInfo[] = dm.getAvailableDeviceListSync();
  trusted.forEach((d: distributedDeviceManager.DeviceBasicInfo) => {
    hilog.info(0x0000, TAG, '%{public}s / %{public}s', d.deviceName, d.networkId);
  });
}

export function releaseDeviceManager(): void {
  if (dm) {
    dm.off('deviceStateChange');
    distributedDeviceManager.releaseDeviceManager(dm);
    dm = undefined;
  }
}

运行结果:两台满足前置条件的设备,日志各输出一行 MatePad / <networkId>;不满足时数组为空,函数正常返回、没有异常。

releaseDeviceManager 不能省。反复进出页面而不释放,累积的不是内存,是回调:大概二十次之后,设备列表要两秒才出来。在页面的 onDestroy 里补上释放即可。

第二步:写迁移的源端与目标端 ​

ts
// 源端:module.json5 的 abilities 里必须配 "continuable": true
import { AbilityConstant, UIAbility, wantConstant } from '@kit.AbilityKit';

export default class EntryAbility extends UIAbility {
  private draftId: string = '';
  private scrollOffset: number = 0;

  onContinue(wantParam: Record<string, Object>): AbilityConstant.OnContinueResult {
    // version 与 targetDevice 是系统预置字段,不要覆盖
    const peerVersion = wantParam.version as number;
    if (peerVersion < 1000) {
      return AbilityConstant.OnContinueResult.MISMATCH;   // 对端版本过低,拒绝迁移
    }
    wantParam['draftId'] = this.draftId;                  // 整体控制在 100KB 以下
    wantParam['scrollOffset'] = this.scrollOffset;
    wantParam[wantConstant.Params.SUPPORT_CONTINUE_PAGE_STACK_KEY] = false;
    // 源端不退出:两台设备各自保留任务
    wantParam[wantConstant.Params.SUPPORT_CONTINUE_SOURCE_EXIT_KEY] = false;
    return AbilityConstant.OnContinueResult.AGREE;
  }
}

运行结果:对端版本达标时迁移发生,draftId 与 scrollOffset 到达目标端;版本过低返回 MISMATCH,迁移界面直接提示失败,不会带着不完整状态过去。

SUPPORT_CONTINUE_SOURCE_EXIT_KEY 默认是 true,也就是迁移成功后源端退出。对“手机看一半、平板接着看”合理;对“两台设备同时标注同一段内容”就不合理,必须显式关掉。这一条踩过一次:测试同事迁移完发现手机上的页面没了,以为是 bug。

ts
// 目标端:只写 onCreate 会漏掉热启动
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
  if (launchParam.launchReason === AbilityConstant.LaunchReason.CONTINUATION) {
    this.draftId = want.parameters?.['draftId'] as string ?? '';
  }
}

onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void {
  if (launchParam.launchReason === AbilityConstant.LaunchReason.CONTINUATION) {
    this.draftId = want.parameters?.['draftId'] as string ?? '';
  }
}

运行结果:杀进程后迁移与后台热迁移都能恢复 draftId。只写 onCreate 时,热迁移过去是空白页——这个 bug 只在热启动这条路径上出现,而测试通常先杀应用再测,所以容易漏。

第三步:用数据对象同步一个共享状态 ​

ts
// 前提:API 20;@kit.ArkData;两端同账号且设备已认证
import { distributedDataObject } from '@kit.ArkData';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

class BoardState {
  strokes: string[] = [];
  activeUserId: string = '';
}

export class BoardSync {
  private ddo: distributedDataObject.DataObject | undefined;
  private state: BoardState = new BoardState();
  onChange: (state: BoardState) => void = () => {};

  start(ctx: common.UIAbilityContext): string {
    this.ddo = distributedDataObject.create(ctx, this.state);
    const sessionId: string = distributedDataObject.genSessionId();
    this.ddo.setSessionId(sessionId);      // 对端必须设置成同一个值
    this.ddo.on('change', (sid: string, fields: Array<string>) => {
      // DDO 不会驱动 ArkUI 刷新,必须自己把数据搬回状态变量
      this.onChange(this.state);
    });
    return sessionId;
  }
}

运行结果:A 端改 activeUserId,B 端 change 回调收到字段名;但界面不会自己变,必须把 state 搬进 @Local 或 @ObservedV2 的字段,UI 才刷新。日志证明回调触发了,界面没动,这是两件事。

第四步:权限与声明 ​

json5
// entry/src/main/module.json5 —— 节选
{
  "module": {
    "requestPermissions": [{
      "name": "ohos.permission.DISTRIBUTED_DATASYNC",
      "reason": "$string:reason_distributed",
      "usedScene": { "abilities": ["EntryAbility"], "when": "inuse" }
    }],
    "abilities": [{
      "name": "EntryAbility",
      "srcEntry": "./ets/entryability/EntryAbility.ets",
      "continuable": true
    }]
  }
}

运行结果:编译通过。DISTRIBUTED_DATASYNC 是 user_grant 权限,声明只完成第一步,运行时还要申请;拒绝后 DDO 的会话建立会失败,迁移不受此权限影响。

第五步:按需求选型 ​

把这款笔记应用的五个需求摊开,选择与代价如下。

需求选了什么代价
手机编辑、平板接着编跨端迁移数据 ≤100KB;触发入口由系统控制
传一份导出文件给对端分布式文件需文件 URI 与权限;大文件自己做进度
双端实时标注先做,后删冲突无解,语义与承诺不符
一次性把参数发给对端Want 拉起 + parameters数据量小;对端必须已安装
跨设备拖拽未采用走 UDMF,与 DDO 无关

运行结果:最终上线的是迁移与文件传输。双端标注在内部演示时暴露了问题——两台设备同时划线,投影上很流畅,演示结束核对数据,B 端少了两笔。不是丢了,是被后到的写入覆盖了。

冲突这件事试过两条路:给字段加时间戳做后写覆盖,按端拆字段(A 端只写 strokesA,B 端只写 strokesB)。都能缓解,但都没有回答“用户看到的是不是同一份”。

设备组合也要提前说清。手机与平板之间的迁移与协同支持最完整,车机、智慧屏、穿戴要看具体机型与系统版本,没有统一的兼容矩阵可查,只能真机组合验证。三次模拟器都正常、只在特定平板上复现的 bug,确实出现过。

常见误解 ​

以为分布式 API 可以当 RPC 用。 它只复制状态,不保证顺序、不做冲突裁决。用它做“两端同时编辑同一段文字”,得到的是“尽力同步”,而用户理解的是“实时协作”,两句话差得很远。用它同步“当前选中项”“一个共享开关”这类低频、幂等的状态,才合适。

以为应用可以放个按钮发起迁移。 迁移入口在系统侧,应用只能通过 continuable 声明能力、在 onContinue 里决定去留,再用 setMissionContinueState 控制哪些页面可迁。产品评审时要把这条说在前面,否则会收到“为什么不能像投屏一样点一下就过去”的质疑。

以为 DDO 一变,界面就会刷新。 change 只是通知,ArkUI 不会因为 DDO 变了就重绘。数据必须搬进 @Local 或 @ObservedV2,这是两套机制。以为回调没触发而加日志,最后发现触发了、只是没人告诉界面。

小结 ​

  • 软总线只做发现、连接、传输、加密;四样 API 都只是“把状态复制过去”,一致性归业务。
  • 设备列表为空先查三件事:同账号、已互认证、两端已安装;接口不会报错。networkId 不能当业务主键。
  • 迁移由系统触发,应用负责声明与决策:continuable、onContinue 的返回值、SOURCE_EXIT、launchReason 分流与 onNewWant。
  • DDO 的 sessionId 要靠业务信令同步;数据类型受限,敏感数据不该走它;change 不等于 UI 刷新。
  • 分布式文件适合一次性传输,不适合高频小数据;设备组合必须用真机验证,模拟器跑通不代表能上线。

相关主题 ​

分布式能力把状态送到了第二台设备,也让“这台设备上到底装了什么”变复杂:多设备形态、多模块、多份签名配置。相关文章进入[《构建与发布:hvigor、多模块与上架》 构建与发布](/guide/harmonyos/harmonyos-hvigor-build.html),把 hvigor 配置、HAP/HSP/HAR 的模块拆分与上架流程收拢成一条可重复的构建链路。