设备选择器（DevicePicker）使用指导
设备选择器组件 - 弹出鸿蒙系统级设备选择器UI。 鸿蒙独有组件，基于 DevicePicker API。
运行前提与搭建步骤
这些案例在包含该组件的鸿蒙 AI 伴侣或 HAP 中运行。Android 侧是供网页编辑器生成积木的声明，不能用安卓伴侣验证鸿蒙系统能力。
- 在设计器拖入
DevicePicker，保留名称DevicePicker1；拖入案例涉及的按钮、文本输入框以及一个标签标签1，按代码中的名称重命名。 - 根据下面的业务说明准备素材、JSON 或系统目标。案例中的按钮代表分步操作，先等初始化、加载或创建成功，再执行下一步。
- 接住完成事件与错误事件，将原始 JSON 或错误显示在标签。先确认原始结果，再编写业务处理。
系统选择界面不是应用自己绘制的列表；选择设备不代表已完成绑定、投屏或数据同步，下一步由对应业务组件执行。
案例一：显示系统设备选择器
各案例独立使用；组合到同一屏幕时，将同名事件的处理合并到一个事件积木中。
when 按钮_选择设备.Click() {
DevicePicker1.ShowPicker()
}
when DevicePicker1.DeviceSelected(设备信息JSON) {
标签1.Text = 设备信息JSON
}
when DevicePicker1.Error(错误信息) {
标签1.Text = 错误信息
}
案例二：释放选择器
when 按钮_关闭.Click() {
DevicePicker1.Release()
}
when DevicePicker1.SelectedDeviceOffline(设备信息JSON) {
标签1.Text = join("设备离线：", 设备信息JSON)
}
参数与返回值速查
JSON 参数是文本，不能直接传字典；需要字典时可用 Web 客户端的 JSON 解码积木转换返回文本。完整默认值与类型见组件参考。
| 方法或事件 | 参数与用途 |
|---|---|
释放（Release） |
无参数。释放设备选择器占用的系统资源。 |
显示选择器（ShowPicker） |
无参数。弹出鸿蒙系统级设备选择器UI，让用户选择目标设备。 |
更新状态（网络ID，状态，描述）（UpdateState） |
网络ID：文本, 状态：数字, 描述：文本。更新指定设备的状态信息。 |
设备已选择时（设备信息JSON）（DeviceSelected） |
设备信息JSON：文本。用户选择了目标设备时触发，返回设备信息。 |
设备已取消选择时（设备信息JSON）（DeviceUnselected） |
设备信息JSON：文本。用户取消了设备选择时触发。 |
出错时（错误信息）（Error） |
错误信息：文本。发生错误时触发，返回错误信息。 |
选择器已显示时（PickerShown） |
无参数。设备选择器UI弹出显示时触发。 |
已选设备离线时（设备信息JSON）（SelectedDeviceOffline） |
设备信息JSON：文本。已选中的设备变为离线状态时触发。 |
状态已更新时（状态JSON）（StateUpdated） |
状态JSON：文本。设备状态更新完成时触发，返回更新结果。 |
常见问题与验收
| 现象 | 检查与预期 |
|---|---|
| 安卓运行没有结果 | 切换到鸿蒙伴侣或 HAP；Android 的声明不会执行该鸿蒙系统能力。 |
| 方法已调用但界面没变化 | 生成 JSON 的方法只是构建数据；按业务流程交给渲染、启动或同步入口，不能将数据生成当成系统操作完成。 |
| 初始化、权限或设备失败 | 记录错误事件，确认系统服务、授权、目标应用或设备可用；只在成功事件后继续下一步。 |
| JSON 解析失败 | 使用上一组件的原始输出，检查引号和字段类型；空对象用于默认模板演示，不能代替真实目标信息。 |
| 两个案例验收 | 每个按钮单独操作一次，核对对应返回或事件；输入错误目标或取消操作时查看失败事件，不应显示成功提示。 |
完整 .aia 源码与操作指导
鸿蒙系统设备面板→真实设备选择→读取networkId／名称→回报测试业务状态→释放并再次显示。需要系统实际发现的支持协同设备，不能用虚构设备替代。状态回报不执行硬件指令、投屏或应用流转；下一步把实际networkId交给对应的分布式组件。
导入 DevicePickerAllFeatures.aia，连接最新伴侣，或编译独立安装包。真机／伴侣运行尚未实测。
| API / 功能 | 操作入口 | 预期结果 |
|---|---|---|
| BusinessDesc读写与设计器配置 | 业务输入后应用，再显示 | 系统面板显示实际业务描述，读回值 |
| ShowPicker、PickerShown、DeviceSelected、DeviceUnselected | 显示真实面板，选中与取消 | 返回实际networkId和设备信息；未找到设备不会填入样本设备 |
| SelectedDeviceId、SelectedDeviceName、SelectedDeviceOffline | 选择后读取；关闭实际目标设备 | 读真实设备信息；系统派发离线时记录实际事件 |
| UpdateState、StateUpdated | 选择真实设备后选空闲／测试成功／测试失败回报 | 0／1／2状态和文字；只测试状态通知，不声称实际流转成功 |
| Release、Error、恢复 | 释放后读取并再显示；无设备点击状态 | 选择清空，未选择不发状态；真实系统错误可重新显示重试 |
| 设备条件 | 两台支持协同的鸿蒙设备，按系统要求开启账号、网络与协同 | 此选择器不是通用BLE扫描；Android只有接口占位 |
所有返回值均用于界面反馈，错误由底部错误区展示。设计器采用明确非默认配置，初始化与界面同步。API 覆盖检查按最终 AIA 检查方法、事件、属性读取与设置及设计器配置，不能替代真实设备验证。
附近设备选择与状态回报
导入方法：项目 → 导入项目（.aia）→ 选择下载的 .aia 源码文件。 鸿蒙系统设备面板→真实设备选择→读取networkId／名称→回报测试业务状态→释放并再次显示。需要系统实际发现的支持协同设备，不能用虚构设备替代。状态回报不执行硬件指令、投屏或应用流转；下一步把实际networkId交给对应的分布式组件。 覆盖检查 14/14。首次载入及保存重开均0个错误，真实后台导入、安装包编译通过；真机／伴侣／硬件联调尚未实测。全部属性读写、方法与事件的操作入口和预期结果见组件指导。
扫码添加客服咨询
