尼克森HarmonyOS 5
HarmonyOS 应用如何实现多设备之间的流转与协同?
想做多设备协同(如手机上编辑、平板上继续),了解到有 分布式数据管理、跨端迁移(Continuation)、多端协同 几种方式,但不太清楚:
1. 应用接续(Continuation)和分布式数据对象分别适用什么场景?
2. 是否需要所有设备登录同一华为账号并且开启分布式开关?
3. 有没有官方推荐的完整示例(如 onContinue 保存状态 + 对端恢复)?
希望有经验的开发者指点一下,感谢。
Mandelx Hemen
橙动创意“手机编辑后去平板继续”先选应用接续;两端同时编辑才进一步考虑多端协同及冲突合并。分布式数据对象是迁移/协同的数据通道,不是长期数据库。源端可在 onContinue 保存最小业务状态,例如:
onContinue(wantParam: Record<string, Object>): AbilityConstant.OnContinueResult {
wantParam['documentId'] = this.documentId;
return AbilityConstant.OnContinueResult.AGREE;
}放在现有 UIAbility 中,AbilityConstant 来自 AbilityKit;目标端冷启动和已存在实例被拉起都要恢复,并校验文档仍可访问。按所选接续方案核对同账号、设备组网和权限等前提,不要把所有分布式能力一概当成相同条件;大正文只传 ID/持久位置,别全塞 Want。
飞b6结论:HarmonyOS 的应用接续(Continuation)和分布式数据对象不是互相替代的技术,而是可以组合使用的两种能力。
对于“手机正在编辑文档,切换到平板继续编辑”,优先采用 应用接续 + onContinue() 保存状态 + 目标设备 onCreate() / onNewWant() 恢复。如果还需要手机和平板同时编辑、实时同步,再引入分布式数据对象。
一、三种跨设备能力怎么选?
| 能力 | 核心作用 | 适用场景 |
|---|---|---|
| 应用接续(Continuation) | 将当前任务从设备 A 接续到 B | 手机编辑一半,平板接着编辑 |
| 分布式数据对象 | 不同设备的同一会话共享数据状态 | 双端同步标题、编辑进度、业务状态 |
| 多端协同 | 多设备同时参与同一业务 | 手机拍照、平板编辑;双设备协作 |
官方将跨端迁移与多端协同统一归为“自由流转”,而分布式数据对象是其中一种数据同步手段

二、设备需要满足哪些条件?
针对系统提供的应用接续能力,官方目前要求:
-
两台设备登录同一华为账号。
-
开启 WLAN 和蓝牙,或满足官方规定的多设备协同增强服务条件。
-
在系统设置中开启 多设备协同 → 接续。
-
双端都安装同一应用,并满足设备、系统版本兼容要求。
-
使用支持应用接续的真实设备;模拟器目前不支持该功能。
从 API 12 起,普通应用接续无需额外申请 ohos.permission.DISTRIBUTED_DATASYNC 权限。
需要注意:多端协同不等于应用接续。 如果通过跨设备 startAbilityByCall() 实现多端协同,官方仍要求相应的分布式数据同步权限及其他配置,不能直接套用应用接续的免权限规则。
三、最小示例:onContinue 保存,目标设备恢复
1. 启用 UIAbility 接续
在 entry/src/main/module.json5 对应的 Ability 配置中增加:
{
"name": "EntryAbility",
"srcEntry": "./ets/entryability/EntryAbility.ets",
"continuable": true
}以上是 abilities 数组中的单项配置,不要直接替换整个 module.json5。
2. 定义接续数据
建议只保存关键业务状态:
export interface EditorSnapshot {
version: number;
documentId: string;
cursorPosition: number;
draftText: string;
}如果草稿比较大,应采用分布式数据对象、文件资产或其他同步方式,而不是将整篇长文直接塞入 Want。
3. 在源端实现 onContinue
以下是简化的 EntryAbility 结构:
import {
UIAbility,
AbilityConstant,
Want
} from '@kit.AbilityKit';
// 示例:由页面编辑操作持续维护的状态
class EditorState {
static snapshot: EditorSnapshot = {
version: 1,
documentId: '',
cursorPosition: 0,
draftText: ''
};
}
interface EditorSnapshot {
version: number;
documentId: string;
cursorPosition: number;
draftText: string;
}
export default class EntryAbility extends UIAbility {
onContinue(
wantParam: Record<string, Object>
): AbilityConstant.OnContinueResult {
const state = EditorState.snapshot;
if (!state.documentId) {
return AbilityConstant.OnContinueResult.REJECT;
}
// 传递可序列化的轻量业务数据
wantParam['editorVersion'] = state.version;
wantParam['documentId'] = state.documentId;
wantParam['cursorPosition'] = state.cursorPosition;
wantParam['draftText'] = state.draftText;
return AbilityConstant.OnContinueResult.AGREE;
}
onCreate(
want: Want,
launchParam: AbilityConstant.LaunchParam
): void {
this.handleContinuation(want, launchParam);
// 此处还需按正常流程创建窗口
}
onNewWant(
want: Want,
launchParam: AbilityConstant.LaunchParam
): void {
this.handleContinuation(want, launchParam);
}
private handleContinuation(
want: Want,
launchParam: AbilityConstant.LaunchParam
): void {
if (launchParam.launchReason !==
AbilityConstant.LaunchReason.CONTINUATION) {
return;
}
const params = want.parameters;
const documentId = params?.['documentId'];
const cursorPosition = params?.['cursorPosition'];
const draftText = params?.['draftText'];
if (typeof documentId !== 'string' ||
typeof cursorPosition !== 'number' ||
typeof draftText !== 'string') {
return;
}
// 将已校验状态交给编辑页的数据管理层
EditorState.snapshot = {
version: 1,
documentId: documentId,
cursorPosition: cursorPosition,
draftText: draftText
};
}
}
这里 EditorState 仅演示状态交接;正式项目建议通过统一 Store 管理,并确保编辑页创建时读取恢复状态、按文档 ID 加载内容后再定位光标。
注意几个容易遗漏的点:
-
onContinue()中的 Want 参数建议控制在 100KB 以下。 -
对端冷启动通常通过
onCreate()恢复;单实例热启动可能走onNewWant()。 -
不要假定目标端已经有源端内存中的
AppStorage、单例或页面实例。 -
接续过程具有系统管理的页面栈恢复机制,如果自己恢复 Navigation,也要避免重复入栈。
这些属于官方接续机制的基本约束。
四、如果还要双端实时编辑,怎么处理?
可以引入分布式数据对象:
两台设备使用同一个 sessionId➡️
创建分布式数据对象并加入会话➡️
监听 change / status 变化➡️
将收到的最新数据映射到本地 UI 状态
但分布式数据对象有实际限制:官方当前说明,在接续场景中单个对象不超过 150KB,在多端协同场景中不超过 500KB;对于复杂类型,通常需要通过重新设置根属性来同步修改,而不是直接修改深层字段。
例如可以同步:
interface EditorSyncState {
documentId: string;
revision: number;
cursorPosition: number;
title: string;
}对于完整 Markdown 文档、图片、附件,不建议每次编辑都同步整个对象。更适合传输文档 ID、增量变更和文件资产,并在业务层处理冲突。
分布式数据对象也不是完整的协同编辑引擎。 如果两台设备同时修改同一段正文,还需要设计版本冲突处理;复杂实时协作可考虑操作日志、OT 或 CRDT。
接续调试时重点检查什么?
建议按下面的顺序验证:
-
双端是否安装同一应用,并启用
continuable: true。 -
双端华为账号、WLAN、蓝牙及系统接续开关是否满足要求。
-
手机编辑页面是否真的触发了
onContinue()。 -
onContinue()是否返回AGREE,参数是否可序列化。 -
平板是否进入
onCreate()或onNewWant(),launchReason是否为CONTINUATION。 -
编辑页是否读取恢复状态,并正确重建页面内容和光标。
如果配置正常却始终不出现接续入口,要先排查设备发现、系统接续设置、任务激活状态和应用兼容性,而不是一开始就怀疑数据对象同步失败。
最终建议:对于“手机编辑、平板继续”这一需求,先独立打通应用接续。 用 onContinue() 传 documentId、草稿和光标位置,平板恢复编辑界面;待这条链路稳定后,再加入分布式数据对象实现双端实时数据同步。这样实现成本更低,问题也更容易定位。
Z1. 应用接续 vs 分布式数据对象,各自的场景
应用接续解决的是"同一个任务换设备继续干"。系统负责设备发现、连接、页面栈迁移,你只需要在 onContinue 里存数据、在 onCreate/onNewWant 里恢复数据,整个 UIAbility 连带页面栈会迁移到对端。典型场景:手机上编辑备忘录 → 走到电脑前接续编辑。
分布式数据对象不是独立功能,它是应用接续和多端协同的数据迁移手段之一。官方文档明确说了:分布式数据对象只能在跨端迁移和通过跨设备 Call 调用实现多端协同的场景中使用。它本质是一个跨设备自动同步的内存变量,设了相同的 sessionId 就能互相同步,像操作本地变量一样操作远端数据。
简单说选型逻辑:
- 数据 < 100KB 且不含文件 → onContinue 里直接用 wantParam 传,最省事
- 数据 > 100KB 或含文件 → onContinue 里创建分布式数据对象,用 sessionId 关联后再 save 持久化,把 sessionId 通过 wantParam 传到对端恢复
- 两个设备同时操作同一份数据(多端协同,不是迁移) → 用分布式数据对象做实时同步,配合跨设备 Call 调用
2. 是否需要同一华为账号 + 开启开关
是的,应用接续的环境要求来自官方文档约束限制:
- 双端登录同一华为账号
- 双端打开 WLAN 和蓝牙,或者在"设置 > 多设备协同 > 高级"中启用"多设备协同增强服务"
- 双端在"设置 > 多设备协同"中开启接续功能
- 双端都安装了该应用
- 设备版本:HarmonyOS NEXT 及以上
权限方面,API 12 起不再需要 ohos.permission.DISTRIBUTED_DATASYNC,API 11 及之前需要声明并动态申请。
3. 完整示例:onContinue 保存 + 对端恢复
最小可运行 demo,数据量 < 100KB 场景,直接用 wantParam 传递:
module.json5 配置(关键一行):
{
"module": {
"abilities": [
{
"name": "EntryAbility",
"continuable": true
}
]
}
}
EntryAbility.ets:
import { UIAbility, AbilityConstant, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
const DOMAIN: number = 0xFF00;
const TAG: string = 'ContinueDemo';
export default class EntryAbility extends UIAbility {
onContinue(wantParam: Record<string, Object>): AbilityConstant.OnContinueResult {
hilog.info(DOMAIN, TAG, 'onContinue');
wantParam['editText'] = '这是要迁移的编辑内容';
wantParam['cursorPos'] = 5;
return AbilityConstant.OnContinueResult.AGREE;
}
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
hilog.info(DOMAIN, TAG, 'onCreate');
if (launchParam.launchReason === AbilityConstant.LaunchReason.CONTINUATION) {
if (want.parameters !== undefined) {
const editText = want.parameters['editText'] as string;
const cursorPos = want.parameters['cursorPos'] as number;
AppStorage.setOrCreate('editText', editText);
AppStorage.setOrCreate('cursorPos', cursorPos);
}
this.context.restoreWindowStage(new LocalStorage());
}
}
onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void {
hilog.info(DOMAIN, TAG, 'onNewWant');
if (launchParam.launchReason === AbilityConstant.LaunchReason.CONTINUATION) {
if (want.parameters !== undefined) {
const editText = want.parameters['editText'] as string;
const cursorPos = want.parameters['cursorPos'] as number;
AppStorage.setOrCreate('editText', editText);
AppStorage.setOrCreate('cursorPos', cursorPos);
}
this.context.restoreWindowStage(new LocalStorage());
}
}
}
几个容易踩的坑:
- restoreWindowStage 必须在同步调用中执行,放异步回调里页面加载会失败
- 迁移启动走的是 onWindowStageRestore 而非 onWindowStageCreate,如果你在后者做了初始化,记得在 onWindowStageRestore 里也做一遍
- 单实例应用热启动走 onNewWant,冷启动走 onCreate,两个都要处理
- wantParam 里不要用 version 和 targetDevice 做 key,这两个是系统预置字段
AI助手应用接续(Continuation)和分布式数据对象并不是互斥的两种技术,而是经常配合使用的:应用接续负责把“任务”从一台设备迁移到另一台设备(页面栈、上下文、启动原因),分布式数据对象负责把“数据”在设备间同步(内存级状态、大对象、文件资产)。下面分别说明。
一、两者的定位与适用场景
应用接续基于 UIAbility 的跨端迁移能力,核心接口是源端的 onContinue() 与目的端的 onCreate() / onNewWant(),适用于“换设备继续干同一件事”的场景,例如手机上编辑文档、平板上接着编辑。它的特点是:
- 只能在同应用(UIAbility)之间触发,两端设备都需要安装该应用;
- 通过
wantParam传递的数据需要控制在 100KB 以内,适合传递页面路由、索引、滚动位置等轻量状态; - 目的端冷启动/多实例热启动走
onCreate(),单实例应用热启动走onNewWant(),恢复时触发的是onWindowStageRestore()而非onWindowStageCreate(),需要把onWindowStageCreate()中的初始化逻辑在onWindowStageRestore()中做同样处理。
分布式数据对象(@kit.ArkData 中的 distributedDataObject)提供内存对象的跨设备自动同步,适用于:
- 迁移数据超过 100KB 的场景(如文档正文、附件列表),在
onContinue()中创建分布式数据对象、生成 sessionId 并放入wantParam,对端在onCreate()/onNewWant()中用相同 sessionId 加入组网,通过on('status')监听到restored状态后恢复数据; - 多端协同场景(如跨设备 Call 调用拉起对端 Ability 后共享实时状态),两端设置同一 sessionId 即可自动同步;
- 需要注意:它只支持简单结构,不支持嵌套复杂对象、函数和循环引用;并发修改是“后发覆盖先发”,没有内置乐观锁,高并发场景建议业务侧自行加版本号字段。
简单来说:轻量状态直接走 wantParam,大数据/文件走分布式数据对象或分布式文件系统(distributedFilesDir),两者在官方最佳实践中是组合使用的。
二、使用前提条件
是的,需要满足以下条件,缺一不可:
- 两端设备登录同一华为账号;
- 两端设备打开 WLAN 和蓝牙开关,并连接同一局域网(可提升数据传输速度);
- 两端设备在系统设置中开启“多设备协同 > 接续”功能;
- 两端设备都安装了该应用(接续只能在同应用之间触发)。
开发侧还需要完成三项配置:
- 在
module.json5的abilities中将continuable配置为true(默认为false,未配置的 UIAbility 会被系统识别为不可迁移); - 申请权限
ohos.permission.DISTRIBUTED_DATASYNC,并在运行时向用户弹窗申请; - 如需支持同应用不同 BundleName 跨端迁移(同一开发者在不同设备类型上使用不同包名),还需配置
continueType并在应用市场完成接续服务申请。
三、完整示例:onContinue 保存 + 对端恢复
以下示例演示“手机编辑、平板继续”的典型实现,轻量数据走 wantParam,大文本走分布式数据对象,适用于 API 12 及以上版本。
第一步,module.json5 配置:
{
"module": {
"abilities": [
{
"name": "EntryAbility",
"srcEntry": "./ets/entryability/EntryAbility.ets",
"continuable": true
}
],
"requestPermissions": [
{
"name": "ohos.permission.DISTRIBUTED_DATASYNC"
}
]
}
}
第二步,定义迁移数据的模型(避免使用未声明类型的对象字面量):
// model/ContinueData.ets
// 分布式数据对象承载的正文内容,字段需与源端、目的端保持一致
export class DocContent {
title: string = '';
body: string = '';
editVersion: number = 0;
}
第三步,在 EntryAbility 中实现保存与恢复:
// entryability/EntryAbility.ets
import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { distributedDataObject } from '@kit.ArkData';
import { BusinessError } from '@kit.BasicServicesKit';
import { DocContent } from '../model/ContinueData';
export default class EntryAbility extends UIAbility {
private dataObject: distributedDataObject.DataObject | undefined = undefined;
// 源端:系统发起迁移时回调,在此保存状态
onContinue(wantParam: Record<string, Object>): AbilityConstant.OnContinueResult {
// 轻量数据(页面路由、光标位置等)直接放入 wantParam,需控制在 100KB 以内
wantParam.currentPage = 'DocEditPage';
wantParam.cursorOffset = 128;
// 大文本数据使用分布式数据对象迁移
const content: DocContent = new DocContent();
content.title = AppStorage.get<string>('docTitle') ?? '';
content.body = AppStorage.get<string>('docBody') ?? '';
content.editVersion = AppStorage.get<number>('editVersion') ?? 0;
this.dataObject = distributedDataObject.create(this.context, content);
// 生成组网 sessionId,两端使用同一 sessionId 即可同步
const sessionId: string = distributedDataObject.genSessionId();
this.dataObject.setSessionId(sessionId);
// 将 sessionId 放入 wantParam,目的端据此加入组网
wantParam.distributedSessionId = sessionId;
// 返回 AGREE 表示同意迁移;异常时可返回 REJECT,版本不匹配可返回 MISMATCH
return AbilityConstant.OnContinueResult.AGREE;
}
// 目的端:冷启动或多实例热启动时恢复
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
this.restoreFromContinuation(want, launchParam);
// 正常启动时的窗口加载逻辑
}
// 目的端:单实例应用热启动时恢复
onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void {
this.restoreFromContinuation(want, launchParam);
}
private restoreFromContinuation(want: Want, launchParam: AbilityConstant.LaunchParam): void {
// 仅在接续场景下执行恢复,避免普通启动误触发
if (launchParam.launchReason !== AbilityConstant.LaunchReason.CONTINUATION) {
return;
}
// 恢复轻量数据
const currentPage: string = want.parameters?.currentPage as string;
const cursorOffset: number = want.parameters?.cursorOffset as number;
AppStorage.setOrCreate<string>('continuePage', currentPage);
AppStorage.setOrCreate<number>('cursorOffset', cursorOffset);
// 创建空的分布式数据对象用于接收数据
const content: DocContent = new DocContent();
this.dataObject = distributedDataObject.create(this.context, content);
// 监听恢复状态,restored 表示数据已从源端同步到位
this.dataObject.on('status', (sessionId: string, networkId: string,
status: 'online' | 'offline' | 'restored') => {
if (status === 'restored' && this.dataObject) {
AppStorage.setOrCreate<string>('docTitle', this.dataObject['title'] as string);
AppStorage.setOrCreate<string>('docBody', this.dataObject['body'] as string);
AppStorage.setOrCreate<number>('editVersion', this.dataObject['editVersion'] as number);
}
});
// 使用源端传入的 sessionId 加入组网,触发数据同步
const sessionId: string = want.parameters?.distributedSessionId as string;
this.dataObject.setSessionId(sessionId).catch((err: BusinessError) => {
console.error(`setSessionId failed, code: ${err.code}, message: ${err.message}`);
});
}
// 接续场景下触发的是 onWindowStageRestore 而非 onWindowStageCreate
onWindowStageRestore(): void {
// 将 onWindowStageCreate 中的必要初始化逻辑在此同样执行,避免应用异常
this.context.restoreWindowStage(new LocalStorage());
}
}
第四步,页面侧根据恢复的状态渲染界面:
// pages/DocEditPage.ets
import { AppStorage } from '@kit.ArkUI';
@Entry
@Component
struct DocEditPage {
@StorageLink('docTitle') docTitle: string = '';
@StorageLink('docBody') docBody: string = '';
@StorageLink('cursorOffset') cursorOffset: number = 0;
build() {
Column() {
TextInput({ text: this.docTitle })
.onChange((value: string) => {
this.docTitle = value;
})
TextArea({ text: this.docBody })
.onChange((value: string) => {
this.docBody = value;
})
}
}
}
四、补充说明
关于官方完整示例,推荐参考开发者官网的最佳实践系列文档:《应用接续概述》《应用接续数据迁移》《常见接续最佳实践》《社交通讯全场景协同最佳实践》《ai辅助图文内容编创》,其中包含了从配置、onContinue 保存、对端 onCreate / onNewWant 恢复到文件资产迁移的完整可运行代码,可直接对照实现。
几个容易踩坑的点:一是 onContinue() 返回 MISMATCH 可用于两端应用版本不一致时的协商拒绝;二是接续恢复时不会走 onWindowStageCreate(),漏配 onWindowStageRestore() 的初始化会导致目的端页面白屏或异常;三是分布式数据对象实例建议托管在 UIAbility 内作为全局唯一实例,页面只订阅监听,页面销毁时注意取消订阅,避免监听句柄残留导致回调丢失或重复触发;四是多设备同时编辑时分布式数据对象没有内置冲突保护,建议在数据模型中增加版本号字段做脏写防护。
lovoyd1. 应用接续(Continuation)vs 分布式数据对象
应用接续:适合串行任务,如手机上编辑文档→切到平板继续编辑。核心是 onContinue 保存业务状态,目标设备在 onCreate/onNewWant 恢复状态,实现无感切换。适合视频播放、文档编辑、阅读类场景。
分布式数据对象(Distributed Data Object):适合并行协同,多台设备同时操作同一份数据,通过 sessionId 标识实现跨设备实时同步。适合双端同时编辑同一笔记、聊天调用其他设备文件等场景。
2. 账号与开关要求
参与流转的设备需要登录同一华为账号,并在超级终端中完成组网(开启蓝牙和 WLAN)。
部分能力(如碰一碰、隔空传送)需要 NFC/蓝牙硬件支持;部分协同能力仅支持平板、二合一设备。
3. 官方推荐示例
官方有完整的应用接续开发指导,核心流程:源设备在 onContinue 回调中序列化保存业务状态 → 目标设备在 onCreate 或 onNewWant 中恢复状态 → 系统自动完成设备发现和状态传输。
大文件不建议直接传输,建议走文件 URI 由远端按需拉取;迁移只传业务状态,不传大体积二进制数据。
选型建议:串行任务(编辑、播放)用应用接续;并行任务(双端协同操作)用分布式数据对象。两者可结合使用,具体看业务是"接力"还是"协作"。
- 为了保障您的信息安全,请勿上传您的敏感个人信息(如您的密码等信息)和您的敏感资产信息(如关键源代码、签名私钥、调试安装包、业务日志等信息),且您需自行承担由此产生的信息泄露等安全风险。
- 如您发布的内容为转载内容,请注明内容来源。
我要提问题
HarmonyOS 手机和平板之间如何实现跨设备协同编辑?(API12+)
【开发者实践】打通设备边界-多设备协同实践精品文章专题
HarmonyOS HarmonyOS系统是分布式结构,能提高性能是指在多个设备协同工作,多节点并行从而提高处理速度,这个具体是指哪部分?(API12+)
HarmonyOS 多人协同开发中如何动态配置签名(API12+)
HarmonyOS 分布式迁移 @ObservedV2 装饰的 Class 实例无法续接到其他设备 (API12+)
HarmonyOS 应用如何去适配手机、折叠屏和平板用户(API12+)
HarmonyOS APP开发-多工程构建 (API12+)
HarmonyOS 如何实现APP端当做服务端,其他设备访问?(API12+)




































苏公安网备 32011402010933号