📦@quec/panel-model-kit

QUEC Panel Model Kit 储存管理设备物模型信息

简单的物模型处理库

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

| 库名 | peerDependencies | devDependencies | | ------------------------ | ---------------- | --------------- | | @quec/panel-device-kit | * | > 0.1.x | | @quec/rn-device-module | * | 2.16.1 | | @quec/rn-log-module | * | 1.0.6 | | @quec/rn-router-module | * | 1.4.1 | | bignumber.js | * | 9.1.2 | | i18n-js | * | 4.1.1 | | react | * | 17.0.2 | | react-native | * | 0.64.3 | | zustand | * | 4.4.3 |

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

✅ 功能列表

1. 物模型状态管理
2. 物模型获取初步处理
3. 物模型格式统一
4. 物模型上报自动处理
5. 物模型下发处理

🧩 模块结构

本库主要包含以下模块：

1. 状态管理器
2. 事件监听器
3. 回调管理器（可选）

🚀 快速开始

1. 初始化状态管理器

// App.tsx
import { createDeviceModelStore, BooleanTSLModel, DateTSLModel } from '@quec/panel-model-kit'

type MyModelType = {
  aaBbbbCccc: BooleanTSLModel
  xxxYyyZzz: DateTSLModel
}

const store = createDeviceModelStore<MyModelType>()
export const useModel = createUseModel<MyModelType>(store)
// 这样有助于获取提示

2. 注册全局回调和物模型上行事件，并主动获取物模型

// AppContainer.tsx
import { modelKitParamsManager } from '@quec/panel-model-kit'

const AppContainer :FC = () => {
    const initModel = useModelInit()
    useEffect(() => {
      // 获取物模型
      if (device) {
        initModel(device.productKey, device.deviceKey)
      }
    }, [initModel, device])

    useInitUpdateDPSEvent({
        eventLocationCallBack, //定位信息事件回调
        eventCallBack,  // 其他事件回调
        reportTSLCallBack, // 物模型属性上报回调
        eventInfoCallBack  // 物模型事件信息回调
    })

    modelKitParamsManager.registerCallbacks({
        loadingCallback: global.loading,
        loadingDismissCallback: global.loadingDismiss,
        tipCallback: global.toast,
    })
}

3. 使用状态和读写物模型 Hook

// anyPage.tsx
import { useModel, useTslWriter, useTslRead } from '@quec/panel-model-kit'
const AnyPage :FC = () => {
    const models = useModel()
    const writer = useTslWriter({...})
    const reader = useTslRead({...})

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

    useEffect(() => {
      writer({
          data: model.xxx,
          value: val,
          ...
        })
      reader({
          data: model.xxx,
          ...
        })
    }, [xxx])
...
}

5. 使用modelsShallow监听单个物模型变化

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

  useEffect(() => {
    const unSubscribe = deviceModelStore.subscribe(
      state => (state.modelsShallow as ModelsType)['xxYyyZzzz'],
      (res: ModelsType['xxYyyZzzz']) => {
        // ...监听变化后的回调
      },
      {fireImmediately: false},
    )

    return () => {
        // 离开则取消订阅
      unSubscribe()
    }
  }, [getSelectedRoleMes])

...
}

🧠 状态管理器 API

📍 物模型状态

初始化

• createDeviceModelStore()：初始化物模型状态管理器，返回store
• createUseModel<T: YourModelsType >(store)： 根据上面的store返回useModel

状态获取

• useModelStoreState：获取所有状态
• useModel：获取当前物模型对象，取自createUseModel的返回

操作方法

• useModelInit()：主动初始获取物模型(会自动全部读取一次物模型的值)
• useSetModel：设置状态管理器里的物模型合集
• useTslWriter(): 下发物模型
• useTslRead(): 读取物模型

扩展

• getDeviceModelStore()：获取 store 实例（未初始化会报错）

状态

| 状态变量 | 说明 | | -------------------- | --------------------------------------------------------------------------------------------------- | | models | 存储物模型数据 | | modelsShallow | 存储物模型数据 只更改内部单个数据，引用不变，不会整体响应，可用于监听单个物模型变化（比如事件） | | isEmptyTsl | 获取到的物模型为空 | | isRequestTslFailed | 获取无物模型失败了 |

🔁 物模型状态监听器

useInitUpdateDPSEvent()

• 注册监听设备物模型状态更新的全局 Hook。
• 通常应在 AppContainer.tsx 或入口组件中调用一次。
• 如果单独使用监听器，可以传入回调处理上行的物模型。
• 事件EVENT_TYPE_DEVICE_DPS_UPDATE(可导出): onDeviceDpsUpdate

💬 写物模型

useTslWriter 写物模型的hook

writeFn 写物模型的方法，相较上面的方法减少了设备状态判断和通道选择自动判断

👁‍🗨 读物模型

useTslRead 读物模型的hook

ReadDpsWithMode 读物模型的方法，相较上面的方法减少了设备状态判断和通道选择自动判断和物模型处理的方法prepareReadDps

useTslAllRead 读全部物模型的hook 🚧（No Test）

🔧 回调管理器

modelKitParamsManager

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

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

🧾 类型定义

| 类型名 | 描述 | 备注 | | ------------------- | ----------------------------------------------------------------- | ---- | | TextTSLModel | 字符型物模型类型 | | | BooleanTSLModel | bool型物模型类型 | | | DateTSLModel | 日期型物模型类型 | | | EnumTSLModel | 枚举型物模型类型 | | | NumberTSLModel | 数值型物模型类型 | | | StructTSLModel | 结构体型物模型类型 | | | ArrayTSLModel | 数组型物模型类型 | | | EventTSLModel | 事件型物模型类型 | | | -- | -- | -- | | AnyTSL | 上面所有的物模型类型集合 | | | ComplexTSLModel | StructTSLModel | ArrayTSLModel | | | NormalTSLModel | 除了 StructTSLModel | ArrayTSLModel | EventTSLModel的物模型集合 | | | -- | -- | -- | | DPS | 用于下发和读取的数据点的格式 | | | DataPointModel | 用于下发和读取的数据点的格式 | | | -- | -- | -- | | Writer | useTslWriter的返回值类型 | | | WriterOptionsType | useTslWriter的参数类型 | |

🌐 多语言配置说明（可选）

⚠️ 注意：只有注册提示回调后，以下多语言 key 才生效。

| key | 中文提示 | 英文提示 | | ------------------------------ | -------------------- | -------- | | quec_model_kit_succeed_set | 设置成功 | | | quec_model_kit_failed_set | 设置失败 | | | quec_model_kit_write_offline | 设备离线，请稍后再试 | | | -- | | |

📌 扩展使用

如果开发者的逻辑过于复杂，不能直接使用封装好的hook，可以使用开放的方法自由组装使用

写物模型useTslWriter的封装内容：

 - 判断设备在线状态  
     - const isOnline = useDeviceOnline()
 - 处理输入的物模型  
     - const dps = prepareWriteDps(data, value)
 - 调用接口进行物模型下发   
     - QuecRNDeviceModule.writeDpsWithMode( dps)

🛠 开发调试（本地开发）

请参考 👉 本地调试文档