quec-panel-template

移远 RN 面板模版工程 2.0（对公版本），基于 React Native 0.81 + React 19 构建，集成移远 IoT 全套 SDK，用于快速开发设备控制面板。

技术栈

• React Native 0.81.1 + React 19.1.0
• TypeScript
• React Navigation 7（原生栈导航）
• Zustand 5（状态管理）
• i18n-js（多语言）

项目结构

quec-panel-template/
├── index.js                    # 入口文件
├── src/
│   ├── App.tsx                 # 应用根组件（初始化设备/物模型 Store）
│   ├── AppContainer.tsx        # 应用容器（初始化主题、事件监听、全局方法）
│   ├── api/                    # HTTP 请求封装
│   ├── assets/image/           # 图片资源（支持明暗主题）
│   ├── components/             # 通用业务组件
│   │   ├── empty-view/         # 空状态视图
│   │   ├── loading/            # 加载指示器
│   │   ├── net-error/          # 网络错误视图
│   │   ├── quec-container/     # 页面容器（含 Header）
│   │   └── quec-header/        # 自定义导航头
│   ├── config/                 # 配置文件
│   │   ├── color.config.ts     # 主题颜色配置（明/暗）
│   │   ├── image.config.ts     # 主题图片配置（明/暗）
│   │   ├── dp.config.ts        # 数据点类型常量
│   │   ├── device.config.ts    # 设备类型/状态常量
│   │   └── route-page.config.ts # 路由页面名称
│   ├── hooks/                  # 自定义 Hooks
│   │   ├── theme.ts            # 主题相关 Hooks（颜色、图片、明暗模式）
│   │   ├── use-navigation.hook.ts
│   │   ├── use-init-event.hook.ts
│   │   └── use-go-back.hook.ts
│   ├── i18n/                   # 多语言
│   │   ├── i18n.ts             # 多语言入口（开发用本地，线上用远程）
│   │   └── locales/            # 语言文件（zh / en）
│   ├── page/                   # 业务页面
│   │   ├── main-page/          # 首页（物模型操作演示）
│   │   ├── alarm-fault-page/   # 告警故障页
│   │   └── setting-page/       # 设置页
│   ├── router/                 # 路由配置
│   ├── style/                  # 基础样式
│   ├── types/                  # TypeScript 类型定义
│   └── util/                   # 工具函数

移远 SDK 依赖说明

核心依赖

| 包名 | 版本 | 说明 | |------|------|------| | @quec/panel-components-kit | 0.16 | 面板 UI 组件库（详见下方） | | @quec/panel-business-kit | 0.1.4 | 业务组件库（PageContainer 等） | | @quec/panel-device-kit | 1.1.0 | 设备管理（设备信息、状态、在线监听） | | @quec/panel-model-kit | 1.0.12 | 物模型管理（TSL 读写、状态订阅） | | @quec/panel-theme-kit | 0.1.4 | 主题管理（明暗模式切换） | | @quec/panel-theme-kit-config | 1.1.2 | 主题配置常量（颜色、图片、字体样式） |

原生桥接模块

| 包名 | 说明 | |------|------| | @quec/rn-device-module | 设备原生桥接 | | @quec/rn-router-module | 路由原生桥接 | | @quec/rn-network-module | 网络状态检测 | | @quec/rn-language-module | 远程多语言 | | @quec/rn-user-module | 用户信息/消息 | | @quec/rn-log-module | 日志模块 | | @quec/rn-tab-module | Tab 切换模块 | | @quec/rn-businesspanel-module | 业务面板模块 |

业务组件

| 包名 | 说明 | |------|------| | @quec/panel-universalsetting-component | 通用设置页组件（设备名称、离线提醒、产品说明等） | | @quec/panel-component-customer-attrs | 自定义属性组件 | | @quec/react-native-easy-toast | Toast 轻提示 |

@quec/panel-components-kit 组件库

为什么使用 panel-components-kit 而不是原生 RN 组件？

1. 主题自动适配，无需手动管理样式

原生 RN 组件（如 View、Text、Button）不具备主题感知能力。要实现明暗模式切换，开发者需要在每个组件上手动读取当前主题、条件判断颜色值，代码中充斥大量 colors.xxx 的样式拼接。而 panel-components-kit 的所有组件内部已经接入了 @quec/panel-theme-kit 的主题系统——只需在应用启动时通过 setComponentThemeHooks 注入一次主题 Hooks，之后所有组件的颜色、图片、字体都会自动跟随 APP 的明暗模式切换，开发者无需关心任何主题逻辑。

2. IoT 面板场景的专属组件，减少重复造轮子

原生 RN 只提供最基础的 UI 原语，而 IoT 面板开发中高频出现的交互模式（如设备属性单元格 Cell.Switch、动作面板 ActionSheet.Option、电池电量图标 Icon.Battery、环形进度条 NutCircle 等）都需要从零搭建。panel-components-kit 将这些 IoT 场景下的通用 UI 模式封装为开箱即用的组件，与移远设备 SDK 的数据结构天然契合，大幅减少重复开发工作量，同时保证各面板之间的 UI 一致性。

初始化

组件库需要在应用启动时注入主题 Hooks：

// src/hooks/theme.ts
import { setComponentThemeHooks } from '@quec/panel-components-kit'
import { createThemeStore } from '@quec/panel-theme-kit'

const { useThemeColors, useThemeImg, useThemeStatusBarStyle, ... } = createThemeStore({ ... })

setComponentThemeHooks({
    useComponentThemeColor: useThemeColors,
    useComponentThemeImg: useThemeImg,
    useThemeStatusBarStyle: useThemeStatusBarStyle,
})

可用组件一览

组件库涵盖布局、基础、表单、数据展示、反馈、滚动六大类，主要包括：

• 布局：Layout.Header / Layout.Card / Layout.Cell / Layout.Grid、Stack、NutRow / NutColumn、NutFlex、Fixed、NutWingBlank / NutWhiteSpace
• 基础：Button（含 Button.Shadow）、Icon（含 Icon.Battery）、NutImage、NutTag、Divider
• 表单：Input、NutTextArea、Switch / Cell.Switch、NutCheckBox / NutCheckboxGroup、Slider、NutSteps / NutStep
• 数据展示：Cell / CellGroup、NutGrid / NutGridItem、NutTabs / TabPane、NutCircle
• 反馈：ActionSheet（含 .Option / .Panel）、Dialog.Confirm / Dialog.Follow / Dialog.Prompt、Loading
• 滚动：ScrollView、HorizontalScrollView、PullToRefresh、Shadow、CommonContainer

所有组件均从 @quec/panel-components-kit 统一导入：

import { Button, Cell, CellGroup, ActionSheet, Dialog, Icon } from '@quec/panel-components-kit'

核心流程

应用初始化流程

App.tsx
  ├── setupI18n()                    # 初始化多语言
  ├── setupNativeStyle()             # 固定字体大小
  ├── createDeviceModelStore()       # 创建物模型 Store
  ├── createDeviceStore()            # 创建设备 Store
  └── <AppContainer />
        ├── useInitTheme()           # 请求 APP 明暗模式
        ├── useModelInit()           # 请求设备物模型
        ├── useGetDeviceStatus()     # 获取设备在线状态
        ├── useInitEvent()           # 监听返回键
        ├── useInitUpdateDeviceStateEvent()  # 监听设备状态更新
        ├── useInitUpdateDPSEvent()  # 监听物模型上行数据
        ├── registerCallbacks()      # 注册 loading/toast 回调
        └── <AppRouter />            # 路由导航

物模型读写

// App.tsx 中创建物模型 Hook
import { createDeviceModelStore, createUseModel } from '@quec/panel-model-kit'
const store = createDeviceModelStore()
export const useModel = createUseModel<ModelsType>(store)

// 页面中使用
import { useTslWriter } from '@quec/panel-model-kit'
import { useModel } from '../../App'

const models = useModel()       // 读取所有物模型属性
const write = useTslWriter()    // 获取写入方法

// 下发单个属性
write({
    data: models.switch_bool,   // 物模型属性
    value: 'true',              // 下发值
})

// 批量下发
write({
    data: [
        { attr: models.switch_bool, value: 'true' },
        { attr: models.temperature, value: '25' },
    ],
})

页面路由

// src/config/route-page.config.ts
export const PAGE_MAIN_DEMO = 'Main'
export const PAGE_ALARM_FAULT = 'AlarmFaultPage'
export const PAGE_SETTING = 'SettingPage'

// 页面跳转
import { useNavigation } from '../../hooks'
const navigation = useNavigation()
navigation.push(PAGE_ALARM_FAULT)
navigation.navigate(PAGE_SETTING, { device })

常用命令

# 安装依赖
yarn

# 启动 Metro
yarn start

# 运行 Android
yarn android

# 运行 iOS
yarn ios

# 打包 Android Bundle
yarn package:android

# 打包 iOS Bundle
yarn package:ios

# 构建面板
yarn build:panel

# 新增页面
yarn addPage

# 生成物模型类型
yarn getModelTypes

# 生成资源类型
yarn gen:assets

# 代码检查
yarn lint

新增页面

运行 yarn addPage 脚本，按提示输入页面名称即可自动生成页面模板文件并注册路由。

主题适配

在 src/config/color.config.ts 和 src/config/image.config.ts 中分别配置明/暗模式的颜色和图片：

// color.config.ts
export const lightColors = {
    // 自定义浅色主题颜色
}
export const darkColors = {
    // 自定义深色主题颜色
}

页面中通过 Hooks 获取当前主题资源：

import { useThemeColors, useThemeImg } from '../hooks/theme'

const colors = useThemeColors()  // 获取当前主题颜色
const images = useThemeImg()     // 获取当前主题图片