云函数内置函数库

约 8810 字大约 29 分钟

云函数内置函数库

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}
*/

数据类型转换函数

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，依赖于 dayjs 的配置）
`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.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)

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