设备发现（DeviceDiscovery）使用指导
设备发现组件 - 发现局域网内的鸿蒙设备，支持设备绑定与状态监听。 鸿蒙独有组件，基于 DistributedHardware DeviceDiscovery API。
运行前提与搭建步骤
这些案例在包含该组件的鸿蒙 AI 伴侣或 HAP 中运行。Android 侧是供网页编辑器生成积木的声明，不能用安卓伴侣验证鸿蒙系统能力。
- 在设计器拖入
DeviceDiscovery，保留名称DeviceDiscovery1；拖入案例涉及的按钮、文本输入框以及一个标签标签1，按代码中的名称重命名。 - 根据下面的业务说明准备素材、JSON 或系统目标。案例中的按钮代表分步操作，先等初始化、加载或创建成功，再执行下一步。
- 接住完成事件与错误事件，将原始 JSON 或错误显示在标签。先确认原始结果，再编写业务处理。
在支持分布式能力的鸿蒙真机上测试；目标设备可发现、授权与系统服务状态决定扫描结果，不能在安卓伴侣中验证。
案例一：初始化并扫描设备
各案例独立使用；组合到同一屏幕时，将同名事件的处理合并到一个事件积木中。
when Screen1.Initialize() {
DeviceDiscovery1.Initialize()
}
when DeviceDiscovery1.Initialized() {
DeviceDiscovery1.StartDiscovery()
}
when DeviceDiscovery1.DeviceDiscovered(设备JSON) {
标签1.Text = 设备JSON
}
when DeviceDiscovery1.Error(错误信息) {
标签1.Text = 错误信息
}
案例二：停止扫描并查看当前列表
when 按钮_停止.Click() {
DeviceDiscovery1.StopDiscovery()
标签1.Text = DeviceDiscovery1.GetDiscoveredDevices()
}
when DeviceDiscovery1.DiscoveryFailed(原因) {
标签1.Text = join("扫描失败：", 原因)
}
参数与返回值速查
JSON 参数是文本，不能直接传字典；需要字典时可用 Web 客户端的 JSON 解码积木转换返回文本。完整默认值与类型见组件参考。
| 方法或事件 | 参数与用途 |
|---|---|
绑定设备（设备ID）（BindDevice） |
设备ID：文本。绑定指定的设备，绑定后可进行分布式通信。 |
获取设备信息（索引）（GetDeviceInfo） |
索引：数字。根据索引获取已发现设备的详细信息，返回JSON格式。 |
获取已发现设备（GetDiscoveredDevices） |
无参数。获取所有已发现的设备列表，返回JSON格式。 |
获取远端设备名（设备ID）（GetRemoteDeviceName） |
设备ID：文本。根据设备ID获取远程设备的名称。 |
初始化（Initialize） |
无参数。初始化设备发现服务，准备发现周围设备。 |
开始发现（StartDiscovery） |
无参数。开始发现周围局域网内的鸿蒙设备。 |
停止发现（StopDiscovery） |
无参数。停止发现设备。 |
解绑设备（设备ID）（UnbindDevice） |
设备ID：文本。解除与指定设备的绑定关系。 |
设备已绑定时（设备ID）（DeviceBound） |
设备ID：文本。设备绑定成功时触发。 |
发现设备时（设备JSON）（DeviceDiscovered） |
设备JSON：文本。发现新设备时触发，返回设备信息的JSON字符串。 |
设备名改变时（新名称）（DeviceNameChanged） |
新名称：文本。本地设备名称发生变化时触发。 |
设备状态改变时（设备JSON，动作）（DeviceStateChanged） |
设备JSON：文本, 动作：文本。设备状态发生变化时触发。 |
设备已解绑时（设备ID）（DeviceUnbound） |
设备ID：文本。设备解绑成功时触发。 |
发现失败时（原因）（DiscoveryFailed） |
原因：文本。设备发现失败时触发，返回失败原因。 |
出错时（错误信息）（Error） |
错误信息：文本。发生错误时触发，返回错误信息。 |
已初始化时（Initialized） |
无参数。设备发现服务初始化完成时触发。 |
常见问题与验收
| 现象 | 检查与预期 |
|---|---|
| 安卓运行没有结果 | 切换到鸿蒙伴侣或 HAP；Android 的声明不会执行该鸿蒙系统能力。 |
| 方法已调用但界面没变化 | 生成 JSON 的方法只是构建数据；按业务流程交给渲染、启动或同步入口，不能将数据生成当成系统操作完成。 |
| 初始化、权限或设备失败 | 记录错误事件，确认系统服务、授权、目标应用或设备可用；只在成功事件后继续下一步。 |
| JSON 解析失败 | 使用上一组件的原始输出，检查引号和字段类型；空对象用于默认模板演示，不能代替真实目标信息。 |
| 两个案例验收 | 每个按钮单独操作一次，核对对应返回或事件；输入错误目标或取消操作时查看失败事件，不应显示成功提示。 |
扫码添加客服咨询
