数据类型

在 ZhiLian.Yun 设备类型的功能定义中，可以为设备属性设置以下数据类型：

基本类型：

integer（整型）
decimal（小数）
string（字符串）
bool（布尔型）
enum（枚举型）
array（数组型）
object（对象型）

高级类型：

map_point（地理坐标）
map_circle（地理圆形围栏）
map_polygon（地理多边形围栏）
coords_point（平面坐标）
coords_3d_point（三维坐标）
daily_timer（每日定时器）
daily_timer_range（每日定时区间）
daily_timer_list（每日定时器列表）
daily_timer_range_list（每日定时区间列表）
countdown（一次性倒计时）

下面是各种数据类型的详细介绍。

integer（整型）

任意整数，例如：

附加选项：

单位（unit）
最小值（min）
最大值（max）
步长（step）
默认值（default）

提示

当设置整型属性的最大值或最小值后，如果上报的数值不符合该条件，ZhiLian.Yun 会拒绝处理。

例如，设备上报整型属性：

json

{
    "count": 10,
    "battery": 85
}

decimal（小数）

任意数值（浮点数），例如：

附加选项：

单位（unit）
小数位数（decimals）
最小值（min）
最大值（max）
步长（step）
默认值（default）

提示

当设置小数属性的最大值或最小值后，如果上报的数值不符合该条件，ZhiLian.Yun 会拒绝处理。设置小数位数后，平台会按指定精度对上报数值进行格式化。

例如，设备上报小数型属性：

json

{
    "temperature": 23.2,
    "humidity": 56.1
}

decimal（小数）类型的属性，可以用来定义绝大多数用数字表示的设备参数，例如：

属性名称	标识符	单位	示例值
温度	temperature	摄氏度/华氏度	25.6°C, 78.1°F
湿度	humidity	%	45.0%
压力	pressure	百帕斯卡/英寸汞柱	1013 hPa, 29.92 inHg
电压	voltage	伏特	220V, 5V
电流	current	安培/毫安	10A, 0.5mA
功率	power	瓦/毫瓦	100W, 1500mW
亮度	brightness	流明/坎德拉	800 lm, 1000 cd
速度	speed	公里/小时/英里/小时	60 km/h, 35 mph
距离	distance	米/千米	10m, 5km
高度	height	米/英尺	1.75m, 5000ft
重量	weight	公斤/磅	70kg, 150lb
流量	flow_rate	升/分钟/立方米/小时	100 L/min, 50 m³/h
频率	frequency	赫兹/吉赫兹	50Hz, 2.4GHz
时间长度	duration	秒/小时	3600秒, 1.5小时
浓度	concentration	微克/立方米/毫克/立方米	500 μg/m³, 0.08 mg/m³

string（字符串）

Plaintext 字符串，例如：

text

auto

附加选项：

最大长度（maxLength）
默认值（default）

例如，设备上报字符串型属性：

json

{
    "mode": "auto"
}

bool（布尔型）

bool 布尔型用于表示两种状态，例如 LED 的开/关，继电器的闭合/断开。

平台存储和展示使用布尔类型，如下：

json

true/false

例如，设备上报布尔型属性：

json

{
    "switch1": false,
    "switch2": true
}

为了支持各种硬件设备上不同的开关量表达方式，布尔型允许在设备和云平台之间的消息中使用多种值类型，如下：

布尔类型

json

true/false

整数类型

json

1/0

文本类型

json

ON/OFF
on/off
yes/no
true/false

需要注意的是，选择不同的值类型，只影响设备端上报属性和接收下发属性中的布尔值表达方式，并不影响这个属性值在平台上的存储和展示方式。在控制台或 API 中下发布尔型属性时，应始终使用 true/false 布尔类型值。

附加选项：

true 文字（trueText）
false 文字（falseText）
下发设备值类型（boolDataType），可选：
- bool(true/false)
- integer(1/0)
- string(true/false)
- string(TRUE/FALSE)
- string(True/False)
- string(on/off)
- string(ON/OFF)
- string(On/Off)
- string(yes/no)
- string(YES/NO)
- string(Yes/No)

enum（枚举型）

enum 类型的属性值，本身是一种文本或整数类型，区别在于必须在限定的多个枚举值中取值。

附加选项：

枚举列表（enumList）：键值对，键为枚举值，值为显示名称
枚举值下发设备值类型（enumDataType）：integer 或 string
默认值（default）

例如，设备上报枚举型属性 mode，用数值来表示工作模式，如下：

json

{
    "mode": "1"
}

或者用字符串来表示工作模式，如下：

json

{
    "mode": "auto"
}

array（数组型）

json

[
    value1,
    value2,
    value3
]

附加选项：

数组元素类型（arrayDataType）：可选 integer、decimal、string、bool
最大长度（maxLength）

例如，设备上报数组型属性 data：

json

{
    "data": [
        1,
        3,
        5
    ]
}

object（对象型）

json

{
    "key1": value1,
    "key2": value2,
    "key3": value3
}

例如，设备上报对象型属性 data：

json

{
    "data": {
        "temperature": 31.2,
        "switch": true,
        "mode": "1"
    }
}

map_point（地理坐标）

该数据类型用于表示地理坐标，可在电子围栏等规则中使用。

该数据类型的结构如下：

json

{
    "lat": number,
    "lng": number
}

请注意：以上的字段值都是数值格式，而不是字符串格式，不要加双引号。

lat：纬度，范围为 -90 到 90 度。
lng：经度，范围为 -180 到 180 度。

例如，设备上报地理坐标型属性 location：

json

{
    "location": {
        "lat": 41.0203,
        "lng": 38.3183
    }
}

map_circle（地理圆形围栏）

该数据类型用于表示地理圆形围栏，可在电子围栏规则中使用。

该数据类型的结构如下：

json

{
    "centerPoint": {
        "lat": number,
        "lng": number
    },
    "radius": number
}

centerPoint：圆形区域的中心点位置。
radius：圆形的半径，单位是米。

例如，设备上报地理圆形围栏型属性 map_circle：

json

{
    "map_circle": {
        "centerPoint": {
            "lat": 41.0203,
            "lng": 38.3189
        },
        "radius": 500
    }
}

map_polygon（地理多边形围栏）

该数据类型用于表示地理多边形围栏，可在电子围栏规则中使用。

该数据类型的结构如下：

json

{
    "points": [
        {
            "lat": number,
            "lng": number
        },
        {
            "lat": number,
            "lng": number
        },
        {
            "lat": number,
            "lng": number
        }
    ]
}

例如，通过 API 更新设备的地理多边形围栏属性 map_polygon：

json

{
    "map_polygon": {
        "points": [
            {
                "lat": 38.462,
                "lng": 140.391
            },
            {
                "lat": 39.462,
                "lng": 140.391
            },
            {
                "lat": 39.462,
                "lng": 141.391
            },
            {
                "lat": 38.462,
                "lng": 141.391
            }
        ]
    }
}

coords_point（平面坐标）

该数据类型用于表示平面坐标。

该数据类型的结构如下：

json

{
    "x": number,
    "y": number
}

请注意：以上的字段值都是数值格式，而不是字符串格式，不要加双引号。

x：平面坐标的 x 轴值。
y：平面坐标的 y 轴值。

例如，设备上报平面坐标型属性 position：

json

{
    "position": {
        "x": 0.5,
        "y": 0.7
    }
}

coords_3d_point（三维坐标）

该数据类型用于表示三维坐标。

该数据类型的结构如下：

json

{
    "x": number,
    "y": number,
    "z": number
}

请注意：以上的字段值都是数值格式，而不是字符串格式，不要加双引号。

x：三维坐标的 x 轴值。
y：三维坐标的 y 轴值。
z：三维坐标的 z 轴值。

例如，设备上报三维坐标型属性 position：

json

{
    "position": {
        "x": 0.5,
        "y": 0.7,
        "z": 0.2
    }
}

daily_timer（每日定时器）

该数据类型用于表示每日定时设置，结构如下：

json

{
    "id": string,
    "en": number,
    "time": string,
    "repeat": string,
    "tz": number,
    "vF": string,
    "vT": string,
    "acts": [
        {
            "seq": number,
            "trig": string,
            "type": string,
            "params": object,
            "delay": number
        }
    ],
    "actAttr": string
}

字段说明：

id：可选，用于追踪去重，例如 t1。
en：是否启用，仅允许 0（否）或 1（是）。
time：表示定时器的触发时间，格式为 HH:mm:ss。
repeat：表示定时器的重复设置，格式为 0123456，每个数字代表一周中的一天，0 表示周日，1 表示周一，以此类推。不可为空，不可包含重复日期。
tz：时区偏移，单位是小时，范围为 -12 到 14。例如 8 表示东八区。
vF：可选，有效期开始日期，格式为 YYYY-MM-DD。
vT：可选，有效期结束日期，格式为 YYYY-MM-DD。若同时设置，须满足 vF <= vT。
acts：可选，内联动作列表。与 actAttr 二选一。详见下方动作列表 acts。本类型中 trig 仅允许 s。
actAttr：可选，动作绑定属性标识，指向存放动作列表的属性（例如 acts1）。与 acts 二选一，不可同时填写。标识须以字母或下划线开头，仅含字母、数字和下划线。

例如，平台下发到设备的定时器属性 switch_open_timer，表示定时器启用，时间为周一到周五每天的 12:00:00：

json

{
    "switch_open_timer": {
        "en": 1,
        "time": "12:00:00",
        "repeat": "12345",
        "tz": 8,
        "acts": [
            {
                "seq": 1,
                "trig": "s",
                "type": "attr",
                "params": {
                    "switch1": true
                }
            }
        ]
    }
}

也可以通过 actAttr 引用独立属性中的动作列表：

json

{
    "switch_open_timer": {
        "en": 1,
        "time": "12:00:00",
        "repeat": "12345",
        "tz": 8,
        "actAttr": "acts1"
    }
}

daily_timer_range（每日定时区间）

该数据类型用于表示每日定时区间设置，结构如下：

json

{
    "id": string,
    "en": number,
    "sTime": string,
    "eTime": string,
    "repeat": string,
    "tz": number,
    "vF": string,
    "vT": string,
    "acts": [
        {
            "seq": number,
            "trig": string,
            "type": string,
            "params": object,
            "delay": number
        }
    ],
    "actAttr": string
}

字段说明：

id：可选，用于追踪去重。
en：是否启用，仅允许 0（否）或 1（是）。
sTime：表示定时区间的开始时间，格式为 HH:mm:ss。
eTime：表示定时区间的结束时间，格式为 HH:mm:ss。
repeat：表示定时区间的重复设置，格式为 0123456，每个数字代表一周中的一天，0 表示周日，1 表示周一，以此类推。
tz：时区偏移，单位是小时，范围为 -12 到 14。例如 8 表示东八区。
vF：可选，有效期开始日期，格式为 YYYY-MM-DD。
vT：可选，有效期结束日期，格式为 YYYY-MM-DD。
acts：可选，内联动作列表。与 actAttr 二选一。本类型中 trig 可取 s（开始时间触发）或 e（结束时间触发）。详见下方动作列表 acts。
actAttr：可选，动作绑定属性标识，指向存放动作列表的属性（例如 acts1）。与 acts 二选一，不可同时填写。

例如，平台更新某设备开关的定时区间属性 switch_timer_range，表示周一到周五每天 12:00:00 开启、18:00:00 关闭：

json

{
    "switch_timer_range": {
        "en": 1,
        "sTime": "12:00:00",
        "eTime": "18:00:00",
        "repeat": "12345",
        "tz": 8,
        "acts": [
            {
                "seq": 1,
                "trig": "s",
                "type": "attr",
                "params": {
                    "switch1": true
                }
            },
            {
                "seq": 2,
                "trig": "e",
                "type": "attr",
                "params": {
                    "switch1": false
                }
            }
        ]
    }
}

daily_timer_list（每日定时器列表）

该数据类型用于表示多个每日定时设置，适用于需要在一个属性中管理多个定时器的场景，例如智能插座的多组定时开关。

数据类型的结构如下：

json

{
    "timer": [
        {
            "id": string,
            "en": number,
            "time": string,
            "repeat": string,
            "vF": string,
            "vT": string,
            "acts": [],
            "actAttr": string
        }
    ],
    "tz": number
}

字段说明：

timer：定时器数组，每个元素表示一个独立的定时器设置，字段含义与 daily_timer 相同（列表内单项不再单独带 tz；同样支持 acts / actAttr 二选一）。
tz：该属性下所有定时器的统一时区偏移，单位是小时，范围为 -12 到 14。

例如，平台下发到设备的定时器列表属性 timer_list，包含两个定时器，分别表示工作日早上 8 点开启和晚上 18 点关闭：

json

{
    "timer_list": {
        "timer": [
            {
                "en": 1,
                "time": "08:00:00",
                "repeat": "12345",
                "acts": [
                    {
                        "seq": 1,
                        "trig": "s",
                        "type": "attr",
                        "params": {
                            "switch1": true
                        }
                    }
                ]
            },
            {
                "en": 1,
                "time": "18:00:00",
                "repeat": "12345",
                "acts": [
                    {
                        "seq": 1,
                        "trig": "s",
                        "type": "attr",
                        "params": {
                            "switch1": false
                        }
                    }
                ]
            }
        ],
        "tz": 8
    }
}

daily_timer_range_list（每日定时区间列表）

该数据类型用于表示多个每日定时区间设置，适用于需要在一个属性中管理多个定时区间的场景，例如智能窗帘的多组开合时间。

数据类型的结构如下：

json

{
    "tR": [
        {
            "id": string,
            "en": number,
            "sTime": string,
            "eTime": string,
            "repeat": string,
            "vF": string,
            "vT": string,
            "acts": [],
            "actAttr": string
        }
    ],
    "tz": number
}

字段说明：

tR：定时区间数组，每个元素表示一个独立的定时区间设置，字段含义与 daily_timer_range 相同（列表内单项不再单独带 tz；同样支持 acts / actAttr 二选一，且 trig 允许 e）。
tz：该属性下所有定时区间的统一时区偏移，单位是小时，范围为 -12 到 14。

例如，平台更新某设备的定时区间列表属性 timer_range_list，包含两组定时区间，分别表示工作日和周末的不同开合时间：

json

{
    "timer_range_list": {
        "tR": [
            {
                "en": 1,
                "sTime": "08:00:00",
                "eTime": "18:00:00",
                "repeat": "12345",
                "acts": [
                    {
                        "seq": 1,
                        "trig": "s",
                        "type": "attr",
                        "params": {
                            "curtain": 100
                        }
                    },
                    {
                        "seq": 2,
                        "trig": "e",
                        "type": "attr",
                        "params": {
                            "curtain": 0
                        }
                    }
                ]
            },
            {
                "en": 1,
                "sTime": "09:00:00",
                "eTime": "17:00:00",
                "repeat": "06",
                "acts": [
                    {
                        "seq": 1,
                        "trig": "s",
                        "type": "attr",
                        "params": {
                            "curtain": 100
                        }
                    },
                    {
                        "seq": 2,
                        "trig": "e",
                        "type": "attr",
                        "params": {
                            "curtain": 0
                        }
                    }
                ]
            }
        ],
        "tz": 8
    }
}

countdown（一次性倒计时）

该数据类型用于表示一次性倒计时任务，适用于延时关闭、临时任务等场景。

数据类型的结构如下：

json

{
    "id": string,
    "en": number,
    "tz": number,
    "cdMs": number,
    "targTs": number,
    "acts": [
        {
            "seq": number,
            "trig": string,
            "type": string,
            "params": object,
            "delay": number
        }
    ],
    "actAttr": string
}

字段说明：

id：可选，任务 ID，用于追踪去重。
en：是否启用，仅允许 0（否）或 1（是）。
tz：时区偏移，单位是小时，范围为 -12 到 14。例如 8 表示东八区。
cdMs：相对倒计时时长，单位是毫秒。例如 60000 表示 60 秒后执行。
targTs：绝对执行时间戳，单位是毫秒。若传入秒级时间戳，平台会自动转换为毫秒。
acts：可选，内联动作列表，结构与每日定时器的动作一致。与 actAttr 二选一。本类型中 trig 仅允许 s。详见下方动作列表 acts。
actAttr：可选，动作绑定属性标识，指向存放动作列表的属性（例如 acts1）。与 acts 二选一，不可同时填写。

提示

cdMs 与 targTs 至少填写一个，且均须 >= 0。cdMs 表示从当前时刻起的相对等待时长，targTs 表示指定的绝对执行时间。

例如，平台下发到设备的倒计时属性 switch_off_countdown，表示 60 秒后关闭开关：

json

{
    "switch_off_countdown": {
        "en": 1,
        "tz": 8,
        "cdMs": 60000,
        "acts": [
            {
                "seq": 1,
                "trig": "s",
                "type": "attr",
                "params": {
                    "switch1": false
                }
            }
        ]
    }
}

也可以使用绝对时间戳方式：

json

{
    "switch_off_countdown": {
        "en": 1,
        "tz": 8,
        "targTs": 1727856000000,
        "acts": [
            {
                "seq": 1,
                "trig": "s",
                "type": "attr",
                "params": {
                    "switch1": false
                }
            }
        ]
    }
}

动作列表 acts

定时类与倒计时类数据类型（daily_timer、daily_timer_range、daily_timer_list、daily_timer_range_list、countdown）可通过以下两种方式之一提供动作：

内联 acts：直接在定时/倒计时结构中写入动作列表。
外置 actAttr：填写动作绑定属性标识，指向另一个属性中存放的动作列表。

提示

acts 与 actAttr 二选一，不可同时填写。若填写 actAttr，平台下行时会清空 acts。actAttr 须为合法属性标识：以字母或下划线开头，仅含字母、数字和下划线。

内联 acts 中每个动作项结构如下：

json

{
    "seq": number,
    "id": string,
    "cond": string,
    "trig": string,
    "type": string,
    "params": object,
    "delay": number,
    "goto": string
}

字段说明：

seq：可选，动作序号，用于排序。
id：可选，动作 ID，用于追踪去重；同一动作列表中不可重复。当使用 goto 跳转时，目标动作需要设置 id。
cond：可选，前置条件表达式。只有条件成立时才执行该动作。支持的变量模板：
- ${attr:xxx}：设备属性，例如 ${attr:humidity} > 60
- ${run:round}：当前回合 / 运行轮次，例如 ${run:round} >= 1
- ${run:runMs}：任务实例累计运行时长（毫秒）
- ${run:trigTs}：本次触发事件的时间戳（毫秒）
- ${time:hour}：当前小时（0~23）
- ${time:minute}：当前分钟（0~59）
- ${time:weekday}：星期，0 表示周日，1~6 表示周一到周六，与 repeat 字段对齐
- 运算符：>、>=、<、<=、==、!=、&&、||、()；字符串使用双引号
trig：触发类型，可选。未指定时默认按 s 处理。
- s：定时触发或开始时间触发。适用于所有定时类与倒计时类型。
- e：结束时间触发。仅 daily_timer_range / daily_timer_range_list 允许；在 daily_timer、daily_timer_list、countdown 中使用会校验失败。
type：动作类型，必填。可选值：
- attr：属性改变，需提供 params
- cmd：执行指令，需提供 params
- delay：延时
- goto：跳转到指定动作，需提供 goto，且目标动作的 id 必须存在于当前动作列表中
- none：空动作
params：动作参数。当 type 为 attr 或 cmd 时必填。
delay：延时时长，单位是毫秒。当 type 为 delay 时使用，须 >= 0。
goto：跳转目标动作 ID。当 type 为 goto 时必填。

前置条件示例：

text

${attr:humidity} > 60 && ${attr:status} == "working"
${run:runMs} > 30000
${run:round} < 10 || ${time:hour} < 22

数据类型 ​

integer（整型） ​

decimal（小数） ​

string（字符串） ​

bool（布尔型） ​

enum（枚举型） ​

array（数组型） ​

object（对象型） ​

map_point（地理坐标） ​

map_circle（地理圆形围栏） ​

map_polygon（地理多边形围栏） ​

coords_point（平面坐标） ​

coords_3d_point（三维坐标） ​

daily_timer（每日定时器） ​

daily_timer_range（每日定时区间） ​

daily_timer_list（每日定时器列表） ​

daily_timer_range_list（每日定时区间列表） ​

countdown（一次性倒计时） ​

动作列表 acts ​

数据类型

integer（整型）

decimal（小数）

string（字符串）

bool（布尔型）

enum（枚举型）

array（数组型）

object（对象型）

map_point（地理坐标）

map_circle（地理圆形围栏）

map_polygon（地理多边形围栏）

coords_point（平面坐标）

coords_3d_point（三维坐标）

daily_timer（每日定时器）

daily_timer_range（每日定时区间）

daily_timer_list（每日定时器列表）

daily_timer_range_list（每日定时区间列表）

countdown（一次性倒计时）

动作列表 acts