第十四章：分布式能力与跨端流转
本章配套代码：
code/Chapter14（设备发现与流转模拟 Demo） 前置要求：已完成数据存储、网络、端云一体化章节
14.1 学习目标
- 理解 HarmonyOS 分布式能力的概念与价值
- 掌握分布式数据同步（DeviceKVStore）
- 了解跨端流转（应用迁移）
- 通过模拟 Demo 理解设备发现与流转流程
14.2 分布式能力概述
HarmonyOS 的分布式 能力实现多设备协同，是操作系统级能力（非 App 内实现）。
┌──────────────────────────────────────────────┐
│ HarmonyOS 分布式能力 │
│ │
│ 分布式软总线（设备发现与连接） │
│ 分布式数据（多设备数据同步） │
│ 分布式任务（跨设备任务调度） │
│ 应用流转（应用状态跨端迁移） │
│ │
│ ┌────────┐ 软总线 ┌────────┐ │
│ │ 手机 │ ◄──────────► │ 平板 │ │
│ └────────┘ └────────┘ │
└──────────────────────────────────────────────┘
| 能力 | 说明 | 典型场景 |
|---|---|---|
| 分布式软总线 | 设备自动发现、组网、连接 | 多设备互联 |
| 分布式数据 | 数据跨设备自动同步 | 笔记多端一致 |
| 应用流转 | 应用状态跨端迁移 | 手机→平板继续阅读 |
| 分布式任务 | 跨设备调用能力 | 手机投屏到电视 |
14.3 分布式数据同步
14.3.1 概念
分布式键值数据库（DEVICE_COLLABORATION 类型）自动在多设备间同步数据。
┌────────────┐ 数据自动同步 ┌────────────┐
│ 手机 │ ◄────────────► │ 平板 │
│ KVStore │ │ KVStore │
└────────────┘ └────────────┘
数据写入一端，其他设备自动同步
14.3.2 使用示例
import { distributedKVStore } from '@kit.ArkData'
class DistributedDataUtil {
private kvStore: distributedKVStore.DeviceKVStore | undefined
async init(context: Context, storeName: string): Promise<void> {
const kvManagerConfig: distributedKVStore.KVManagerConfig = {
context,
bundleName: context.applicationInfo.name as string
}
const kvManager = distributedKVStore.createKVManager(kvManagerConfig)
const options: distributedKVStore.Options = {
createIfMissing: true,
encrypt: false,
backup: false,
autoSync: true, // 启用自动同步（关键）
kvStoreType: distributedKVStore.KVStoreType.DEVICE_COLLABORATION,
securityLevel: distributedKVStore.SecurityLevel.S1
}
this.kvStore = await kvManager.getKVStore<distributedKVStore.DeviceKVStore>(
storeName, options
)
}
async put(key: string, value: string | number | boolean): Promise<void> {
await this.kvStore?.put(key, value)
}
async get(key: string): Promise<string | number | boolean | undefined> {
return await this.kvStore?.get(key)
}
async syncToAllDevices(): Promise<void> {
await this.kvStore?.sync([
{
deviceId: '*', // 所有在线设备
mode: distributedKVStore.SyncMode.PUSH_AND_PULL
}
])
}
}
export default DistributedDataUtil
与普通 KVStore 的区别：
| 对比 | SingleKVStore | DeviceKVStore |
|---|---|---|
kvStoreType | SINGLE_VERSION | DEVICE_COLLABORATION |
autoSync | false | true |
| 数据同步 | 本地 | 多设备自动同步 |
| 适用 | 本地缓存 | 分布式数据 |
⚠️ 分布式能力需要设备登录同一华为账号、连接同一网络/可信环境。
14.4 跨端流转（应用迁移）
14.4.1 概念
应用流转：在源设备保存应用状态，迁移到目标设备继续运行。
手机播放视频 平板继续播放
┌──────────┐ 流转 ┌──────────┐
│ 视频页 │ ───────► │ 视频页 │
│ 进度50% │ │ 进度50% │
└──────────┘ └──────────┘
应用状态 + 页面栈 一起迁移
两种流转方式：
| 方式 | 说明 |
|---|---|
| 跨端迁移 | 源端停止，目标端接管（续播/续读） |
| 多端协同 | 两端共存，能力互补（手机遥控电视） |
14.4.2 基本流程
- 源设备：保存应用状态（写入分布式数据或迁移能力）
- 发起流转：调用分布式任务接口发起迁移
- 目标设备：接收并恢复应用状态
14.5 综合示例：设备发现与流转
对应 code/Chapter14 的 Index.ets，模拟设备发现与流转过程：
@Entry
@ComponentV2
struct Index {
@Local deviceInfo: string = 'Current device: Phone'
@Local transferStatus: string = 'Not transferred'
@Local message: string = '海内存知己，天涯若比邻'
discoverDevices() {
this.deviceInfo =
'Discovered devices:\n- Phone (Local)\n- Tablet (Available)\n- Smart Screen (Available)'
}
async transferToDevice(target: string) {
this.transferStatus = `Transferring to ${target}...`
await new Promise(resolve => setTimeout(resolve, 1000))
this.transferStatus = `Transferred to ${target}`
}
build() {
Column({ space: 16 }) {
Text('Chapter 14: Distribution Capability')
.fontSize(24)
.fontWeight(FontWeight.Bold)
// 设备信息
Column({ space: 8 }) {
Text(this.deviceInfo)
.fontSize(14)
.whiteSpace(WhiteSpace.Pre)
}
.width('100%')
.padding(12)
.backgroundColor(Color.White)
.borderRadius(8)
.alignItems(HorizontalAlign.Start)
// 操作按钮
Row({ space: 12 }) {
Button('Discover')
.onClick(() => this.discoverDevices())
Button('To Tablet')
.onClick(() => this.transferToDevice('Tablet'))
Button('To Screen')
.onClick(() => this.transferToDevice('Smart Screen'))
}
// 状态
Row() {
Text('Status: ').fontSize(14)
Text(this.transferStatus)
.fontSize(14)
.fontColor(this.transferStatus.includes('Transferred') ? '#00A86B' : '#007DFF')
}
}
.width('100%')
.height('100%')
.padding(16)
.backgroundColor('#f5f5f5')
}
}
运行效果：
- 点击 "Discover"：展示发现的设备列表（模拟软总线设备发现）
- 点击 "To Tablet"/"To Screen"：模拟流转，状态显示"Transferring..." → "Transferred to xxx"
- 状态颜色随流转完成变绿
运行效果截图：
🔧 升级为真实分布式：真实场景使用分布式软总线（
@kit.DistributedServiceKit）发现设备、分布式数据（DeviceKVStore）同步状态、分布式任务/应用迁移能力发起流转。本章模拟 Demo 用于理解流程与状态管理。
14.6 分布式开发的注意事项
安全考虑：
| 事项 | 说明 |
|---|---|
| 设备认证 | 需登录同一华为账号、可信组网 |
| 数据加密 | 敏感数据加密存储同步 |
| 用户授权 | 跨设备操作需用户确认 |
| 权限申请 | 使用分布式能力需申请相应权限 |
性能考虑：
| 事项 | 说明 |
|---|---|
| 数据量控制 | 减少同步数据量 |
| 同步频率 | 合理设置，避免频繁同步 |
| 异常处理 | 处理设备离线、网络异常 |
| 冲突解决 | 使用版本号/时间戳策略 |
14.7 常见问题
Q：如何保证多设备数据一致性？ 使用版本控制和冲突解决策略（时间戳/版本号），DeviceKVStore 内置同步机制。
Q：设备离线时如何处理？ 实现本地缓存（Preferences/KVStore），设备上线后自动同步。
Q：分布式能力需要什么前提？ 设备登录同一华为账号、开启蓝牙/WLAN 组成可信网络、应用安装于各设备。
Q：模拟 Demo 与真实流转的差距？
模拟 Demo 演示 UI 与流程；真实流转调用 @kit.DistributedServiceKit 的软总线发现与流转接口。
14.8 本章小结
| 知识点 | 说明 |
|---|---|
| 分布式软总线 | 设备发现与连接 |
| DeviceKVStore | 多设备数据自动同步 |
| 应用流转 | 应用状态跨端迁移 |
| 多端协同 | 两端能力互补 |
| 模拟 Demo | 理解流程与状态管理 |
14.9 课后练习
- 理解分布式数据同步原理，梳理 DeviceKVStore 同步流程
- 调研应用迁移（continuation）的两种实现方式
- 将待办事项应用升级为分布式版本（多设备同步）
- 思考分布式应用的安全设计模式
- 将练习整合进
Chapter14/Index.ets