1. 引言

在万物互联的时代，用户拥有多台鸿蒙设备（如手机、平板、智慧屏、智能手表等）已成为常态。这些设备协同工作的核心前提是 ​​实时感知彼此的在线/离线状态​​——例如，当手机与平板处于同一局域网时，用户希望平板能实时显示手机“在线”以便快速投屏；当手机断开Wi-Fi或关闭蓝牙时，平板应立即提示“离线”以避免无效操作。

鸿蒙操作系统通过 ​​分布式软总线​​ 和 ​​设备状态管理模块​​，为开发者提供了设备状态实时同步的能力。本文将聚焦 ​​“设备在线/离线状态提示”​​ 这一基础但关键的场景，深入解析其技术原理、实现方案及代码示例，帮助开发者快速构建支持设备状态感知的多设备应用。

2. 技术背景

​​2.1 鸿蒙分布式设备管理的核心机制​​

鸿蒙的分布式能力基于 ​​分布式软总线​​（Distributed Soft Bus），它通过蓝牙、Wi-Fi、NFC等多种通信技术，自动发现并连接同一局域网或邻近范围内的鸿蒙设备。设备状态（在线/离线）的实时同步依赖于以下关键技术：

• ​​设备发现与组网​​：设备通过组播（Multicast）或广播（Broadcast）协议定期发送“心跳包”（包含设备ID、类型、当前状态等信息），邻近设备监听这些包并更新本地设备列表；
• ​​状态监听​​：开发者通过鸿蒙提供的 ​​@ohos.distributedHardware.deviceManager​​ 模块（或更高版本的 ​​@ohos.distributedDeviceState​​ 相关API），订阅目标设备的状态变化事件（如从“在线”变为“离线”）；
• ​​实时通信​​：当设备的网络连接（如Wi-Fi断开）或电源状态（如关机）发生变化时，设备会主动上报状态变更，其他设备通过监听回调实时接收通知。

​​2.2 在线/离线状态的定义​​

在鸿蒙分布式场景中，“在线”通常指设备满足以下条件：

• 设备已开机且系统正常运行；
• 设备与当前网络（如家庭Wi-Fi）保持连接（或通过蓝牙/NFC与其他设备建立了直接链路）；
• 设备未主动关闭分布式服务（如用户未禁用“多设备协同”功能）。

“离线”则指设备不满足上述任一条件（如Wi-Fi断开、蓝牙关闭、设备关机或进入休眠模式）。

3. 应用使用场景

​​3.1 典型使用场景​​

4. 不同场景下的详细代码实现

​​4.1 环境准备​​

​​4.1.1 开发工具与依赖​​

• ​​开发工具​​：DevEco Studio（鸿蒙官方IDE，支持API 9及以上版本）；
• ​​目标设备​​：至少两台鸿蒙设备（如一台手机和一台平板），确保已开启“分布式协同”功能（默认开启）；
• ​​核心技术​​：
  • ​​设备状态监听​​：通过 @ohos.distributedHardware.deviceManager 模块（API 9）或更高版本的分布式设备状态API（如 @ohos.distributedDeviceState）；
  • ​​权限配置​​：需在 config.json 中声明分布式相关权限（如 ohos.permission.DISTRIBUTED_DATASYNC）；
  • ​​设备类型​​：支持手机（DEVICE_TYPE_PHONE）、平板（DEVICE_TYPE_TABLET）、智慧屏（DEVICE_TYPE_TV）等。

​​4.1.2 权限配置示例（config.json）​​

{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.DISTRIBUTED_DATASYNC",
        "reason": "用于监听分布式设备的在线/离线状态"
      },
      {
        "name": "ohos.permission.GET_DISTRIBUTED_DEVICE_INFO",
        "reason": "获取设备基本信息（如设备ID、类型）"
      }
    ]
  }
}

​​4.2 典型场景1：基础设备状态监听（API 9，DeviceManager模块）​​

​​4.2.1 代码实现（ArkTS示例）​​

// 设备状态监听页面（DeviceStatusPage.ets）
import distributedDeviceManager from '@ohos.distributedHardware.deviceManager';
import promptAction from '@ohos.promptAction';

@Entry
@Component
struct DeviceStatusPage {
  @State onlineDevices: Array<string> = []; // 存储在线设备ID
  @State offlineDevices: Array<string> = []; // 存储离线设备ID
  private deviceManager: distributedDeviceManager.DeviceManager | null = null;

  aboutToAppear() {
    this.initDeviceManager();
  }

  // 初始化设备管理器并开始监听状态
  private initDeviceManager() {
    // 获取设备管理器实例
    distributedDeviceManager.getDeviceManager(this.onDeviceManagerCallback.bind(this));
  }

  // 设备管理器回调（成功获取实例后注册状态监听）
  private onDeviceManagerCallback(err: number, data: distributedDeviceManager.DeviceManager) {
    if (err === 0 && data) {
      this.deviceManager = data;
      console.info('设备管理器初始化成功');
      this.registerStatusListener();
    } else {
      promptAction.showToast({
        message: '设备管理器初始化失败(err:' + err + ')',
        duration: 3000
      });
    }
  }

  // 注册设备状态变化监听器
  private registerStatusListener() {
    if (!this.deviceManager) return;

    // 监听设备状态变化（API 9支持的设备状态事件）
    this.deviceManager.on('deviceStatusChange', (deviceId: string, status: number) => {
      console.info(`设备状态变化: deviceId=${deviceId}, status=${status}`);
      this.updateDeviceStatus(deviceId, status);
    });

    // 可选：主动获取当前已连接的设备列表（初始状态）
    this.getInitialDeviceList();
  }

  // 获取初始设备列表（模拟API 9可能不支持直接获取，此处为示例逻辑）
  private getInitialDeviceList() {
    // 注意：API 9的DeviceManager可能不直接提供“当前在线设备列表”，实际需通过状态监听动态维护
    // 此处假设初始时无设备，后续通过状态监听动态更新
    this.onlineDevices = [];
    this.offlineDevices = [];
  }

  // 根据状态更新设备分类（1表示在线，0或其他值表示离线，具体值需参考API文档）
  private updateDeviceStatus(deviceId: string, status: number) {
    if (status === 1) { // 假设status=1为在线（实际值需根据API 9文档确认）
      // 移除离线列表（如果存在）
      const offlineIndex = this.offlineDevices.indexOf(deviceId);
      if (offlineIndex !== -1) {
        this.offlineDevices.splice(offlineIndex, 1);
      }
      // 添加到在线列表（避免重复）
      if (!this.onlineDevices.includes(deviceId)) {
        this.onlineDevices.push(deviceId);
        this.showDeviceStatusToast(deviceId, '在线');
      }
    } else { // 其他状态为离线
      // 移除在线列表（如果存在）
      const onlineIndex = this.onlineDevices.indexOf(deviceId);
      if (onlineIndex !== -1) {
        this.onlineDevices.splice(onlineIndex, 1);
      }
      // 添加到离线列表（避免重复）
      if (!this.offlineDevices.includes(deviceId)) {
        this.offlineDevices.push(deviceId);
        this.showDeviceStatusToast(deviceId, '离线');
      }
    }
  }

  // 显示设备状态提示（简化版，实际可用弹窗或UI组件展示）
  private showDeviceStatusToast(deviceId: string, status: string) {
    // 模拟设备ID转名称（实际需通过getDeviceInfos接口获取设备名称）
    const deviceName = '设备_' + deviceId.slice(-4); // 截取后4位作为简写
    promptAction.showToast({
      message: `${deviceName} 当前${status}`,
      duration: 2000
    });
    console.info(`${deviceName} 状态更新: ${status}`);
  }

  // 页面UI：显示在线/离线设备列表（简化示例）
  build() {
    Column({ space: 20 }) {
      Text('鸿蒙设备状态实时同步')
        .fontSize(24)
        .fontWeight(FontWeight.Bold)
        .margin({ top: 20 })

      Text('在线设备:')
        .fontSize(18)
        .alignSelf(ItemAlign.Start)
      List({ space: 10 }) {
        ForEach(this.onlineDevices, (deviceId: string) => {
          ListItem() {
            Text(`• 设备_${deviceId.slice(-4)} (在线)`)
              .fontSize(16)
              .fontColor(Color.Green)
          }
        })
      }
      .width('100%')
      .height(150)

      Text('离线设备:')
        .fontSize(18)
        .alignSelf(ItemAlign.Start)
      List({ space: 10 }) {
        ForEach(this.offlineDevices, (deviceId: string) => {
          ListItem() {
            Text(`• 设备_${deviceId.slice(-4)} (离线)`)
              .fontSize(16)
              .fontColor(Color.Red)
          }
        })
      }
      .width('100%')
      .height(150)
    }
    .width('100%')
    .height('100%')
    .padding(20)
  }
}

​​4.2.2 代码解析​​

• ​​核心模块导入​​：

  • distributedDeviceManager：鸿蒙提供的分布式设备管理模块（API 9），用于监听设备状态变化；
  • promptAction：用于显示简单的Toast提示（实际项目中可替换为自定义UI组件）。

• ​​设备管理器初始化​​：

  • getDeviceManager 是异步获取 DeviceManager 实例的方法，成功后通过 on 方法注册 deviceStatusChange 事件监听器，该监听器会在任意目标设备的状态变化时触发回调。

• ​​状态监听逻辑​​：

  • 回调参数 deviceId 是设备的唯一标识符（如MAC地址或系统生成的ID），status 是状态码（假设 1 表示在线，其他值表示离线，具体值需参考API 9文档）。
  • updateDeviceStatus 方法根据状态码更新 onlineDevices 和 offlineDevices 列表，并通过Toast提示用户当前状态变化。

• ​​UI展示​​：

  • 页面通过 List 组件分别显示在线设备和离线设备列表，设备名称简化为 设备_XXXX（取设备ID后4位），在线设备显示绿色，离线设备显示红色。

​​4.2.3 运行结果​​

• ​​初始状态​​：页面显示空的在线/离线设备列表；
• ​​设备连接​​：当另一台鸿蒙设备（如平板）进入同一局域网并开启分布式服务时，手机端控制台输出类似 设备状态变化: deviceId=ABC123456789, status=1，Toast提示“设备_5678 当前在线”，在线设备列表新增一项；
• ​​设备断开​​：当平板关闭Wi-Fi或退出分布式应用时，状态变为 0，Toast提示“设备_5678 当前离线”，在线列表移除该项，离线列表新增一项。

​​4.3 典型场景2：进阶设备信息与状态展示（结合设备名称获取）​​

​​4.3.1 代码实现（扩展功能）​​

若需显示设备的真实名称（而非ID简写），可通过 getDeviceInfos 接口（API 9支持）获取设备详情。以下代码扩展了状态监听逻辑，关联设备ID与名称：

// 扩展：获取设备名称（需在状态监听前调用）
private async fetchDeviceNames() {
  if (!this.deviceManager) return;

  try {
    const deviceInfos = await this.deviceManager.getDeviceList({
      deviceType: distributedDeviceManager.DeviceType.DEVICE_TYPE_ALL // 获取所有类型设备
    });
    deviceInfos.forEach((info) => {
      const deviceId = info.deviceId;
      const deviceName = info.deviceName || `设备_${deviceId.slice(-4)}`; // 优先使用真实名称
      // 可将设备名称与ID的映射存储到Map中，供后续状态更新时使用
      console.info(`设备信息: ID=${deviceId}, 名称=${deviceName}, 类型=${info.deviceType}`);
    });
  } catch (error) {
    console.error('获取设备列表失败:', error);
  }
}

// 在initDeviceManager()中调用（可选）
private initDeviceManager() {
  distributedDeviceManager.getDeviceManager((err, data) => {
    if (err === 0 && data) {
      this.deviceManager = data;
      console.info('设备管理器初始化成功');
      this.fetchDeviceNames(); // 先获取设备信息
      this.registerStatusListener(); // 再注册状态监听
    }
  });
}

​​4.3.2 原理解释​​

• getDeviceList 接口返回当前可发现的设备列表（包含 deviceId、deviceName、deviceType 等信息），开发者可通过 deviceName 字段直接显示设备真实名称（如“张三的手机”“客厅的智慧屏”）；
• 若设备未设置名称，则回退到ID简写（如 设备_ABCD），确保始终有可读标识。

5. 原理解释

​​5.1 设备状态同步的核心流程​​

1. ​​心跳机制​​：每台鸿蒙设备作为分布式网络中的节点，会定期通过组播/广播协议发送“心跳包”，包含自身的设备ID、当前网络状态（如Wi-Fi连接状态）、电源状态（如是否开机）等信息；
2. ​​邻居发现​​：邻近设备（如同一Wi-Fi下的手机和平板）监听这些心跳包，解析后更新本地的设备状态表（如“设备A：在线，最后活跃时间：202X-XX-XX 10:00”）；
3. ​​状态变更通知​​：当设备的网络连接断开（如Wi-Fi关闭）、蓝牙禁用或主动退出分布式服务时，会发送“离线心跳”或停止发送心跳包，邻居设备检测到超时（如30秒内未收到心跳）后，将设备状态标记为“离线”；
4. ​​开发者回调​​：通过 deviceStatusChange 事件监听器，开发者可实时接收状态变更通知（如从“在线”→“离线”或反之），并在UI或业务逻辑中做出响应。

​​5.2 核心特性​​

6. 原理流程图及原理解释

​​6.1 设备状态同步的完整流程图​​

sequenceDiagram
    participant 设备A as 设备A（如手机）
    participant 设备B as 设备B（如平板）
    participant 网络 as 局域网（Wi-Fi/蓝牙）
    participant 监听器 as 状态监听回调

    loop 心跳发送（设备A/B）
      设备A->>网络: 定期发送心跳包（含设备ID、状态=在线）
      设备B->>网络: 定期发送心跳包（含设备ID、状态=在线）
    end

    网络->>设备B: 转发设备A的心跳包
    设备B->>监听器: 触发deviceStatusChange(deviceA_ID, 1)（在线）
    监听器->>UI: 更新设备A为“在线”

    loop 状态变化（设备A断开Wi-Fi）
      设备A->>网络: 停止发送心跳包（或发送状态=离线）
    end

    Note over 网络,设备B: 超时未收到设备A心跳（如30秒）
    设备B->>监听器: 触发deviceStatusChange(deviceA_ID, 0)（离线）
    监听器->>UI: 更新设备A为“离线”

​​6.2 原理解释​​

• ​​初始阶段​​：设备A和设备B在同一局域网下，均定期通过心跳包宣告自身“在线”；
• ​​状态同步​​：设备B通过监听网络中的心跳包，实时感知设备A的状态（通过 deviceStatusChange 回调更新UI）；
• ​​状态变化​​：当设备A断开Wi-Fi时，停止发送心跳包，设备B在超时后检测到设备A无心跳，触发离线回调并更新UI；
• ​​双向同步​​：该机制是双向的（设备A也能感知设备B的状态），确保多设备间的状态一致性。

7. 实际详细应用代码示例（综合案例：投屏应用的设备选择页）

​​7.1 场景描述​​

开发一个投屏应用，要求在用户点击“投屏”按钮时：

• 仅显示当前在线的鸿蒙设备（如智慧屏、平板）；
• 实时更新设备列表（当某台设备离线时，自动从列表中移除）；
• 用户选择在线设备后，直接发起投屏请求。

​​7.2 代码实现（简化版投屏设备选择页）​​

// 投屏设备选择页（CastDevicePage.ets）
import distributedDeviceManager from '@ohos.distributedHardware.deviceManager';
import router from '@ohos.router';

@Entry
@Component
struct CastDevicePage {
  @State onlineDevices: Array<{ id: string, name: string }> = []; // 在线设备列表（含名称）
  private deviceManager: distributedDeviceManager.DeviceManager | null = null;

  aboutToAppear() {
    this.initDeviceManager();
  }

  private initDeviceManager() {
    distributedDeviceManager.getDeviceManager((err, data) => {
      if (err === 0 && data) {
        this.deviceManager = data;
        this.registerStatusListener();
        this.loadInitialDevices();
      }
    });
  }

  // 模拟加载初始设备（实际需结合getDeviceList）
  private loadInitialDevices() {
    // 假设初始时有2台在线设备（实际需通过API获取）
    this.onlineDevices = [
      { id: 'DEV001', name: '客厅智慧屏' },
      { id: 'DEV002', name: '卧室平板' }
    ];
  }

  private registerStatusListener() {
    if (!this.deviceManager) return;

    this.deviceManager.on('deviceStatusChange', (deviceId: string, status: number) => {
      console.info(`投屏设备状态变化: ${deviceId}, ${status}`);
      this.updateCastDeviceStatus(deviceId, status);
    });
  }

  private updateCastDeviceStatus(deviceId: string, status: number) {
    if (status === 1) { // 在线
      const exists = this.onlineDevices.some(device => device.id === deviceId);
      if (!exists) {
        this.onlineDevices.push({ id: deviceId, name: `设备_${deviceId.slice(-4)}` });
      }
    } else { // 离线
      this.onlineDevices = this.onlineDevices.filter(device => device.id !== deviceId);
    }
  }

  // 用户选择设备并投屏
  private castToDevice(device: { id: string, name: string }) {
    console.info(`开始投屏到: ${device.name}`);
    router.pushUrl({
      url: 'pages/CastPlayerPage', // 投屏播放页
      params: { deviceId: device.id, deviceName: device.name }
    });
  }

  build() {
    Column({ space: 20 }) {
      Text('选择投屏设备')
        .fontSize(24)
        .fontWeight(FontWeight.Bold)

      if (this.onlineDevices.length === 0) {
        Text('暂无可用的在线设备，请检查设备网络连接')
          .fontSize(16)
          .fontColor(Color.Gray)
      } else {
        List({ space: 10 }) {
          ForEach(this.onlineDevices, (device) => {
            ListItem() {
              Button(device.name)
                .onClick(() => this.castToDevice(device))
                .width('100%')
                .height(50)
                .backgroundColor(Color.Blue)
                .fontColor(Color.White)
            }
          })
        }
        .width('100%')
        .layoutWeight(1)
      }
    }
    .width('100%')
    .height('100%')
    .padding(20)
  }
}

​​7.3 运行结果​​

• ​​初始状态​​：显示预置的在线设备列表（如“客厅智慧屏”“卧室平板”）；
• ​​设备离线​​：当智慧屏关闭Wi-Fi时，状态变为离线，列表自动移除该项；
• ​​用户交互​​：点击在线设备按钮后，跳转到投屏播放页（模拟实际投屏逻辑）。

8. 运行结果

​​8.1 基础场景（DeviceStatusPage）​​

• 控制台输出设备状态变化的日志（如 设备状态变化: deviceId=XXX, status=1）；
• Toast提示用户“设备_XXXX 当前在线/离线”；
• UI列表实时更新在线/离线设备的数量与详情。

​​8.2 综合场景（CastDevicePage）​​

• 投屏页面仅显示在线设备按钮，离线设备自动隐藏；
• 用户点击在线设备后触发投屏流程（实际项目中需对接鸿蒙的投屏服务API）。

9. 测试步骤及详细代码

​​9.1 基础功能测试​​

1. ​​设备连接测试​​：启动两台鸿蒙设备（如手机和平板），确保均在同一Wi-Fi下，打开分布式应用，观察控制台是否输出对方设备的“在线”状态；
2. ​​状态变化测试​​：关闭平板的Wi-Fi或退出分布式应用，观察手机端是否在几秒内提示“平板离线”并更新UI列表；
3. ​​UI同步测试​​：在设备状态变化时，检查在线/离线设备列表是否实时刷新（如颜色、数量变化）。

​​9.2 边界测试​​

1. ​​无设备场景​​：当所有设备均离线时，UI是否显示“无在线设备”提示；
2. ​​频繁切换测试​​：快速开关Wi-Fi（模拟设备频繁在线/离线），验证状态监听是否稳定（无重复提示或遗漏）；
3. ​​多设备并发测试​​：同时连接3台以上鸿蒙设备，检查状态同步是否准确（无错乱或延迟）。

10. 部署场景

​​10.1 生产环境部署​​

• ​​权限合规​​：确保应用的 config.json 中已正确声明分布式相关权限（如 DISTRIBUTED_DATASYNC），并通过应用市场审核；
• ​​兼容性适配​​：针对不同鸿蒙版本（如API 9、API 10）调整状态监听API（高版本可能提供更简洁的接口）；
• ​​性能优化​​：避免频繁更新UI（如设备状态每秒变化多次时，通过防抖机制合并更新）。

​​10.2 适用场景​​

• ​​多设备协同应用​​：投屏、文件互传、跨设备剪贴板；
• ​​智能家居控制​​：智慧屏、智能音箱的状态监控；
• ​​团队协作工具​​：多台平板/手机的实时在线状态展示（如会议场景）。

11. 疑难解答

​​11.1 问题1：设备状态监听无回调​​

• ​​可能原因​​：未正确获取 DeviceManager 实例（如异步回调失败），或未注册 deviceStatusChange 事件；
• ​​解决方案​​：检查 getDeviceManager 的错误码（err === 0 表示成功），并在成功后调用 on 方法注册监听。

​​11.2 问题2：状态更新延迟​​

• ​​可能原因​​：心跳间隔较长（如默认30秒），或网络环境不稳定（如Wi-Fi信号弱）；
• ​​解决方案​​：优化网络环境（如靠近路由器），或在高版本API中调整心跳参数（若支持）。

​​11.3 问题3：设备名称显示为空​​

• ​​可能原因​​：未调用 getDeviceList 获取设备真实名称，或设备未设置名称；
• ​​解决方案​​：通过 getDeviceInfos 接口获取设备名称（参考场景2代码），或使用ID简写作为备用。

12. 未来展望

​​12.1 技术趋势​​

• ​​更精准的状态感知​​：未来可能支持“弱在线”状态（如设备网络延迟高但未完全离线），提供更细致的协同提示；
• ​​跨网络同步​​：支持跨Wi-Fi网络（如手机4G与平板家庭Wi-Fi）的设备状态同步（依赖更高级的分布式协议）；
• ​​AI驱动的状态预测​​：通过机器学习预测设备可能的离线风险（如电量低时自动提醒），提前优化协同体验。

​​12.2 挑战​​

• ​​多协议兼容​​：不同鸿蒙设备的通信协议（如蓝牙/Wi-Fi/NFC）可能存在差异，需统一状态同步逻辑；
• ​​隐私与安全​​：设备状态信息可能暴露用户使用习惯（如“常在线设备”），需加强数据加密与权限控制；
• ​​低功耗优化​​：频繁的心跳机制可能增加设备电量消耗，需平衡实时性与能耗。

​​13. 总结​​

鸿蒙的 ​​设备状态实时同步（在线/离线提示）​​ 是多设备协同的基础能力，通过分布式软总线的心跳机制和状态监听API，开发者能够轻松实现设备状态的实时感知与UI同步。本文通过 ​​基础API调用（DeviceManager）、代码示例（ArkTS）、原理解析及综合应用（投屏场景）​​ 的系统讲解，揭示了：

• ​​核心原理​​：设备通过心跳包宣告状态，邻居设备监听并更新本地状态表，开发者通过回调实时响应变化；
• ​​最佳实践​​：结合 deviceStatusChange 事件与UI组件（如列表、Toast），构建响应式的设备状态面板；
• ​​技术扩展​​：未来可通过获取设备名称、优化心跳策略等方式提升用户体验；
• ​​开发者价值​​：掌握设备状态同步能力，是开发高质量鸿蒙多设备应用（如投屏、智能家居）的关键，能够显著增强产品的交互性与可靠性。

从简单的状态提示到复杂的协同操作，鸿蒙的设备状态管理能力正推动多设备生态向更智能、更无缝的方向发展！