鸿蒙流转（HarmonyFlow）使用指导
鸿蒙流转组件 - 流转载荷构建，用于原子服务路由、服务卡片和跨设备流转。 鸿蒙独有组件，支持状态缓存、状态包导入导出以及流转命令构建。
运行前提与搭建步骤
这些案例在包含该组件的鸿蒙 AI 伴侣或 HAP 中运行。Android 侧是供网页编辑器生成积木的声明，不能用安卓伴侣验证鸿蒙系统能力。
- 在设计器拖入
HarmonyFlow，保留名称HarmonyFlow1；拖入案例涉及的按钮、文本输入框以及一个标签标签1，按代码中的名称重命名。 - 根据下面的业务说明准备素材、JSON 或系统目标。案例中的按钮代表分步操作，先等初始化、加载或创建成功，再执行下一步。
- 接住完成事件与错误事件，将原始 JSON 或错误显示在标签。先确认原始结果，再编写业务处理。
状态包填写案例一导出的原始 JSON。构建状态包不等于已执行跨设备流转；真正启动目标由桥接或流转组件完成。
案例一：保存页面状态包
各案例独立使用；组合到同一屏幕时，将同名事件的处理合并到一个事件积木中。
when 按钮_保存.Click() {
HarmonyFlow1.SetStateValue("query", 文本输入框1.Text)
标签1.Text = HarmonyFlow1.ExportStatePacket("search", "results")
}
案例二：恢复状态包
when 按钮_恢复.Click() {
HarmonyFlow1.ImportStatePacket(文本输入框_状态包.Text)
}
when HarmonyFlow1.StatePacketImported(数据包JSON) {
标签1.Text = HarmonyFlow1.GetStateValue("query")
}
参数与返回值速查
JSON 参数是文本，不能直接传字典；需要字典时可用 Web 客户端的 JSON 解码积木转换返回文本。完整默认值与类型见组件参考。
| 方法或事件 | 参数与用途 |
|---|---|
构建原子服务载荷（服务ID，入口路径，参数JSON）（BuildAtomicServicePayload） |
服务ID：文本, 入口路径：文本, 参数JSON：文本。构建用于启动或恢复原子服务的路由载荷。 |
构建卡片模型（卡片ID，标题，副标题，路由名）（BuildCardModel） |
卡片ID：文本, 标题：文本, 副标题：文本, 路由名：文本。基于当前状态构建服务卡片模型。 |
构建流转命令（目标设备类型，能力名，数据包JSON）（BuildContinuationCommand） |
目标设备类型：文本, 能力名：文本, 数据包JSON：文本。构建跨设备流转命令封装。 |
清空状态（ClearState） |
无参数。清空当前缓存的全部流转状态。 |
导出状态包（流转名称，路由名）（ExportStatePacket） |
流转名称：文本, 路由名：文本。将当前流转状态导出为可携带的鸿蒙状态包。 |
获取最近载荷（GetLastPayload） |
无参数。获取最近一次生成的载荷。 |
获取状态值（键）（GetStateValue） |
键：文本。按键名读取一项流转状态值。 |
导入状态包（数据包JSON）（ImportStatePacket） |
数据包JSON：文本。导入之前导出的鸿蒙状态包。 |
删除状态值（键）（RemoveStateValue） |
键：文本。按键名删除已保存的状态值。 |
设置状态值（键，值）（SetStateValue） |
键：文本, 值：文本。按键名保存一项流转状态值。 |
载荷已生成时（种类，数据JSON）（FlowPayloadBuilt） |
种类：文本, 数据JSON：文本。每次生成新的载荷封装时触发。 |
状态包已导入时（数据包JSON）（StatePacketImported） |
数据包JSON：文本。导入鸿蒙状态包后触发。 |
常见问题与验收
| 现象 | 检查与预期 |
|---|---|
| 安卓运行没有结果 | 切换到鸿蒙伴侣或 HAP；Android 的声明不会执行该鸿蒙系统能力。 |
| 方法已调用但界面没变化 | 生成 JSON 的方法只是构建数据；按业务流程交给渲染、启动或同步入口，不能将数据生成当成系统操作完成。 |
| 初始化、权限或设备失败 | 记录错误事件，确认系统服务、授权、目标应用或设备可用；只在成功事件后继续下一步。 |
| JSON 解析失败 | 使用上一组件的原始输出，检查引号和字段类型；空对象用于默认模板演示，不能代替真实目标信息。 |
| 两个案例验收 | 每个按钮单独操作一次，核对对应返回或事件；输入错误目标或取消操作时查看失败事件，不应显示成功提示。 |
完整 .aia 源码与操作指导
设备巡检状态的本地闭环：键值写入→导出真实JSON→独立TinyDB备份→修改或清空→重新导入恢复→构建卡片、原子服务和流转载体。初始温度23.5明确是示例输入，未连接硬件。数据包可通过自己的通信组件传递，本组件不自动跨设备发送或启动应用。
导入 HarmonyFlowAllFeatures.aia，连接最新伴侣，或编译独立安装包。真机／伴侣运行尚未实测。
| API / 功能 | 操作入口 | 预期结果 |
|---|---|---|
| SetStateValue、GetStateValue、RemoveStateValue、ClearState、StateSize | 键值输入、读取、删除、确认清空 | 真实内存状态；空值允许，空键拦截；不存在键返回空字符串，不代表空字符串键不存在 |
| ExportStatePacket、ImportStatePacket、StatePacketImported | 导出备份→修改值→清空→读取备份→导入 | 用实际状态包恢复设备与温度；成功导入替换当前状态，非法JSON返回假且原状态保留 |
| BuildAtomicServicePayload、BuildCardModel、BuildContinuationCommand、FlowPayloadBuilt | 三个载体构建入口，流转使用真实已导出包 | 显示实际协议、kind和数据；只构建JSON，不注册服务卡片，不执行远端启动 |
| LastPayload、GetLastPayload | 每次操作后读取最近载荷 | 属性与方法返回真实最近封装；删键／清空不一定更新最近载荷 |
| 本地持久化、复制与另一设备 | 导出存独立TinyDB；重开读取备份；真实JSON粘贴导入 | 本地备份不会自动导入；跨设备通道由用户选择，不能把复制当传输完成 |
| Android与空包 | Android运行；未导出点流转／复制 | Android接口占位不返回有效包；无包先提示，使用鸿蒙才验证实际逻辑 |
所有返回值均用于界面反馈，错误由底部错误区展示。设计器采用明确非默认配置，初始化与界面同步。API 覆盖检查按最终 AIA 检查方法、事件、属性读取与设置及设计器配置，不能替代真实设备验证。
设备巡检状态打包与恢复
导入方法：项目 → 导入项目（.aia）→ 选择下载的 .aia 源码文件。 设备巡检状态的本地闭环：键值写入→导出真实JSON→独立TinyDB备份→修改或清空→重新导入恢复→构建卡片、原子服务和流转载体。初始温度23.5明确是示例输入，未连接硬件。数据包可通过自己的通信组件传递，本组件不自动跨设备发送或启动应用。 覆盖检查 14/14。首次载入及保存重开均0个错误，真实后台导入、安装包编译通过；真机／伴侣／硬件联调尚未实测。全部属性读写、方法与事件的操作入口和预期结果见组件指导。
扫码添加客服咨询
