分布式能力:跨设备流转与协同
本篇要点:能判断一个跨设备需求该用迁移、数据对象还是文件,并在设计阶段说清它的失败语义。 前置文章:《性能优化:布局、长列表与帧率分析》把单机页面调到了 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 可以把对象存到对端,但对端不在线时不会排队。目前可行的做法是自己做一层本地落库、变更日志、上线后拉取差量,这套逻辑不依赖软总线。
动手实践
第一步:把设备列表跑出来
// 前提: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 里补上释放即可。
第二步:写迁移的源端与目标端
// 源端: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。
// 目标端:只写 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 只在热启动这条路径上出现,而测试通常先杀应用再测,所以容易漏。
第三步:用数据对象同步一个共享状态
// 前提: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 才刷新。日志证明回调触发了,界面没动,这是两件事。
第四步:权限与声明
// 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 的模块拆分与上架流程收拢成一条可重复的构建链路。