小机云

组件语义（IoT） ​

本文说明字段变化会让组件产生什么变化，供开发者或 AI 写固件时查阅。 「页面上有哪些字段」看控制台导出的组件描述。本文只收录写错就会错的条目。

# 数据方向 ​

direction含义固件要做的事
in只输入只上报，设备不要等这个字段下发
out只输出只接收，页面不会因设备上报而改变
inout双向既要处理下发，也要上报

# 值的形态 ​

IoT 项目走 MQTT，数据是 JSON 对象，不是 $X 文本帧：

json
{ "switch": true, "slider": 35, "items": ["a", "c"] }
  • 布尔用 true/false（也兼容 1/0）。
  • 数组用 JSON 数组，不要拼逗号字符串。
  • 对象字段（deviceState）按子项上报，见下。

# 各组件 ​

开关 SwitchFragment ​

  • 字段：switch，Boolean，inout
  • 只在状态变化时上报，不要周期性重复发送

切换 ToggleFragment ​

  • 字段：enabled，Boolean，inout
  • 注意：bindKey 是 enabled，不是 switch

滑块 SliderFragment ​

  • 字段：slider，Float，inout
  • 量程/步进以组件描述为准；默认松手才发送

滑块组 / 数值组 ​

  • 一槽一字段：slider1、slider2……，数量由页面配置决定，不写死

选择按钮 CheckboxFragment ​

  • 字段：item，单选为字符串、多选为数组，inout
  • 值来自页面里配置的 items[].value

选项组 CheckboxGroupFragment ​

  • 一槽一字段：group1、group2……，单选/多选按行配置

下拉选择 SelectFragment ​

  • 字段：selected，String，inout
  • 值是 options 的 value，不是显示文本

方向键 ArrowKeyFragment ​

  • 字段：up、down、left、right、ok，String，out
  • 按下发值、释放发空

颜色选择器 ColorPickerFragment ​

  • 字段：color，Color，inout，值形如 #RRGGBB

按钮 ButtonFragment ​

  • 没有 bindKey，点击发送的是页面里配置的内容
  • 写固件前必须向用户确认按钮发什么

曲线图 LineMarkerFragment ​

  • 没有 bindKey，按 series 的 key 接收，追加而不是替换

设备状态 DeviceStateFragment ​

  • 字段：deviceState，Object，in
  • 子项：
    • rssi：信号强度 0~31
    • capacity：电量 0~100，101 表示充电中
    • online：在线状态由平台维护，设备不需要上报
  • 三个子项是否显示由页面配置决定，但协议里可以都发

显示类组件 ​

数字滚动、仪表盘、进度条、水位、电池、文本、接收器等：direction 基本是 in，设备只上报。

# IoT 端专属约束 ​

  • 设备状态包含 rssi（与蓝牙不同），单位与量程见上。
  • 视频组件在 IoT / WiFi 项目中可用。
  • 重力传感器、指南针在 IoT 项目中不可用。
  • 没有二进制转换表，不存在 hex 位表。

# 写代码前的自查 ​

  1. 每个 out 字段都有明确触发点，不是周期发送。
  2. 布尔用 true/false，数组用 JSON 数组。
  3. ToggleFragment 用 enabled，SwitchFragment 用 switch。
  4. 组类组件的字段数量按页面实际配置。
  5. deviceState.capacity == 101 表示充电中，不是 101% 电量。

# 相关文档 ​