数据类型

在 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,
    "enable": boolean,
    "time": string,
    "repeat": string,
    "tzOffset": number,
    "validFrom": string,
    "validTo": string,
    "actions": [
        {
            "seq": number,
            "trig": string,
            "type": string,
            "params": object,
            "delay": number
        }
    ]
}

字段说明：

id：可选，用于追踪去重。
enable：表示定时器是否启用，true 表示启用，false 表示禁用。
time：表示定时器的触发时间，格式为 HH:mm:ss。
repeat：表示定时器的重复设置，格式为 0123456，每个数字代表一周中的一天，0 表示周日，1 表示周一，以此类推。不可为空，不可包含重复日期。
tzOffset：时区偏移，单位是小时，范围为 -12 到 14。例如 8 表示东八区。
validFrom：可选，有效期开始日期，格式为 YYYY-MM-DD。
validTo：可选，有效期结束日期，格式为 YYYY-MM-DD。若同时设置，须满足 validFrom <= validTo。
actions：可选，动作列表。详见下方动作列表 actions。

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

json

{
    "switch_open_timer": {
        "enable": true,
        "time": "12:00:00",
        "repeat": "12345",
        "tzOffset": 8,
        "actions": [
            {
                "seq": 1,
                "trig": "start",
                "type": "attr",
                "params": {
                    "switch1": true
                }
            }
        ]
    }
}

daily_timer_range（每日定时区间）

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

json

{
    "id": string,
    "enable": boolean,
    "startTime": string,
    "endTime": string,
    "repeat": string,
    "tzOffset": number,
    "validFrom": string,
    "validTo": string,
    "actions": [
        {
            "seq": number,
            "trig": string,
            "type": string,
            "params": object,
            "delay": number
        }
    ]
}

字段说明：

id：可选，用于追踪去重。
enable：表示定时区间是否启用，true 表示启用，false 表示禁用。
startTime：表示定时区间的开始时间，格式为 HH:mm:ss。
endTime：表示定时区间的结束时间，格式为 HH:mm:ss。
repeat：表示定时区间的重复设置，格式为 0123456，每个数字代表一周中的一天，0 表示周日，1 表示周一，以此类推。
tzOffset：时区偏移，单位是小时，范围为 -12 到 14。例如 8 表示东八区。
validFrom：可选，有效期开始日期，格式为 YYYY-MM-DD。
validTo：可选，有效期结束日期，格式为 YYYY-MM-DD。
actions：可选，动作列表。trig 可取 start（开始时间触发）或 end（结束时间触发）。详见下方动作列表 actions。

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

json

{
    "switch_timer_range": {
        "enable": true,
        "startTime": "12:00:00",
        "endTime": "18:00:00",
        "repeat": "12345",
        "tzOffset": 8,
        "actions": [
            {
                "seq": 1,
                "trig": "start",
                "type": "attr",
                "params": {
                    "switch1": true
                }
            },
            {
                "seq": 2,
                "trig": "end",
                "type": "attr",
                "params": {
                    "switch1": false
                }
            }
        ]
    }
}

daily_timer_list（每日定时器列表）

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

数据类型的结构如下：

json

{
    "timer": [
        {
            "id": string,
            "enable": boolean,
            "time": string,
            "repeat": string,
            "validFrom": string,
            "validTo": string,
            "actions": []
        }
    ],
    "tzOffset": number
}

字段说明：

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

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

json

{
    "timer_list": {
        "timer": [
            {
                "enable": true,
                "time": "08:00:00",
                "repeat": "12345",
                "actions": [
                    {
                        "seq": 1,
                        "trig": "start",
                        "type": "attr",
                        "params": {
                            "switch1": true
                        }
                    }
                ]
            },
            {
                "enable": true,
                "time": "18:00:00",
                "repeat": "12345",
                "actions": [
                    {
                        "seq": 1,
                        "trig": "start",
                        "type": "attr",
                        "params": {
                            "switch1": false
                        }
                    }
                ]
            }
        ],
        "tzOffset": 8
    }
}

daily_timer_range_list（每日定时区间列表）

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

数据类型的结构如下：

json

{
    "timerRange": [
        {
            "id": string,
            "enable": boolean,
            "startTime": string,
            "endTime": string,
            "repeat": string,
            "validFrom": string,
            "validTo": string,
            "actions": []
        }
    ],
    "tzOffset": number
}

字段说明：

timerRange：定时区间数组，每个元素表示一个独立的定时区间设置，字段含义与 daily_timer_range 相同（列表内单项不再单独带 tzOffset）。
tzOffset：该属性下所有定时区间的统一时区偏移，单位是小时，范围为 -12 到 14。

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

json

{
    "timer_range_list": {
        "timerRange": [
            {
                "enable": true,
                "startTime": "08:00:00",
                "endTime": "18:00:00",
                "repeat": "12345",
                "actions": [
                    {
                        "seq": 1,
                        "trig": "start",
                        "type": "attr",
                        "params": {
                            "curtain": 100
                        }
                    },
                    {
                        "seq": 2,
                        "trig": "end",
                        "type": "attr",
                        "params": {
                            "curtain": 0
                        }
                    }
                ]
            },
            {
                "enable": true,
                "startTime": "09:00:00",
                "endTime": "17:00:00",
                "repeat": "06",
                "actions": [
                    {
                        "seq": 1,
                        "trig": "start",
                        "type": "attr",
                        "params": {
                            "curtain": 100
                        }
                    },
                    {
                        "seq": 2,
                        "trig": "end",
                        "type": "attr",
                        "params": {
                            "curtain": 0
                        }
                    }
                ]
            }
        ],
        "tzOffset": 8
    }
}

countdown（一次性倒计时）

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

数据类型的结构如下：

json

{
    "id": string,
    "enable": boolean,
    "tzOffset": number,
    "cdMs": number,
    "targetTs": number,
    "actions": [
        {
            "seq": number,
            "trig": string,
            "type": string,
            "params": object,
            "delay": number
        }
    ]
}

字段说明：

id：可选，任务 ID，用于追踪去重。
enable：表示倒计时是否启用，true 表示启用，false 表示禁用。
tzOffset：时区偏移，单位是小时，范围为 -12 到 14。例如 8 表示东八区。
cdMs：相对倒计时时长，单位是毫秒。例如 60000 表示 60 秒后执行。
targetTs：绝对执行时间戳，单位是毫秒。若传入秒级时间戳，平台会自动转换为毫秒。
actions：可选，动作列表，结构与每日定时器的动作一致。详见下方动作列表 actions。

提示

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

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

json

{
    "switch_off_countdown": {
        "enable": true,
        "tzOffset": 8,
        "cdMs": 60000,
        "actions": [
            {
                "seq": 1,
                "trig": "start",
                "type": "attr",
                "params": {
                    "switch1": false
                }
            }
        ]
    }
}

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

json

{
    "switch_off_countdown": {
        "enable": true,
        "tzOffset": 8,
        "targetTs": 1727856000000,
        "actions": [
            {
                "seq": 1,
                "trig": "start",
                "type": "attr",
                "params": {
                    "switch1": false
                }
            }
        ]
    }
}

动作列表 actions

定时类与倒计时类数据类型（daily_timer、daily_timer_range、daily_timer_list、daily_timer_range_list、countdown）均支持可选的 actions 动作列表，结构如下：

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：触发类型。start 表示定时触发或开始时间触发；end 表示结束时间触发（主要用于定时区间）。未指定时默认按 start 处理。
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（一次性倒计时） ​

动作列表 actions ​

数据类型

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（一次性倒计时）

动作列表 actions