📦 @quec/panel-device-kit

QUEC Panel Device Kit - 设备信息状态管理工具库

用于管理和监听设备信息，支持设备状态、设备列表、事件注册、类型导出等功能。

🗝 依赖库 请自行安装以下库

| 库名 | peerDependencies | devDependencies | | ------------------------------ | ---------------- | --------------- | | @quec/rn-businesspanel-module| * | ^1.1.3 | | @quec/rn-device-module | * | 2.16.1 | | @quec/rn-language-module | * | 0.1.9 | | @quec/rn-log-module | * | 1.0.6 | | i18n-js | * | 4.1.1 | | react | * | 17.0.2 | | react-native | * | 0.64.3 | | zustand | * | 4.4.3 |

PS:如果你的安装版本和devDependencies版本有很大的出入，请联系维护人员进行更新

✅ 功能列表

1. 存储设备信息
2. 监听设备状态变更
3. 支持设备列表状态管理
4. 支持订阅设备列表物模型（🚧 TODO）
5. 导出相关类型供外部使用

🧩 模块结构

本库主要包含以下模块：

1. 状态管理器
   • 设备状态（deviceStore）
   • 设备列表状态（deviceListStore）
2. 设备事件监听器
3. 回调管理器（deviceKitParamsManager）

🚀 快速开始

1. 初始化处理app传入数据

// App.tsx
import {
  useSetProps,
} from '@quec/panel-device-kit'
const App: FC<Props> = props => {
  const setProps = useSetProps()

  useEffect(() => {
    const propsProcessed = setProps(props)
    global.props = propsProcessed
  }, [setProps])

  return <AppContainer />
}

2. 初始化状态管理器

// App.tsx
import { createDeviceStore, createDeviceListStore } from '@quec/panel-device-kit'

createDeviceStore()
createDeviceListStore()

3. 注册全局回调和监听事件

// AppContainer.tsx
import { deviceKitParamsManager, useInitUpdateDeviceStateEvent } from '@quec/panel-device-kit'

const AppContainer :FC = () => {
  const refreshDeviceList = useDeviceListRefresh()
  // 设备状态事件
  useInitUpdateDeviceStateEvent(
    updateDeviceStateCallback,  // 在离线状态更新回调
    updateDeviceConnectingStateCallback // 连接状态更新回调
    )
  // 设备更新事件
  useInitDeviceInfoUpdateEvent(() => {
    // 当使用到设备列表状态时，APP通知设备更新了，最好刷新一下设备列表
    refreshDeviceList()  
  })  
  //设备列表更新监听事件
  useInitDeviceListUpdateEvent({
    // 是否自动切换设备，常用于使用了设备列表的面板
        // 当前设备已经不复存在，更换列表第一个设备
        // 设备列表或当前设备为空时，跳转到业务面板
    enableAutoCheckoutDevice: true,  
    refreshDeviceListEventCallback: null,  // 设备列表更新监听事件主动回调
    refreshDeviceListSuccessCallback: null,  // APP通知刷新列表 => 主动刷新列表 => 刷新成功 => refreshDeviceListSuccessCallback(list)
  })  
  ...
  deviceKitParamsManager.registerCallbacks({
    loadingCallback: global.loading,
    loadingDismissCallback: global.loadingDismiss,
    tipCallback: global.toast,
  })
}

4. 在组件中使用状态

// anyPage.tsx
import { useDevice } from '@quec/panel-device-kit'
const AnyPage :FC = () => {

const device = useDevice()

useEffect(() => {
  console.log(device)
}, [device])

🧠 状态管理器 API

📍 设备状态

初始化

• createDeviceStore()：初始化设备状态管理器

查状态的 Hook

• useDeviceStoreState()：获取所有状态集合
• useDevice()：获取当前设备信息
• useDeviceProps()：获取初始传入参数
• useDeviceFamily()：获取家庭信息
• useDeviceArea()：获取区域信息
• useDeviceProductUrl()：获取产品说明书链接
• useDeviceOnline()：获取设备在线状态

请求状态的方法 Hook

• useGetDeviceStatus()：主动拉取设备状态
• useSetProps(props)：设置初始参数并同步更新设备
• useUpdateDevice(data)：更新设备信息
• useUpdateOnlineStatus(online)：更新在线状态
• useCheckCurrentDeviceExist()：检查当前设备是否还存在

扩展

• getDeviceStore()：获取 deviceStore 实例（未初始化会抛错）

📍 设备列表状态

初始化

• createDeviceListStore()：初始化设备列表状态管理器

查设备列表状态的 Hook

• useDeviceListStoreState()：获取所有状态集合
• useDeviceList()：获取设备列表

请求设备列表的方法 Hook

• useDeviceListRefresh()：刷新设备列表
• useDeviceListLoadMore()：加载下一页设备

扩展

• getDeviceListStore()：获取 deviceListStore 实例（未初始化会抛错）

🔁 设备(列表)状态事件监听器

useInitUpdateDeviceStateEvent() 监听设备状态更新

useInitDeviceListUpdateEvent() 监听设备列表监听事件更新

useInitDeviceInfoUpdateEvent() 监听设备更新事件

• 注册监听设备状态更新的全局 Hook。
• 通常应在 AppContainer.tsx 或入口组件中调用一次。

✉ 监听事件名称

| 监听事件名称 | 内容 | 说明 | | -------------------------------- | ------------------------- | -------------------- | | EVENT_TYPE_DEVICE_ONLINE | onDeviceOnlineState | 设备在离线状态更新 | | EVENT_TYPE_DEVICE_CONNECTING | onDeviceConnectingState | 设备连接状态更新 | | EVENT_TYPE_REFRESH_DEVICE_LIST | QuecRefreshDeviceList | 设备列表更新 | | EVENT_TYPE_REFRESH_DEVICE | QuecRefreshDeviceInfo | 设备更新（更换设备） |

🔧 回调管理器

deviceKitParamsManager

通过 registerCallbacks() 可传入以下回调函数：

| 回调名 | 说明 | | ------------------------ | ---------------- | | loadingCallback | 显示全局 loading | | loadingDismissCallback | 隐藏 loading | | tipCallback | 全局 toast 提示 |

🧾 类型导出

| 类型名 | 描述 | | ------------- | ---------------------------------- | | PropsModel | 初始传入参数类型 | | DeviceModel | 从PropsModel取出的设备信息类型 | | FamilyModel | 从PropsModel取出的用户家庭信息类型 |

🌐 多语言配置说明

⚠️ 提示类语言依赖于是否注册了 tipCallback 回调。

| key | 中文提示 | 英文提示 | | --------------------------------- | -------------- | -------------- | | quec_device_kit_device_offline | 设备离线 | device offline | | quec_device_kit_device_online | 设备上线 | -- | | quec_device_kit_no_more_devices | 没有更多设备了 | -- |

🛠 本地调试说明

如需修改本库并本地调试，请参考 👉 本地调试文档