分布式数据（DistributedData）使用指导
分布式数据组件 - 跨设备数据同步与存储。 鸿蒙独有组件，基于 DistributedDataManager API。
运行前提与搭建步骤
这些案例在包含该组件的鸿蒙 AI 伴侣或 HAP 中运行。Android 侧是供网页编辑器生成积木的声明，不能用安卓伴侣验证鸿蒙系统能力。
- 在设计器拖入
DistributedData，保留名称DistributedData1；拖入案例涉及的按钮、文本输入框以及一个标签标签1，按代码中的名称重命名。 - 根据下面的业务说明准备素材、JSON 或系统目标。案例中的按钮代表分步操作，先等初始化、加载或创建成功，再执行下一步。
- 接住完成事件与错误事件，将原始 JSON 或错误显示在标签。先确认原始结果，再编写业务处理。
先等 StoreOpened 再使用存储。跨设备测试要满足同应用、可信设备与相同会话等系统条件；本地 Get 成功不等于远端同步成功。
案例一：写入并读取键值
各案例独立使用；组合到同一屏幕时，将同名事件的处理合并到一个事件积木中。
when Screen1.Initialize() {
DistributedData1.Initialize("demo_store")
}
when DistributedData1.StoreOpened() {
DistributedData1.Put("message", "你好")
标签1.Text = DistributedData1.Get("message")
}
when DistributedData1.Error(错误信息) {
标签1.Text = 错误信息
}
案例二：创建同步对象
when 按钮_同步对象.Click() {
DistributedData1.CreateSyncObject("message", 文本输入框1.Text)
DistributedData1.JoinSession(文本输入框_会话.Text)
}
when DistributedData1.ObjectChanged(键, 值) {
标签1.Text = join(键, "：", 值)
}
参数与返回值速查
JSON 参数是文本，不能直接传字典；需要字典时可用 Web 客户端的 JSON 解码积木转换返回文本。完整默认值与类型见组件参考。
| 方法或事件 | 参数与用途 |
|---|---|
创建同步对象（键，值）（CreateSyncObject） |
键：文本, 值：文本。创建一个支持跨设备同步的数据对象。 |
删除（键）（Delete） |
键：文本。从分布式数据存储中删除指定键的数据。 |
执行GET请求（键）（Get） |
键：文本。从分布式数据存储中获取指定键对应的值。 |
获取数据（GetEntries） |
无参数。获取分布式数据存储中的所有数据条目，返回JSON格式。 |
获取对象值（键）（GetObjectValue） |
键：文本。获取同步对象的当前值。 |
初始化（存储ID）（Initialize） |
存储ID：文本。初始化分布式数据存储，创建或打开指定ID的数据存储。 |
加入会话（会话ID）（JoinSession） |
会话ID：文本。加入指定的数据同步会话。 |
离开会话（LeaveSession） |
无参数。离开当前的数据同步会话。 |
写入（键，值）（Put） |
键：文本, 值：文本。向分布式数据存储中写入一条键值对数据。 |
设置对象值（键，值）（SetObjectValue） |
键：文本, 值：文本。更新同步对象的值，变化会自动同步到其他设备。 |
同步到设备（设备ID）（SyncToDevice） |
设备ID：文本。手动将数据同步到指定的远程设备。 |
数据改变时（键，值）（DataChanged） |
键：文本, 值：文本。分布式数据发生变化时触发。 |
出错时（错误信息）（Error） |
错误信息：文本。发生错误时触发，返回错误信息。 |
对象变化时（键，值）（ObjectChanged） |
键：文本, 值：文本。同步对象的值发生变化时触发。 |
存储已打开时（StoreOpened） |
无参数。分布式数据存储成功打开时触发。 |
同步完成时（结果）（SyncComplete） |
结果：文本。跨设备数据同步完成时触发，返回同步结果。 |
同步状态变化时（状态）（SyncStatusChanged） |
状态：文本。数据同步状态发生变化时触发。 |
常见问题与验收
| 现象 | 检查与预期 |
|---|---|
| 安卓运行没有结果 | 切换到鸿蒙伴侣或 HAP；Android 的声明不会执行该鸿蒙系统能力。 |
| 方法已调用但界面没变化 | 生成 JSON 的方法只是构建数据；按业务流程交给渲染、启动或同步入口，不能将数据生成当成系统操作完成。 |
| 初始化、权限或设备失败 | 记录错误事件，确认系统服务、授权、目标应用或设备可用；只在成功事件后继续下一步。 |
| JSON 解析失败 | 使用上一组件的原始输出，检查引号和字段类型；空对象用于默认模板演示，不能代替真实目标信息。 |
| 两个案例验收 | 每个按钮单独操作一次，核对对应返回或事件；输入错误目标或取消操作时查看失败事件，不应显示成功提示。 |
扫码添加客服咨询
