多设备连接状态管理与异常恢复机制：监听设备上下线、异常断连处理与状态提示设计 HarmonyOS 5.0.0 或以上

本文链接：https://blog.csdn.net/weixin_43815680/article/details/148007044

适配版本：HarmonyOS 5.0.0 或以上
阅读目标：掌握如何管理分布式设备的连接状态，处理中途掉线、权限失效、同步异常等情况，提升协同系统的健壮性和用户体验

🧠 一、核心管理场景

场景	管理目标
监听设备上下线	实时感知设备是否在线
显示设备状态（在线/离线）	UI 中提供设备可用性指示
自动断线重连或提示用户操作	网络不稳或中断后重试/引导处理
中途掉线导致同步失败的补救机制	确保分布式 KV/任务迁移在网络恢复后可继续执行

📦 二、监听设备状态变化（`@ohos.deviceManager`）

import deviceManager from '@ohos.distributedHardware.deviceManager'

deviceManager.createDeviceManager('myAppTag', (err, manager) => {
  if (err) return
  manager.on('deviceStateChange', (data) => {
    if (data.action === 'online') {
      console.info(`设备上线：${data.deviceName}`)
      updateDeviceStatus(data.deviceId, true)
    } else if (data.action === 'offline') {
      console.warn(`设备离线：${data.deviceName}`)
      updateDeviceStatus(data.deviceId, false)
    }
  })
})

📌 建议在应用 App.ets 或首页入口处注册监听。

🟢 三、设备状态 UI 提示（组件封装）

@Component
struct DeviceStatus {
  @Prop deviceId: string
  @State online: boolean = false

  async aboutToAppear() {
    this.online = await queryDeviceStatus(this.deviceId)
  }

  build() {
    Text(this.online ? '🟢 在线' : '⚫ 离线')
      .fontColor(this.online ? '#00cc00' : '#666')
  }
}

🔄 四、自动重连机制（推荐策略）

function tryReconnect(deviceId: string, maxRetry = 3) {
  let attempts = 0
  const timer = setInterval(async () => {
    const status = await queryDeviceOnline(deviceId)
    if (status || ++attempts >= maxRetry) {
      clearInterval(timer)
      if (status) {
        prompt.showToast({ message: '设备已重新连接' })
      }
    }
  }, 3000)
}

🧩 五、同步失败的恢复处理（以 KVStore 为例）

kvStore.on('syncComplete', (result) => {
  if (result.errCode !== 0) {
    prompt.showToast({ message: '同步失败，等待重试' })
    tryReconnect(result.deviceId)
  }
})

📌 可在失败后延迟重试，或引导用户检查设备与网络状态。

🔐 六、权限/配对失效提示处理

若目标设备权限撤销/重新配对，建议主动清理会话并跳转重授权页：

if (!isTrustedDevice(deviceId)) {
  router.replaceUrl({ url: 'pages/DeviceAuthGuide' })
}

🔧 七、设备状态缓存建议（持久化状态）

// 使用 preferences 或 localStorage 缓存状态
await preferences.put(`device_status_${deviceId}`, true/false)

便于在应用重启后保留“上次设备可用性”并快速渲染 UI。

✅ 八、小结

能力模块	实现说明
实时上下线监听	使用 `deviceManager.on('deviceStateChange')` 注册事件监听
UI 状态同步提示	在线/离线状态组件封装，增强协同可视化体验
异常断连恢复机制	支持自动重连、错误回退、用户提示等机制
权限/可信状态校验	异常时主动跳转引导页，保障后续分布式能力可持续运行