云函数内置函数库

约 10244 字大约 34 分钟

云函数内置函数库

ThingsCloud 平台在消息规则和任务中广泛支持云函数的使用，允许您通过编写 JavaScript 代码来实现复杂的逻辑和数据处理，帮助您根据自己的具体需求来编写处理过程。

为了进一步增强这种能力，ThingsCloud 还提供了一系列的内置函数工具。这些工具覆盖了设备和属性查询、数据类型转换、时间处理等常见需求，从而极大地简化了云函数开发的难度。

您可以直接在自己的云函数代码中调用这些内置函数，实现快速开发，这不仅提高了开发效率，也使得维护和更新变得更加方便。

示例

设备信息

Cloud.getDeviceInfo()

读取当前设备信息。

参数

无

返回值

object 类型，设备信息键值对集合，例如：

{
    "id": "sw52w1ps",           // 设备 ID
    "name": "DTU-5728",         // 设备名称
    "type": "dms60h1k",         // 所属设备类型 ID
    "tags": {},                 // 设备 Tags
    "device_key": "867135052265477",    // 设备唯一标识符
    "device_code": "82595616",  // 设备码，用户可输入设备码或扫码添加设备
    "sub_device_addr": "",      // 子设备地址，仅对子设备有效。
    "sub_device_addr_hex": ""   // 子设备地址 HEX 格式，仅对 Modbus 子设备有效。
}

设备属性

Cloud.getCurrentAttributes()

读取设备所有属性当前值。

参数

无

返回值

object 类型，设备属性当前值的键值对集合，例如：

{
    "activity": 0,
    "battery": 69,
    "co2": 855,
    "humidity": 36.5,
    "illumination": 34,
    "infrared": 15
}

示例

举个简单的例子，我们将 小米 Zigbee 无线按键 通过智能网关接入 ThingsCloud，这是一个功能强大的多状态按键，不像通常的智能开关只有 ON/OFF 两个状态，它支持 单击、双机、三击、长按 共四个状态。

当按键每次被单击时，会上报属性，如下：

{
    "click": "single"
}

假如我们希望通过单击按键来切换灯泡的开关，可我们并不知道这次单击是开灯还是关灯。这时我们可以利用如下预处理函数，来生成一个新的状态，表示按键的虚拟开关状态。

module.exports = function (report_attributes) {
     
    if (report_attributes.click == 'single') {
        // 读取设备当前属性值，如果无该属性，默认为 false
        const attributes = Cloud.getCurrentAttributes().status || false;
        // 根据上一次开关状态来更新本次状态
        report_attributes.status = attributes.status ? false : true;
        // 顺便生成显示在应用上的文字
        report_attributes.status_text = attributes.status ? 'OFF' : 'ON';
    }
    
    return report_attributes;
}

属性上报经过这个预处理函数后，会变为如下：

{
    "click": "single",
    "status": true,
    "status_text": "ON"
}

所以，云平台上该设备最终接收到的，是以上这组属性。

Cloud.getAttributeMetadata(identifier)

读取当前设备指定属性的元信息。

参数

string 类型：属性标识符。

返回值

object 类型，属性元信息键值对集合。
- type：属性类型。
- date_type: 数据类型。
- ts：属性最后上报时间戳（毫秒）。

示例

Cloud.getAttributeMetadata('temperature')
/*
{
    "type": "report",
    "data_type": "number",
    "ts": 1708587480939
}
*/

地理位置函数

Cloud.gpsWGS84toGCJ02(point)

用于将 GPS 原始 WGS84 坐标转化为国内的 GCJ02 坐标，转化后的坐标可以在腾讯地图、高德地图上正确显示位置。

参数

point：MapPoint 类型，参考 MapPoint 数据类型。输入 GPS 原始坐标位置，通常为 GPS 模组直接返回的坐标信息。

返回值

MapPoint 类型，经过转化的坐标位置。

示例

module.exports = function (report_attributes) {
     
    if (
        report_attributes.location != undefined &&
        report_attributes.location.lat != undefined &&
        report_attributes.location.lng != undefined)
    {
        report_attributes.location_gcj02 = Cloud.gpsWGS84toGCJ02(report_attributes.location);
    }
    
    return report_attributes;
}

Cloud.gpsWGS84toBD09

用于将 GPS 原始 WGS84 坐标转化为国内的 BD09 坐标，转化后的坐标可以在百度地图上正确显示位置。

使用方法同上。

Cloud.isPointInCircle

用于判断某个坐标位置是否处于圆形地理区域内部，实现电子围栏的功能。

参数

point：MapPoint 类型，输入当前位置坐标。
circle： MapCircle 类型，圆形地理区域。参考 MapCircle 数据类型。

返回值

Boolean 类型。true 表示是区域内，false 表示不在区域内。

示例

假如我们已经为设备写入电子围栏的属性，如下：

{
    "circle": {
        "centerPoint": {
            "lat": 39.462,
            "lng": 140.391
        },
        "radius": 100
    }
}

然后属性上报预处理函数如下：

module.exports = function (report_attributes) {
     
    if (
        report_attributes.location != undefined &&
        report_attributes.location.lat != undefined &&
        report_attributes.location.lng != undefined)
    {
        // 读取设备当前属性值，拿到电子围栏属性值
        const attributes = Cloud.getCurrentAttributes();
        report_attributes.in_area = Cloud.isPointInCircle(report_attributes.location, attributes.circle);
    }
    
    return report_attributes;
}

当设备上报当前位置后，会立即触发以上规则，电子围栏的判断结果将写入设备的属性 in_area。

每个设备都可以独立设置自己的电子围栏，然后共用所属设备类型的同一个预处理规则。

Cloud.isPointInPolygon

用于判断某个坐标位置是否处于多边形地理区域内部，实现电子围栏的功能。

参数

point：MapPoint 类型，输入当前位置坐标。
polygon： MapPolygon 类型，多边形地理区域。参考 MapPolygon 数据类型。

返回值

Boolean 类型。true 表示是区域内，false 表示不在区域内。

示例

假如我们已经为设备写入电子围栏的属性，如下：

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

然后属性上报预处理函数如下：

module.exports = function (report_attributes) {
     
    if (
        report_attributes.location != undefined &&
        report_attributes.location.lat != undefined &&
        report_attributes.location.lng != undefined)
    {
        // 读取设备当前属性值，拿到电子围栏属性值
        const attributes = Cloud.getCurrentAttributes();
        report_attributes.in_area = Cloud.isPointInPolygon(report_attributes.location, attributes.polygon);
    }
    
    return report_attributes;
}

当设备上报当前位置后，会立即触发以上规则，电子围栏的判断结果将写入设备的属性 in_area。

每个设备都可以独立设置自己的电子围栏，然后共用所属设备类型的同一个预处理规则。

JSON 编解码函数

Cloud.Utils.jsonDecode(string)

将 JSON 字符串转为 JavaScript 对象或数组。

参数

string：有效的 JSON 字符串。

返回值

object 类型：JSON 字符串对应的 JavaScript 对象或数组。

示例

Cloud.Utils.jsonDecode('{"temperature":22.5,"humidity":65.9,"switch":true}');
/* 返回 JavaScript 对象
{
    "temperature": 22.5,
    "humidity": 65.9,
    "switch": true
}
*/

Cloud.Utils.jsonEncode(object)

将 JavaScript 对象或数组转为 JSON 字符串。

参数

object：JavaScript 对象或数组。

返回值

string 类型：JSON 字符串。

示例

Cloud.Utils.jsonEncode({
    "temperature": 22.5,
    "humidity": 65.9,
    "switch": true
});
/* 返回字符串
{"temperature":22.5,"humidity":65.9,"switch":true}
*/

Modbus RTU 函数

Modbus RTU 函数用于构造 Modbus RTU 指令，与 Modbus 从站设备进行通信。

提示

以下 Modbus RTU 函数适用于在消息规则或任务的云函数中，更加灵活高效的控制 Modbus 指令生成，而不需要人工编写晦涩的 Modbus 指令。例如：

在消息规则中根据设备上报消息，自动生成不同的 Modbus 指令。
在定时任务中，根据需要，自动生成查询指定寄存器地址或数量的 Modbus 指令。

若您只需要简单的读取或写入操作，可使用基于配置方式的 Modbus 任务操作。

Cloud.ModbusRTU.setUnitId(id)

设置 Modbus RTU 从站地址。该函数调用之后，生成 Modbus 指令时使用该从站地址。若不调用该函数，默认从站地址为 1。

参数

id：设置 Modbus RTU 从站地址，1~255。

返回值

无

示例

// 设置从站地址为 1
Cloud.ModbusRTU.setUnitId(1);
// 设置从站地址为 10
Cloud.ModbusRTU.setUnitId(10);

Cloud.ModbusRTU.readCoils(addr, len)

或 Cloud.ModbusRTU.fc01(addr, len)

读取线圈状态，对应功能码 0x01。

这些线圈通常用于表示开关量输出或内部继电器的状态。适用于监控设备的运行状态、开关位置等，比如读取继电器状态、电机的启动/停止状态、阀门的开闭状态等。

参数

addr：线圈起始地址。
len：线圈个数。

返回值

string 类型：生成的 Modbus 指令 HEX 字符串格式。

示例

// 从地址 0 开始读取 4 个离散输出点的状态
Cloud.ModbusRTU.readCoils(0, 4) 
// 或者
Cloud.ModbusRTU.fc01(0, 4)

// 以上函数调用均返回：0101000000043DC9

Cloud.ModbusRTU.readDiscreteInputs(addr, len)

或 Cloud.ModbusRTU.fc02(addr, len)

读取输入状态，对应功能码 0x02。

这些输入点通常连接外部的开关、传感器等设备，用于反映外部设备的状态信息，例如读取限位开关的通断、温度传感器的报警信号等。

参数

addr：线圈起始地址。
len：线圈个数。

返回值

string 类型：生成的 Modbus 指令 HEX 字符串格式。

示例

// 从地址 0 开始读取 4 个离散输入点的状态
Cloud.ModbusRTU.readDiscreteInputs(0, 4) 
// 或者
Cloud.ModbusRTU.fc02(0, 4)

// 以上函数调用均返回：01020000000479C9

Cloud.ModbusRTU.readHoldingRegisters(addr, len)

或 Cloud.ModbusRTU.fc03(addr, len)

读取保持寄存器的值，对应功能码 0x03。

保持寄存器可用于存储各种数据，如设备的配置参数、运行数据、测量值等，如变频器的运行频率、电压设定值，或者获取设备上传的实时数据，如温度、压力、流量等测量值。

参数

addr：寄存器起始地址。
len：寄存器个数。

返回值

string 类型：生成的 Modbus 指令 HEX 字符串格式。

示例

// 从地址 0 开始读取 2 个寄存器的值
Cloud.ModbusRTU.readHoldingRegisters(0, 2) 
// 或者
Cloud.ModbusRTU.fc03(0, 2)

// 以上函数调用均返回：010300000002C40B

Cloud.ModbusRTU.readInputRegisters(addr, len)

或 Cloud.ModbusRTU.fc04(addr, len)

读取输入寄存器的值，对应功能码 0x04。

输入寄存器通常用于存储只读的、由设备内部自动更新或外部传感器输入的数据，如设备的实时电流值、电压值、功率值等。

参数

addr：寄存器起始地址。
len：寄存器个数。

返回值

string 类型：生成的 Modbus 指令 HEX 字符串格式。

示例

// 从地址 0 开始读取 2 个寄存器的值
Cloud.ModbusRTU.readInputRegisters(0, 2) 
// 或者
Cloud.ModbusRTU.fc04(0, 2)

// 以上函数调用均返回：01040000000271CB

Cloud.ModbusRTU.writeCoil(addr, value)

或 Cloud.ModbusRTU.fc05(addr, value)

写入单个线圈，对应功能码 0x05。

一般用于对设备进行控制操作，如启动或停止电机、打开或关闭继电器等。

参数

addr：线圈地址。
value：写入开关量值，用 1 或 0 表示。

返回值

string 类型：生成的 Modbus 指令 HEX 字符串格式。

示例

// 将地址 0 的线圈设置为 1
Cloud.ModbusRTU.writeCoil(0, 1) 
// 或者
Cloud.ModbusRTU.fc05(0, 1)

// 以上函数调用均返回：0105000000190C

Cloud.ModbusRTU.writeRegister(addr, value)

或 Cloud.ModbusRTU.fc06(addr, value)

写入单个寄存器，对应功能码 0x06。

常用于修改设备的配置参数或设置设备的运行值，如设置变频器的目标频率、修改 PLC 的定时器设定值等。

参数

addr：线圈地址。
value：写入数值。

返回值

string 类型：生成的 Modbus 指令 HEX 字符串格式。

示例

// 将地址 0 的保持寄存器设置为 100
Cloud.ModbusRTU.writeRegister(0, 100) 
// 或者
Cloud.ModbusRTU.fc06(0, 100)

// 以上函数调用均返回：0106000000648821

Cloud.ModbusRTU.writeCoils(addr, values)

或 Cloud.ModbusRTU.fc15(addr, value)

写入多个线圈，对应功能码 0x0F。

参数

addr：线圈起始地址。
values：数组类型，包含写入的多个开关量值，每个开关量值用 1 或 0 表示。

返回值

string 类型：生成的 Modbus 指令 HEX 字符串格式。

示例

// 从地址 0 开始写入 4 个线圈的状态，分别为 1、1、0、1 
Cloud.ModbusRTU.writeCoils(0, [1, 1, 0, 1])
// 或者
Cloud.ModbusRTU.fc15(0, [1, 1, 0, 1])

// 以上函数调用均返回：010F00000004010B7F51

Cloud.ModbusRTU.writeRegisters(addr, values)

或 Cloud.ModbusRTU.fc16(addr, values)

写入多个保持寄存器，对应功能码 0x10。

参数

addr：线圈地址。
values：数组类型，包含写入的多个数值。

返回值

string 类型：生成的 Modbus 指令 HEX 字符串格式。

示例

//  从地址 0 开始写入 4 个保持寄存器的值，分别为 100、200、300、400
Cloud.ModbusRTU.writeRegisters(0, [100, 200, 300, 400]) 
// 或者
Cloud.ModbusRTU.fc16(0, [100, 200, 300, 400]) 

// 以上函数调用均返回：01100000000408006400C8012C0190B3A5

数据类型转换函数

Cloud.Utils.enableAutoIntToUInt(enable)

在整数转 HEX 的一系列函数中，是否允许当输入数值超出带符号整数范围时，自动转为无符号整数。

例如：使用 Cloud.Utils.int8ToHex(number) 可将带符号8位整数（范围是 -128~127）转为 HEX 字符串。假如输入数值为 128，如果开启了自动转换，该函数不会异常，会自动转为调用 Cloud.Utils.uint8ToHex(number)，将输入数值作为无符号8位整数（范围是 0～255），返回 HEX 字符串 80。

可见，如果您不能确定输入数值是带符号还是无符号类型，通过该自动转换的特性，可以有效避免由于云函数输入范围错误导致异常中断，影响设备的正常通信。

该特性默认为允许，如需禁用该特性，请调用该函数。

参数

enable：布尔类型，true 为允许，false 为禁用。

示例

Cloud.Utils.enableAutoIntToUInt(false)  // 禁用自动转换

Cloud.Utils.int8ToHex(number)

将 8 位带符号整数转为十六进制的 HEX 字符串。

参数

number：带符号 8 位整数，范围从 -127～128。

返回值

string 类型：1 个字节的 HEX 字符串。

示例

Cloud.Utils.int8ToHex(0)        // 00
Cloud.Utils.int8ToHex(127)      // 7F
Cloud.Utils.int8ToHex(-128)     // 80
Cloud.Utils.int8ToHex(-1)       // FF

Cloud.Utils.uint8ToHex(number)

将 8 位无符号整数转为十六进制的 HEX 字符串。

参数

number：无符号 8 位整数，范围从 0～255。

返回值

string 类型：1 个字节的 HEX 字符串。

示例

Cloud.Utils.uint8ToHex(0)       // 00
Cloud.Utils.uint8ToHex(127)     // 7F
Cloud.Utils.uint8ToHex(128)     // 80
Cloud.Utils.uint8ToHex(255)     // FF

知识分享

什么是带符号和无符号？

带符号和无符号的 8 位整数转换成十六进制时之所以不一样，关键在于它们表示数值的方式不同：

无符号的 8 位整数：范围是 0 到 255，使用所有 8 位直接表示数值大小。例如，255（最大值）在二进制中为 11111111，十六进制表示为 FF。
带符号的 8 位整数：范围是 -128 到 127，最高位用作符号位（0 表示正数，1 表示负数），剩余 7 位表示数值大小。例如，-128（最小负值）在二进制中为 10000000，十六进制表示为 80。

这种差异源于带符号整数使用一位来表示正负，而无符号整数则利用所有位来增加表示范围。因此，相同的二进制序列在这两种整数类型中可能代表不同的数值。

对于 16 位和 32 位整数的带符号和无符号，也是同理。

Cloud.Utils.int16ToHex(number)

将 16 位带符号整数转为十六进制的 HEX 字符串，使用大端字节序。

参数

number：带符号 16 位整数，范围从 -32767～32768。

返回值

string 类型：2 个字节的 HEX 字符串。

示例

Cloud.Utils.int16ToHex(-32768)      // 8000
Cloud.Utils.int16ToHex(-1)          // FFFF
Cloud.Utils.int16ToHex(0)           // 0000
Cloud.Utils.int16ToHex(1)           // 0001
Cloud.Utils.int16ToHex(32767)       // 7FFF

Cloud.Utils.int16ToHexLE(number)

将 16 位带符号整数转为十六进制的 HEX 字符串，使用小端字节序。

参数

number：带符号 16 位整数，范围从 -32767～32768。

返回值

string 类型：2 个字节的 HEX 字符串。

示例

Cloud.Utils.int16ToHexLE(-32768)      // 0080
Cloud.Utils.int16ToHexLE(-1)          // FFFF
Cloud.Utils.int16ToHexLE(0)           // 0000
Cloud.Utils.int16ToHexLE(1)           // 0100
Cloud.Utils.int16ToHexLE(32767)       // FF7F

知识分享

什么是大端字节序和小端字节序？

大端字节序（Big Endian）和小端字节序（Little Endian）是两种不同的数据表示方法，主要区别在于多字节数据中字节的排列顺序：

大端字节序（Big Endian）：高位字节排在内存的低地址端，低位字节排在高地址端。例如，16位整数 0x1234 在内存中会以 12 34 的顺序存储，12 是高位字节，存储在低地址。
小端字节序（Little Endian）：低位字节排在内存的低地址端，高位字节排在高地址端。同样的16位整数 0x1234 在内存中会以 34 12 的顺序存储，34 是低位字节，存储在低地址。

这种差异影响数据的读写方式，尤其是在跨平台数据交换时。选择使用哪种字节序取决于处理器架构和数据交换的需求。

Cloud.Utils.uint16ToHex(number)

将 16 位无符号整数转为十六进制的 HEX 字符串，使用大端字节序。

参数

number：无符号 16 位整数，范围从 0～65535。

返回值

string 类型：2 个字节的 HEX 字符串。

示例

Cloud.Utils.uint16ToHex(0)          // 0000
Cloud.Utils.uint16ToHex(1)          // 0001
Cloud.Utils.uint16ToHex(32767)      // 7FFF
Cloud.Utils.uint16ToHex(65535)      // FFFF

Cloud.Utils.uint16ToHexLE(number)

将 16 位无符号整数转为十六进制的 HEX 字符串，使用小端字节序。

参数

number：无符号 16 位整数，范围从 0～65535。

返回值

string 类型：2 个字节的 HEX 字符串。

示例

Cloud.Utils.uint16ToHex(0)          // 0000
Cloud.Utils.uint16ToHex(1)          // 0100
Cloud.Utils.uint16ToHex(32767)      // FF7F
Cloud.Utils.uint16ToHex(65535)      // FFFF

Cloud.Utils.int32ToHex(number)

将 32 位带符号整数转为十六进制的 HEX 字符串，使用大端字节序。

参数

number：带符号 32 位整数，范围从 -2147483648～2147483647。

返回值

string 类型：4 个字节的 HEX 字符串。

示例

Cloud.Utils.int32ToHex(0)           // 00000000
Cloud.Utils.int32ToHex(1)           // 00000001
Cloud.Utils.int32ToHex(2147483647)  // 7FFFFFFF
Cloud.Utils.int32ToHex(-2147483648) // 80000000
Cloud.Utils.int32ToHex(-1)          // FFFFFFFF

Cloud.Utils.int32ToHexLE(number)

将 32 位带符号整数转为十六进制的 HEX 字符串，使用小端字节序。

参数

number：带符号 32 位整数，范围从 -2147483648～2147483647。

返回值

string 类型：4 个字节的 HEX 字符串。

示例

Cloud.Utils.int32ToHex(0)           // 00000000
Cloud.Utils.int32ToHex(1)           // 01000000
Cloud.Utils.int32ToHex(2147483647)  // FFFFFF7F
Cloud.Utils.int32ToHex(-2147483648) // 00000080
Cloud.Utils.int32ToHex(-1)          // FFFFFFFF

Cloud.Utils.uint32ToHex(number)

将 32 位无符号整数转为十六进制的 HEX 字符串，使用大端字节序。

参数

number：无符号 32 位整数，范围从 0～4294967295。

返回值

string 类型：4 个字节的 HEX 字符串。

示例

Cloud.Utils.uint32ToHex(0)          // 00000000
Cloud.Utils.uint32ToHex(1)          // 00000001
Cloud.Utils.uint32ToHex(2147483647) // 7FFFFFFF
Cloud.Utils.uint32ToHex(2147483648) // 80000000
Cloud.Utils.uint32ToHex(4294967295) // FFFFFFFF

Cloud.Utils.uint32ToHexLE(number)

将 32 位无符号整数转为十六进制的 HEX 字符串，使用小端字节序。

参数

number：无符号 32 位整数，范围从 0～4294967295。

返回值

string 类型：4 个字节的 HEX 字符串。

示例

Cloud.Utils.uint32ToHexLE(0)          // 00000000
Cloud.Utils.uint32ToHexLE(1)          // 01000000
Cloud.Utils.uint32ToHexLE(2147483647) // FFFFFF7F
Cloud.Utils.uint32ToHexLE(2147483648) // 00000080
Cloud.Utils.uint32ToHexLE(4294967295) // FFFFFFFF

Cloud.Utils.float32ToHex(number)

将 32 位 Float 单精度浮点数转为十六进制的 HEX 字符串，使用大端字节序。

参数

number：单精度浮点数。

返回值

string 类型：4 个字节的 HEX 字符串。

示例

Cloud.Utils.float32ToHex(0)             // 00000000
Cloud.Utils.float32ToHex(100.123)       // 42C83EFA
Cloud.Utils.float32ToHex(-100.123)      // C2C83EFA
Cloud.Utils.float32ToHex(5000.123)      // 459C40FC
Cloud.Utils.float32ToHex(-5000.123)     // C59C40FC

知识分享

为什么浮点数转十六进制时，不区分带符号和无符号？

在处理浮点数（如 IEEE 754 标准中定义的 32 位和 64 位浮点数）时，不像整数那样直接区分带符号和不带符号。浮点数的表示包括三个部分：符号（sign）、指数（exponent）、和尾数（mantissa 或 fraction）。这种表示方式允许浮点数同时表示正数、负数以及 0。

符号位：单独的一位用来表示数值的正负，0 代表正数，1 代表负数。
指数位：一组位表示指数（但也有其特殊的编码规则，如偏移量或偏置）。
尾数位：剩余的位用来表示数值的精确度（或者说是数值的有效数字）。

因此，当你将一个浮点数转换成十六进制表示时，这个转换包含了数值的全貌——包括它的符号、大小和精度。不需要像处理整数那样分开考虑带符号和不带符号，因为浮点数的表示方法本身就内嵌了符号信息。

例如，对于 32 位浮点数（即 float），IEEE 754 标准规定了1位符号位、8位指数位和23位尾数位的结构。这种结构使得浮点数可以表示很宽的范围，包括非常小和非常大的数值，同时包含了符号信息。因此，当你将浮点数转换为十六进制字符串时，这个字符串反映了浮点数的完整信息，包括其正负符号。

Cloud.Utils.float32ToHexLE(number)

将 32 位 Float 单精度浮点数转为十六进制的 HEX 字符串，使用小端字节序。

参数

number：单精度浮点数。

返回值

string 类型：4 个字节的 HEX 字符串。

示例

Cloud.Utils.float32ToHex(0)             // 00000000
Cloud.Utils.float32ToHex(100.123)       // FA3EC842
Cloud.Utils.float32ToHex(-100.123)      // FA3EC8C2
Cloud.Utils.float32ToHex(5000.123)      // FC409C45
Cloud.Utils.float32ToHex(-5000.123)     // FC409CC5

Cloud.Utils.double64ToHex(number)

将 64 位 Double 双精度浮点数转为十六进制的 HEX 字符串，使用大端字节序。

参数

number：双精度浮点数。

返回值

string 类型：8 个字节的 HEX 字符串。

示例

Cloud.Utils.double64ToHex(0)            // 0000000000000000
Cloud.Utils.double64ToHex(10000.123)    // 40C3880FBE76C8B4
Cloud.Utils.double64ToHex(-10000.123)   // C0C3880FBE76C8B4
Cloud.Utils.double64ToHex(500000.123)   // 411E84807DF3B646
Cloud.Utils.double64ToHex(-500000.123)  // C11E84807DF3B646

Cloud.Utils.double64ToHexLE(number)

将 64 位 Double 双精度浮点数转为十六进制的 HEX 字符串，使用小端字节序。

参数

number：双精度浮点数。

返回值

string 类型：8 个字节的 HEX 字符串。

示例

Cloud.Utils.double64ToHexLE(0)            // 0000000000000000
Cloud.Utils.double64ToHexLE(10000.123)    // B4C876BE0F88C340
Cloud.Utils.double64ToHexLE(-10000.123)   // B4C876BE0F88C3C0
Cloud.Utils.double64ToHexLE(500000.123)   // 46B6F37D80841E41
Cloud.Utils.double64ToHexLE(-500000.123)  // 46B6F37D80841EC1

Cloud.Utils.bitsToByte(bits)

将一个字节的二进制序列，转为无符号整数。

参数

bits：包含8个二进制位数值的数组，例如：[0,1,0,0,1,0,0,0]。

返回值

number 类型：无符号整数。

示例

Cloud.Utils.bitsToByte([0,0,0,0,0,0,0,1])   // 1
Cloud.Utils.bitsToByte([0,0,0,0,0,0,1,1])   // 3
Cloud.Utils.bitsToByte([0,0,0,0,1,1,1,1])   // 15

Cloud.Utils.bitsToByteHex(bits)

将一个字节的二进制序列，转为十六进制 HEX 字符串。

参数

bits：包含8个二进制位数值的数组，例如：[0,1,0,0,1,0,0,0]。

返回值

string 类型：十六进制 HEX 字符串。

示例

Cloud.Utils.bitsToByteHex([0,0,0,0,0,0,0,1])   // 01
Cloud.Utils.bitsToByteHex([0,0,0,0,0,0,1,1])   // 03
Cloud.Utils.bitsToByteHex([0,0,0,0,1,1,1,1])   // 0F

Cloud.Utils.byteToBits(byte)

将8位无符号整数，转为一个字节的二进制序列。

参数

byte：无符号整数，范围是 0～255。

返回值

bits 类型：包含8个二进制位数值的数组，例如：[0,1,0,0,1,0,0,0]。

示例

Cloud.Utils.byteToBits(1)   // [0,0,0,0,0,0,0,1]
Cloud.Utils.byteToBits(3)   // [0,0,0,0,0,0,1,1]
Cloud.Utils.byteToBits(15)  // [0,0,0,0,1,1,1,1]

Cloud.Utils.strToBuffer(data)

将字符串转为 Buffer 字节序列。

参数

data：string 字符串类型。

返回值

Buffer 字节流类型。

示例

Cloud.Utils.strToBuffer("APIO=42")  // [65,80,73,79,61,52,50]

Cloud.Utils.strToHex(data)

将字符串转为 HEX 字符串，中文部分使用 UTF-8 字符编码。

参数

data：string 字符串类型。

返回值

string 类型，表示十六进制 HEX。

示例

Cloud.Utils.strToHex("APIO=42")  // 4150494F3D3432

Cloud.Utils.strToBase64(data)

将字符串转为 base64 编码的字符串。

参数

data：string 字符串类型。

返回值

string 类型，表示 base64 编码的字符串。

示例

Cloud.Utils.strToBase64("temperature=23.1,humitidy=56.2")
// dGVtcGVyYXR1cmU9MjMuMSxodW1pdGlkeT01Ni4y

Cloud.Utils.hexToBuffer(data)

将十六进制 HEX 字符串转为 Buffer 字节序列。

参数

data：有效的 HEX 字符串。

返回值

Buffer 字节流类型。

示例

Cloud.Utils.hexToBuffer("4150494F3D3432")   // Buffer 字节流 [65,80,73,79,61,52,50]

Cloud.Utils.hexToStr(data)

将十六进制 HEX 转为字符串。

参数

data：string 类型，有效的 HEX 字符串。

返回值

string 类型。

示例

Cloud.Utils.hexToStr("6162636431323334")   // abcd1234

Cloud.Utils.hexToBase64(data)

将 HEX 字符串转为 Base64 字符串。

参数

data：有效的十六进制 HEX 字符串。

返回值

string 类型：Base64 字符串。

示例

Cloud.Utils.hexToBase64("4150494F3D3432")   // QVBJTz00Mg==

Cloud.Utils.bufferToHex(data)

将 Buffer 字节序列转为十六进制 HEX 字符串。

参数

data：Buffer 字节流类型。

返回值

string 类型：表示十六进制 HEX。

示例

// data 为 Buffer 字节流，来自设备的自定义数据流上报
Cloud.Utils.bufferToHex(data)   // 4150494F3D3432

Cloud.Utils.bufferToStr(data)

将 Buffer 字节序列转为字符串。

参数

data：Buffer 字节流类型。

返回值

string 类型。

示例

// data 为 Buffer 字节流，来自设备的自定义数据流上报
Cloud.Utils.bufferToStr(data)   // ##GPS=34.12,148.23##

Cloud.Utils.bufferToBase64(data)

将 Buffer 字节流类型转为 Base64 字符串。

参数

data：有效的 Base64 字符串。

返回值

string 类型：Base64 字符串。

示例

// data 二进制数据流，在 HEX 类型的自定义数据流上报
Cloud.Utils.bufferToBase64(data)     // QVBJTz00Mg==

Cloud.Utils.base64ToBuffer(data)

将 Base64 字符串转为 Buffer 字节序列。

参数

data：有效的 Base64 字符串。

返回值

Buffer 字节流类型。

示例

Cloud.Utils.base64ToBuffer("QVBJTz00Mg==")   // Buffer 字节流 [65,80,73,79,61,52,50]

Cloud.Utils.base64ToHex(data)

将 Base64 字符串转为 HEX 十六进制字符串。

参数

data：有效的 Base64 字符串。

返回值

string 类型：HEX 字符串。

示例

Cloud.Utils.base64ToHex("QVBJTz00Mg==")     // 4150494f3d3432

Cloud.Utils.base64ToStr(data)

将 Base64 字符串解码为字符串。

参数

data：有效的 Base64 字符串。

返回值

string 类型。

示例

Cloud.Utils.base64ToHex("dGVtcGVyYXR1cmU9MjMuMSxodW1pdGlkeT01Ni4y")     
// temperature=23.1,humitidy=56.2

Cloud.Utils.isNumeric(data)

判断给定的输入是否表示一个数值。

参数

data：number 或 string 类型。

返回值

boolean 类型。

示例

Cloud.Utils.isNumeric(10)   // true
Cloud.Utils.isNumeric(23.5)   // true
Cloud.Utils.isNumeric("23.5")   // true
Cloud.Utils.isNumeric(true)   // false
Cloud.Utils.isNumeric("temperature")   // false

国际字符转换函数

Cloud.Utils.strToGB2312Hex(data)

将字符串转为 HEX 字符串，中文部分使用 GB2312 字符编码。

参数

data：任何字符串类型。

返回值

string 类型：表示十六进制 HEX。

示例

Cloud.Utils.strToHex("你好")        // E4BDA0E5A5BD
Cloud.Utils.strToGB2312Hex("你好")  // C4E3BAC3

Cloud.Utils.strToGBKHex(data)

将字符串转为 HEX 字符串，中文部分使用 GB2312 字符编码。

参数

data：string 字符串类型。

返回值

string 类型，表示十六进制 HEX。

示例

Cloud.Utils.strToHex("你好")        // E4BDA0E5A5BD
Cloud.Utils.strToGBKHex("你好")     // C4E3BAC3

Cloud.Utils.decodeGB2312(data)

将 Buffer 字节流转为字符串，中文部分使用 GB2312 字符编码进行解码。

参数

data：Buffer 字节流类型。

返回值

string 类型。

示例

// data 为 Buffer 字节流，来自设备的自定义数据流（必须使用 HEX 格式）上报。
Cloud.Utils.decodeGB2312(data)     // abc-123-设备已启动

Cloud.Utils.decodeGBK(data)

将 Buffer 字节流转为字符串，中文部分使用 GBK 字符编码进行解码。

参数

data：Buffer 字节流类型。

返回值

string 类型。

示例

// data 为 Buffer 字节流，来自设备的自定义数据流（必须使用 HEX 格式）上报。
Cloud.Utils.decodeGBK(data)     // abc-123-设备已启动

Buffer 函数

在 ThingsCloud 自定义数据上报规则 - 属性解析函数中，设备上报的自定义数据（可能是二进制、JSON、HEX）作为 Buffer 类型的参数 data 传入云函数，您可以对其进行解析和处理。

提示

Buffer 类型用于表示固定长度的字节序列，是 JavaScript Uint8Array 类的子类。

下边列出一些常用的 Buffer 类型函数，通常用于设备采用自定义二进制协议时的数据解析。

为了便于您浏览示例，这里我们假设，某设备通过平台的自定义数据流，上报了二进制报文，内容以 HEX 形式体现如下：

01 04 06 02 81 00 DB 00 00 2D 54

也许您已经看出来了，这是一个温湿度+光照传感器的 Modbus 回复报文，我们就以它为例。

这时，在自定义数据上报规则的属性解析函数中，以上二进制报文以 Buffer 类型的参数 data 传入云函数，在下边的函数示例中，我们会以 data 为例进行一些演示。

data.readInt8([offset])

从 data 指定的 offset 中读取有符号的 8 位整数。

offset 表示在开始读取之前要跳过的字节数，必须满足 0 <= offset <= data.length - 1 ，默认值：0。以下函数中 offset 含义相同。

示例

data.readInt8(0)    // 1
data.readInt8(3)    // 2
data.readInt8(4)    // -127

data.readUInt8([offset])

从 data 指定的 offset 中读取无符号的 8 位整数。

示例

data.readInt8(0)    // 1
data.readInt8(3)    // 2
data.readUInt8(4)   // 129

data.readInt16BE([offset])

从 data 指定的 offset 中读取有符号的大端字节序 16 位整数。

示例

data.readInt16BE(3)     // 641
data.readInt16BE(5)     // 219

data.readInt16LE([offset])

从 data 指定的 offset 中读取有符号的小端字节序 16 位整数。

示例

data.readInt16BE(3)     // -32510
data.readInt16BE(5)     // -9472

data.readUInt16BE([offset])

从 data 指定的 offset 中读取无符号的大端字节序 16 位整数。

示例

data.readUInt16BE(3)     // 641
data.readUInt16BE(5)     // 219

data.readUInt16LE([offset])

从 data 指定的 offset 中读取无符号的小端字节序 16 位整数。

示例

data.readUInt16LE(3)    // 33026
data.readUInt16LE(5)    // 56064

data.readInt32BE([offset])

从 data 指定的 offset 中读取有符号的大端字节序 32 位整数。

示例

data.readInt32BE(3)     // 42008795

data.readInt32LE([offset])

从 data 指定的 offset 中读取有符号的小端字节序 32 位整数。

示例

data.readInt32LE(3)     // -620723966

data.readUInt32BE([offset])

从 data 指定的 offset 中读取无符号的大端字节序 32 位整数。

示例

data.readUInt32BE(3)    // 42008795

data.readUInt32LE([offset])

从 data 指定的 offset 中读取无符号的小端字节序 32 位整数。

示例

data.readUInt32LE(3)    // 3674243330

data.readFloatBE([offset])

从 data 指定的 offset 中读取大端字节序 32 位单精度浮点数。

示例

data.readFloatBE(3)     // 1.8955337421991285e-37

data.readFloatLE([offset])

从 data 指定的 offset 中读取小端字节序 32 位单精度浮点数。

示例

data.readFloatLE(3)     // -36170642608881660

日期时间函数

Cloud.Utils.setTimezone(timezone)

设置日期时间函数的默认时区。

参数

timezone：指定时区，不填则使用默认时区。常用时区参考

提示

所有日期时间函数的默认时区是 Asia/Shanghai，以下所有函数示例均使用默认时区。

示例

Cloud.Utils.setTimezone("America/New_York")

Cloud.Utils.unixTimestamp(date)

获取 Unix 时间戳，单位是秒。

提示

Unix 时间戳（Unix Timestamp），也称为 POSIX 时间或 Epoch 时间，是一个广泛使用的时间表示方法，它表示从 1970 年 1 月 1 日 00:00:00 UTC（协调世界时）到当前时间点之间的总秒数（不考虑闰秒）。Unix 时间戳是一个整数值，不仅用于 Unix 系统和类 Unix 系统，而且在各种编程语言和应用中都被广泛采用。

参数

date：指定时间，格式参考日期时间输入格式，不填或 "" 表示当前时间。

示例

Cloud.Utils.unixTimestamp()     // 当前时间戳（秒），例如：1703121965
Cloud.Utils.unixTimestamp("2023-01-01")     // 1672502400
Cloud.Utils.unixTimestamp("2023-01-01 12:00")   // 1672545600
Cloud.Utils.unixTimestamp("2023-01-01 12:00:00")     // 1672545600

Cloud.Utils.unixTimestampMills(date)

获取 Unix 时间戳，单位是毫秒。

参数

date：指定时间，格式参考日期时间输入格式，不填或 "" 表示当前时间。

示例

Cloud.Utils.unixTimestampMills()     // 当前时间戳（毫秒），例如：1703121965000
Cloud.Utils.unixTimestampMills("2023-01-01")     // 1672502400000
Cloud.Utils.unixTimestampMills("2023-01-01 12:00")   // 1672545600000
Cloud.Utils.unixTimestampMills("2023-01-01 12:00:00")     // 1672545600000

Cloud.Utils.dateFormat(format, date)

按指定格式输出日期时间。

参数

format：格式符号，请参考日期时间输出格式。
date：指定时间，格式参考日期时间输入格式，不填或 "" 表示当前时间。

示例

Cloud.Utils.dateFormat("YYYY-MM-DD")   // 当前日期：例如：2023-12-21
Cloud.Utils.dateFormat("YYYY-MM-DD HH:mm:ss")   // 当前时间，例如：2023-12-21 09:26:05
Cloud.Utils.dateFormat("YYYY-MM-DD HH:mm:ss", 1672545600000)   // 2023-01-01 12:00:00

Cloud.Utils.dateToObject(date)

获得指定时间的 Object 对象

参数

date：指定时间，格式参考日期时间输入格式，不填或 "" 表示当前时间。

示例

Cloud.Utils.dateToObject("2023-01-01 12:00:00")
/* {
    "years": 2023,
    "months": 0,
    "date": 1,
    "hours": 12,
    "minutes": 0,
    "seconds": 0,
    "milliseconds": 0
} */

Cloud.Utils.dateAdd(date, amount, unit, format)

为指定时间增加特定的时间。

参数

date：指定时间，格式参考日期时间输入格式，不填或 "" 表示当前时间。
amount：数量。
unit：时间单位。
format：格式符号，请参考日期时间输出格式。

unit 取值如下：

单位	简写	说明
`year`	`y`	年
`month`	`M`	月
`week`	`w`	周
`day`	`d`	日
`hour`	`h`	小时
`minute`	`m`	分钟
`second`	`s`	秒
`millisecond`	`ms`	毫秒

示例

Cloud.Utils.dateAdd("2023-01-01 12:00:00", 2, "day", "YYYY-MM-DD HH:mm:ss")    // 2023-01-03 12:00:00
Cloud.Utils.dateAdd(1672545600000, 2, "day", "YYYY-MM-DD HH:mm:ss")    // 2023-01-03 12:00:00
Cloud.Utils.dateAdd("2023-01-01 12:00:00", 3, "month", "YYYY-MM-DD")   // 2023-04-01

Cloud.Utils.dateSubtract(date, amount, unit, format)

为指定时间减少特定的时间。

参数

date：指定时间，格式参考日期时间输入格式，不填或 "" 表示当前时间。
amount：数量。
unit：时间单位。
format：格式符号，请参考日期时间输出格式。

unit 取值同 Cloud.Utils.dateAdd。

示例

Cloud.Utils.dateSubtract("2023-01-01 12:00:00", 2, "day", "YYYY-MM-DD HH:mm:ss")    // 2022-12-30 12:00:00
Cloud.Utils.dateSubtract(1672545600000, 2, "day", "YYYY-MM-DD HH:mm:ss")    // 2022-12-30 12:00:00
Cloud.Utils.dateSubtract("2023-01-01 12:00:00", 3, "month", "YYYY-MM-DD")   // 2022-10-01

Cloud.Utils.dateStartOf(unit, format)

获得指定时间单位的开始时间。

参数

unit：时间单位。
format：格式符号，请参考日期时间输出格式。

unit 取值如下：

单位	简写	文字说明
`year`	`y`	当前年份的开始（1月1日 00:00:00）
`month`	`M`	当前月份的开始（该月的第一天 00:00:00）
`week`	`w`	当前周的开始（周一 00:00:00）
`day`	`d`	当前日的开始（00:00:00）
`hour`	`h`	当前小时的开始（分钟和秒均为 00）
`minute`	`m`	当前分钟的开始（秒为 00）
`second`	`s`	当前秒的开始（毫秒为 000）

示例

Cloud.Utils.dateStartOf("month", "YYYY-MM-DD HH:mm:ss")     // 2023-01-01 00:00:00
Cloud.Utils.dateStartOf("day", "YYYY-MM-DD")   // 2023-01-10

Cloud.Utils.dateEndOf(unit, format)

获得指定时间单位的结束时间。

参数

unit：时间单位。
format：格式符号，请参考日期时间输出格式。

unit 取值同 Cloud.Utils.dateStartOf。

示例

Cloud.Utils.dateEndOf("month", "YYYY-MM-DD HH:mm:ss")     // 2023-01-31 23:59:59
Cloud.Utils.dateEndOf("day", "YYYY-MM-DD")   // 2023-01-10

Cloud.Utils.daysInMonth(date)

获得指定时间所在月份的天数。

参数

date：指定时间，格式参考日期时间输入格式，不填或 "" 表示当前时间。

示例

Cloud.Utils.daysInMonth(1706716800000)     // 29
Cloud.Utils.daysInMonth("2024-02-01 00:00:00")  // 29

Cloud.Utils.dayOfWeek(date)

获得指定时间对应的星期几，返回一个表示星期几的整数，取值如下：

0：周日
1：周一
2：周二
3：周三
4：周四
5：周五
6：周六

参数

date：指定时间，格式参考日期时间输入格式，不填或 "" 表示当前时间。

示例

Cloud.Utils.dayOfWeek(1706716800000)     // 4
Cloud.Utils.dayOfWeek("2024-02-02")  // 5

Cloud.Utils.dateDiff(date1, date2, unit, decimal)

计算两个指定时间的距离，使用特定的时间单位表示。

参数

date1：指定时间1，格式参考日期时间输入格式。
date2：指定时间2，格式参考日期时间输入格式。
unit：时间单位。
decimal：结果是否支持小数，不填表示取整。

unit 取值如下：

单位	简写	说明
`year`	`y`	年
`month`	`M`	月
`quarter`	`Q`	季度
`week`	`w`	周
`day`	`d`	日
`hour`	`h`	小时
`minute`	`m`	分钟
`second`	`s`	秒
`millisecond`	`ms`	毫秒

示例

Cloud.Utils.dateDiff("2021-02-01 12:00:00", "2024-02-08 12:00:00", "month")    // 36
Cloud.Utils.dateDiff("2021-02-01 12:00:00", "2024-02-08 12:00:00", "month", true)  // 36.225806451612904

Cloud.Utils.isDateSame(date1, date2, unit)

判断在特定时间单位下，date1 是否等同于 date2。

参数

date1：指定时间1，格式参考日期时间输入格式。
date2：指定时间2，格式参考日期时间输入格式。
unit：时间单位。

unit 取值如下：

单位	简写	说明
`year`	`y`	年
`month`	`M`	月
`week`	`w`	周
`day`	`d`	日
`hour`	`h`	小时
`minute`	`m`	分钟
`second`	`s`	秒

示例

Cloud.Utils.isDateSame("2023-01-01 00:00:00", "2023-01-01 12:00:00", "day")     // true
Cloud.Utils.isDateSame(1672545600000, 1672632000000, "day")     // true

Cloud.Utils.isDateBefore(date1, date2, unit)

判断在特定时间单位下，date1 是否早于 date2。

参数

date1：指定时间1，格式参考日期时间输入格式。
date2：指定时间2，格式参考日期时间输入格式。
unit：时间单位。

unit 取值同 Cloud.Utils.isDateSame。

示例

Cloud.Utils.isDateBefore("2023-01-01 00:00:00", "2023-01-02 12:00:00", "day")   // true
Cloud.Utils.isDateBefore(1672545600000, 1672632000000, "day")   // true

Cloud.Utils.isDateSameOrBefore(date1, date2, unit)

判断在特定时间单位下，date1 是否等同或早于 date2。

参数

date1：指定时间1，格式参考日期时间输入格式。
date2：指定时间2，格式参考日期时间输入格式。
unit：时间单位。

unit 取值同 Cloud.Utils.isDateSame。

示例

Cloud.Utils.isDateSameOrBefore("2023-01-01 00:00:00", "2023-01-02 12:00:00", "day")   // true
Cloud.Utils.isDateSameOrBefore(1672545600000, 1672632000000, "day")   // true

Cloud.Utils.isDateAfter(date1, date2, unit)

判断在特定时间单位下，date1 是否晚于 date2。

参数

date1：指定时间1，格式参考日期时间输入格式。
date2：指定时间2，格式参考日期时间输入格式。
unit：时间单位。

unit 取值同 Cloud.Utils.isDateSame。

示例

Cloud.Utils.isDateAfter("2023-01-01 00:00:00", "2023-01-02 12:00:00", "day")   // false
Cloud.Utils.isDateAfter(1672545600000, 1672632000000, "day")   // false

Cloud.Utils.isDateSameOrAfter(date1, date2, unit)

判断在特定时间单位下，date1 是否等同或晚于 date2。

参数

date1：指定时间1，格式参考日期时间输入格式。
date2：指定时间2，格式参考日期时间输入格式。
unit：时间单位。

unit 取值同 Cloud.Utils.isDateSame。

示例

Cloud.Utils.isDateSameOrAfter("2023-01-01 00:00:00", "2023-01-02 12:00:00", "day")   // false
Cloud.Utils.isDateSameOrAfter(1672545600000, 1672632000000, "day")   // false

Cloud.Utils.isDateBetween(date, date_start, date_end, unit)

判断在特定时间单位下，date 是否在 date1 和 date2 之间。

参数

date：指定时间，格式参考日期时间输入格式。
date1：指定时间1，格式参考日期时间输入格式。
date2：指定时间2，格式参考日期时间输入格式。
unit：时间单位。

unit 取值同 Cloud.Utils.isDateSame。

示例

isDateBetween("2023-01-01 12:00:00", "2023-01-01 00:00:00", "2023-01-02 12:00:00")  // true
Cloud.Utils.isDateBetween("2023-01-01 12:00:00", "2023-01-01 00:00:00", "2023-01-02 12:00:00", "day")   // false
Cloud.Utils.isDateBetween(1672545600000, 1672502400000, 1672632000000, "day")   // false

日期时间输入格式

符合 ISO 8601open in new window 规范的日期时间字符串，例如：
- 2023-01-01
- 2023-01-01 08:00
- 2023-01-01 08:00:00
- 2023-01-01T00:00:00.000Z
- 2023-01-01T08:00:00.000+08:00
UNIX 时间戳（毫秒），例如：
- 1612108800000
- 1688184000000

日期时间输出格式

格式符号	输出示例	说明
`YYYY`	2024	4位数年份
`YY`	24	2位数年份
`MMMM`	January	月份的完整名称
`MMM`	Jan	月份的缩写
`MM`	01	2位数月份
`M`	1	月份
`D`	2	日
`DD`	02	2位数的日
`d`	0-6	星期中的第几天，星期天为0
`H`	14	24小时制的小时数
`HH`	14	24小时制的2位小时数
`h`	2	12小时制的小时数
`hh`	02	12小时制的2位小时数
`m`	5	分钟
`mm`	05	2位数分钟
`s`	9	秒
`ss`	09	2位数秒
`SSS`	9	秒
`A`	PM	大写的AM或PM
`a`	pm	小写的am或pm
`Z`	+05:30	表示时区的偏移
`ZZ`	+0530	表示时区的偏移，无冒号分隔

常用时区参考

全球的时区覆盖了从 UTC-12:00 到 UTC+14:00 的范围，每个时区都有其特定的地理位置或国家使用。以下是一些典型的时区及其包含的地点示例：

美洲 (North America)
- America/New_York (东部时区, UTC-5)
- America/Chicago (中部时区, UTC-6)
- America/Denver (山地时区, UTC-7)
- America/Los_Angeles (太平洋时区, UTC-8)
- America/Anchorage (阿拉斯加时区, UTC-9)
- Pacific/Honolulu (夏威夷时区, UTC-10)
欧洲 (Europe)
- Europe/London (格林尼治平均时间, UTC+0)
- Europe/Paris (中欧时区, UTC+1)
- Europe/Athens (东欧时区, UTC+2)
- Europe/Moscow (莫斯科时区, UTC+3)
亚洲 (Asia)
- Asia/Dubai (海湾标准时间, UTC+4)
- Asia/Karachi (巴基斯坦标准时间, UTC+5)
- Asia/Dhaka (孟加拉国标准时间, UTC+6)
- Asia/Bangkok (印度支那时间, UTC+7)
- Asia/Shanghai (中国标准时间, UTC+8)
- Asia/Tokyo (日本标准时间, UTC+9)
- Australia/Sydney (澳大利亚东部时间, UTC+10)
- Pacific/Auckland (新西兰标准时间, UTC+12)
大洋洲 (Oceania)
- Pacific/Fiji (斐济时间, UTC+12)
- Pacific/Tongatapu (汤加时间, UTC+13)
非洲 (Africa)
- Africa/Casablanca (摩洛哥时间, UTC+0)
- Africa/Lagos (西非时间, UTC+1)
- Africa/Johannesburg (南非标准时间, UTC+2)
南美洲 (South America)
- America/Bogota (哥伦比亚时间, UTC-5)
- America/Caracas (委内瑞拉时间, UTC-4)
- America/Buenos_Aires (阿根廷时间, UTC-3)

这些时区名称遵循 "大洲/城市" 的命名规则，代表了特定城市或地区的标准时间（不考虑夏令时的影响）。全球各地区根据其地理位置和政治决定选择使用哪个时区。