鸿蒙桥接（HarmonyBridge）使用指导
鸿蒙桥接组件 - Want 桥接，用于原子服务、服务卡片和无缝流转入口。 鸿蒙独有组件，可构建 Want 快照并直接启动目标 Ability。
运行前提与搭建步骤
这些案例在包含该组件的鸿蒙 AI 伴侣或 HAP 中运行。Android 侧是供网页编辑器生成积木的声明，不能用安卓伴侣验证鸿蒙系统能力。
- 在设计器拖入
HarmonyBridge，保留名称HarmonyBridge1；拖入案例涉及的按钮、文本输入框以及一个标签标签1，按代码中的名称重命名。 - 根据下面的业务说明准备素材、JSON 或系统目标。案例中的按钮代表分步操作，先等初始化、加载或创建成功，再执行下一步。
- 接住完成事件与错误事件，将原始 JSON 或错误显示在标签。先确认原始结果，再编写业务处理。
包名和 Ability 填实际可访问的已安装目标；{} 是空参数 JSON。WantPrepared 只表示构建完成，LaunchSucceeded 才表示启动调用成功。
案例一：构建目标 Want
各案例独立使用；组合到同一屏幕时，将同名事件的处理合并到一个事件积木中。
when 按钮_构建.Click() {
标签1.Text = HarmonyBridge1.PrepareAtomicServiceWant(文本输入框_包名.Text, 文本输入框_Ability.Text, "home", "{}")
}
案例二：启动已安装 Ability
when 按钮_启动.Click() {
HarmonyBridge1.LaunchAbility(文本输入框_包名.Text, 文本输入框_Ability.Text, "{}")
}
when HarmonyBridge1.LaunchSucceeded(种类, 启动请求JSON) {
标签1.Text = "启动成功"
}
when HarmonyBridge1.LaunchFailed(种类, 消息) {
标签1.Text = 消息
}
参数与返回值速查
JSON 参数是文本，不能直接传字典；需要字典时可用 Web 客户端的 JSON 解码积木转换返回文本。完整默认值与类型见组件参考。
| 方法或事件 | 参数与用途 |
|---|---|
获取最近错误（GetLastError） |
无参数。获取最近一次启动失败的错误信息。 |
获取最近Want JSON（GetLastWantJson） |
无参数。获取最近一次准备或启动的 Want 快照 JSON。 |
启动Ability（包名，能力名，参数JSON）（LaunchAbility） |
包名：文本, 能力名：文本, 参数JSON：文本。使用给定的包名、Ability 名称和参数 JSON 立即启动目标 Ability。 |
启动Want JSON（启动请求JSON）（LaunchWantJson） |
启动请求JSON：文本。启动之前准备好的 Want 快照 JSON。 |
准备原子服务Want（包名，能力名，入口路径，数据JSON）（PrepareAtomicServiceWant） |
包名：文本, 能力名：文本, 入口路径：文本, 数据JSON：文本。构建适用于原子服务轻入口场景的 Want 快照。 |
准备卡片Want（卡片ID，路由名，数据JSON）（PrepareCardWant） |
卡片ID：文本, 路由名：文本, 数据JSON：文本。构建适用于卡片点击跳转和卡片恢复场景的 Want 快照。 |
准备流转Want（目标设备类型，能力名，数据JSON）（PrepareContinuationWant） |
目标设备类型：文本, 能力名：文本, 数据JSON：文本。构建适用于流转和多设备接续场景的 Want 快照。 |
启动失败时（种类，消息）（LaunchFailed） |
种类：文本, 消息：文本。桥接组件无法启动 Want 时触发。 |
启动成功时（种类，启动请求JSON）（LaunchSucceeded） |
种类：文本, 启动请求JSON：文本。startAbility 调用成功后触发。 |
Want已准备时（种类，启动请求JSON）（WantPrepared） |
种类：文本, 启动请求JSON：文本。组件完成 Want 快照准备后触发。 |
常见问题与验收
| 现象 | 检查与预期 |
|---|---|
| 安卓运行没有结果 | 切换到鸿蒙伴侣或 HAP；Android 的声明不会执行该鸿蒙系统能力。 |
| 方法已调用但界面没变化 | 生成 JSON 的方法只是构建数据；按业务流程交给渲染、启动或同步入口，不能将数据生成当成系统操作完成。 |
| 初始化、权限或设备失败 | 记录错误事件，确认系统服务、授权、目标应用或设备可用；只在成功事件后继续下一步。 |
| JSON 解析失败 | 使用上一组件的原始输出，检查引号和字段类型；空对象用于默认模板演示，不能代替真实目标信息。 |
| 两个案例验收 | 每个按钮单独操作一次，核对对应返回或事件；输入错误目标或取消操作时查看失败事件，不应显示成功提示。 |
完整 .aia 源码与操作指导
鸿蒙桥接载体准备→查看与复制真实Want JSON→显式启动实际已安装Ability→读取真实提交结果、事件与最近错误。默认目标是本仓库鸿蒙伴侣，导入即可准备数据；启动只在用户确认后执行。准备卡片或流转Want不表示已经注册卡片或完成跨设备流转。
导入 HarmonyBridgeAllFeatures.aia，连接最新伴侣，或编译独立安装包。真机／伴侣运行尚未实测。
| API / 功能 | 操作入口 | 预期结果 |
|---|---|---|
| DefaultBundleName、DefaultAbilityName读写及设计器配置 | 默认配置输入后应用 | 真正设置并读回；默认cn.fun123.ohappinventor/EntryAbility是仓库伴侣实际标识 |
| PrepareAtomicServiceWant、PrepareCardWant、PrepareContinuationWant、WantPrepared | 三种准备入口、Want输入、复制 | 实际JSON和kind；构建载体，不注册原子服务／卡片，也不执行远端流转 |
| LastWantJson、GetLastWantJson、LastError、GetLastError | 每次准备／启动后及读取按钮 | 读取真实最近快照与错误；不存在成功时不填入模拟数据 |
| LaunchAbility、LaunchWantJson、LaunchSucceeded、LaunchFailed | 勾选确认，启动已安装伴侣或自己的导出Ability | 返回值表示提交请求；系统实际启动由事件反映，目标业务完成需自己的确认协议 |
| JSON、空输入、非法Want与恢复 | 非法Want按钮；空包名；修正后再次准备启动 | 非法JSON不启动，返回假并展示实际原因；填写真实目标后可重试 |
| 平台与目标要求 | 鸿蒙导入，伴侣已安装；独立包也可启动伴侣 | Android为接口占位；外部Ability必须允许当前应用访问，找不到如实失败 |
所有返回值均用于界面反馈，错误由底部错误区展示。设计器采用明确非默认配置，初始化与界面同步。API 覆盖检查按最终 AIA 检查方法、事件、属性读取与设置及设计器配置，不能替代真实设备验证。
鸿蒙Want桥接与启动
导入方法：项目 → 导入项目（.aia）→ 选择下载的 .aia 源码文件。 鸿蒙桥接载体准备→查看与复制真实Want JSON→显式启动实际已安装Ability→读取真实提交结果、事件与最近错误。默认目标是本仓库鸿蒙伴侣，导入即可准备数据；启动只在用户确认后执行。准备卡片或流转Want不表示已经注册卡片或完成跨设备流转。 覆盖检查 18/18。首次载入及保存重开均0个错误，真实后台导入、安装包编译通过；真机／伴侣／硬件联调尚未实测。全部属性读写、方法与事件的操作入口和预期结果见组件指导。
扫码添加客服咨询
