HarmonyOS —— 跨设备互通特性：用平板“遥控手机相机”的正确姿势

HarmonyOS —— 跨设备互通特性：用平板“遥控手机相机”的正确姿势

这一节不是网络、不是传输，而是 “让你的设备们一起干活”。
典型画面：我在平板写笔记，点一下按钮 → 旁边手机自动亮屏开相机 → 拍完图秒回到平板里。

---

一、先搞清楚：HarmonyOS 跨设备互通到底干嘛用？

鸿蒙开发者第四期活动

官方这块叫 “跨设备互通特性”，本质是：

在一台设备上写应用，把 其它设备的能力（相机、扫描、图库）当“外设”一样用。

具体来说：

• 平板 / 2in1 上的应用：
  • 可以直接调用 手机 / 另一台平板 的：
    • 相机（拍照）
    • 文档扫描
    • 图库选择器
    • 视频选择器
    • 图片 & 视频组合选择器
• 拍完 / 选完之后，结果会回传到本端应用里，你只需要处理“拿到的图片/数据”。

版本支持一眼记住

• API 6.0.0(20) 及之后：
  • ✅ 支持：跨端拍照、文档扫描、图库选择器、视频选择器、图片&视频选择器
• API 6.0.0(20) 之前：
  • ✅ 支持：跨端拍照、文档扫描、图库选择器
  • ❌ 不支持：视频选择器、图片&视频组合选择器

设备侧：

• 能力支持：Phone / 2in1 / Tablet / Wearable /（新）TV
  （你可以理解为：有 HarmonyOS，且版本够高，就都能拉进来玩）

---

二、典型使用场景：平板写笔记，手机当“外拍相机”

官方举的就是这个场景：

• 我在 平板/2in1 的富文本应用 里（笔记、邮件、备忘录……）
• 想插一张“刚拍的照片”，但：
  • 平板拿着不方便
  • 手机更轻、镜头更强、构图更爽

这时候就可以：

1. 在平板应用里点“跨设备拍照”按钮；
2. 弹出设备列表（比如“我的手机”“备用手机”等）；
3. 选一台手机；
4. 手机自动亮屏 + 打开相机预览；
5. 拍照、确认；
6. 照片自动回传到平板应用内，插入到当前文档。

重点：

• 整个“发现设备、建链、认证、数据传输、控制指令”
  → 都是 系统的分布式协同框架帮你做好了；
• 你在应用侧只要用两个组件：
  • createCollaborationServiceMenuItems —— 设备选择菜单
  • CollaborationServiceStateDialog —— 远端相机状态弹窗

---

三、核心组件：一个菜单 + 一个状态弹窗

1. createCollaborationServiceMenuItems —— 相机设备列表组件

你可以把它理解成：

“把附近可用设备列出来，让用户选哪台来当相机。”

特点：

• 系统分布式协同框架会：
  • 找到 同账号 + 同组网 下有相机能力的设备；
  • 帮你完成 发现、连接、认证；
  • 然后把这些设备列表交给 createCollaborationServiceMenuItems 来展示。

UI 行为上：

• 附近只有 1 ～ 2 台可用设备：
  • 直接在菜单里列出这 1～2 个设备；
• 附近有 2 台以上设备：
  • 自动创建 子菜单项，把多个设备“叠层”展示出来；
  • 用户逐级选择具体设备。

你在 UI 里的用法很适合这样放：

• 富文本编辑应用的 「插入」菜单；
• 工具栏上的 「跨设备拍照」按钮；
• 右键菜单里的 「从手机拍照导入」之类。

2. CollaborationServiceStateDialog —— 远端相机状态弹窗组件

这个是用来显示 远端拍照过程的实时状态 的，中间所有步骤不用你手搓：

可能出现的状态包括：

• ✅ 对端设备拍摄中
• ✅ 图片导入中（数据正在回传）
• ❌ 协同失败
• ❌ 本端 WLAN 未开启
• ❌ 双端 WLAN 或蓝牙未开启

好处是：

• 你不需要自己去解析各种错误码；
• 直接用系统提供的状态弹窗组件，用户一看就知道该干嘛。

---

四、整体运作机制：一条链路从发现设备到照片回传

官方给了一张图（时间线大致是这样），总结成 4 步：

步骤 1：系统自动完成“跨设备建链”

• 同账号、同组网下：
  • 本端设备：平板 / 2in1
  • 远端设备：手机 / 平板
• 分布式协同框架会自动做：
  • 设备发现
  • 连接建立
  • 安全认证
• 然后把 可用的远端相机设备列表 交给 createCollaborationServiceMenuItems 组件展示。

对开发者来说：
你只关心“有哪几台设备可用”，不用自己写发现/配对/认证逻辑。

---

步骤 2：用户在本端 UI 中选择设备并唤醒远端相机

• 用户在你的应用功能入口（按钮/菜单）中调起：
  • createCollaborationServiceMenuItems
• 用户从里面选中一台远端设备，比如“我的手机”；
• 应用通过协同框架发起 跨端拍照请求；
• 系统自动在那台手机/平板上：
  • 亮屏
  • 打开相机预览界面
• 同步地：
  • 远端的拍照状态会实时回传到
    • CollaborationServiceStateDialog
    • createCollaborationServiceMenuItems 的 UI 区域里

此时，用户在你当前使用的平板/2in1 上不用干别的，只需要拿起手机操作相机。

---

步骤 3：用户在远端设备上拍照 & 导入

在远端设备上，用户的流程就是：

1. 调整角度、构图；
2. 点击拍照；
3. 预览 & 确认照片。

确认后：

• 照片会以分布式协同方式，快速回传到本端应用；
• CollaborationServiceStateDialog 会显示“图片导入中”→完成；
• 远端设备自动退出相机界面，回到原来的状态（不会一直卡在拍照界面）。

---

步骤 4：出错场景 & 用户操作提示

如果协同过程出现问题，组件会显示对应的状态，例如：

• 协同失败（网络/权限/异常等）
• 本端 WLAN 未开启
• 双端 WLAN 或蓝牙未开启

此时用户只需要按照提示做两件事：

1. 打开对应设备的 WLAN / 蓝牙；
2. 回到你的应用，再次点击 createCollaborationServiceMenuItems 入口重新发起流程。

你这边的处理逻辑通常只需要：

• 给用户一个“重试”入口；
• 必要时在日志中打一些调试信息。

---

五、作为开发者，你需要做的事情可以这样记

虽然文档这一节主要讲原理，没有给完整 ArkTS 代码，但可以概括出开发侧的“心智模型”：

1. UI 层面：
   • 在应用里找到“需要插入图片/扫描结果”的入口，比如：
     • 富文本编辑工具栏按钮
     • 「插入」菜单里的一个 Action
   • 入口触发时：
     • 调用 createCollaborationServiceMenuItems 让用户选设备；
     • 在侧边或中间弹出 CollaborationServiceStateDialog 显示进度。
2. 数据层面：
   • 最终你只要处理“拍完之后的图片/扫描结果”：
     • 插入到编辑器
     • 保存到本地
     • 或走后续上传逻辑
3. 异常 & 状态：
   • 给出最基本的提示：
     • WLAN / 蓝牙未开启 → 引导去设置；
     • 协同失败 → 支持“重试”按钮；
   • 内部可配合日志系统埋点哪些状态出现得多，用来优化交互。

重点：你不用自己实现：

• 发现设备；
• 连通性检测；
• 设备间认证；
• 通信协议；
• 数据流的打包/解包。

这一切都是 HarmonyOS 分布式协同框架 + 两个组件 帮你搞定。

---

六、考点 / 复习小抄

• 能力名称： 跨设备互通特性（以拍照为例）
• 版本支持：
  • API 6.0.0(20) 及之后：
    • 拍照、文档扫描、图库选择器、视频选择器、图片&视频选择器
  • 之前版本：
    • 仅支持：拍照、文档扫描、图库选择器
• 典型设备角色：
  • 本端：平板 / 2in1（运行编辑类应用）
  • 远端：手机 / 平板（提供相机/扫描/图库能力）
• 关键组件：
  • createCollaborationServiceMenuItems：相机设备列表组件
  • CollaborationServiceStateDialog：远端相机状态弹窗组件
• 核心流程：
  1. 同账号同组网 → 分布式框架自动建链 & 发现设备
  2. 本端调用设备列表组件，用户选远端设备
  3. 系统唤醒远端相机，状态实时回传到状态弹窗
  4. 用户在远端拍照并确认 → 照片回传到本端应用
  5. 远端自动退出相机界面，流程结束