跳至主要內容

云函数内置函数库

约 8882 字大约 30 分钟

云函数内置函数库

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 坐标,转化后的坐标可以在腾讯地图、高德地图上正确显示位置。

参数

  • pointMapPoint 类型,参考 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

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

参数

  • pointMapPoint 类型,输入当前位置坐标。
  • circleMapCircle 类型,圆形地理区域。参考 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

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

参数

  • pointMapPoint 类型,输入当前位置坐标。
  • polygonMapPolygon 类型,多边形地理区域。参考 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 字节序列。

参数

  • datastring 字符串类型。

返回值

  • Buffer 字节流类型。

示例

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

Cloud.Utils.strToHex(data)

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

参数

  • datastring 字符串类型。

返回值

  • string 类型,表示十六进制 HEX。

示例

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

Cloud.Utils.strToBase64(data)

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

参数

  • datastring 字符串类型。

返回值

  • 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 转为字符串。

参数

  • datastring 类型,有效的 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 字符串。

参数

  • dataBuffer 字节流类型。

返回值

  • string 类型:表示十六进制 HEX。

示例

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

Cloud.Utils.bufferToStr(data)

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

参数

  • dataBuffer 字节流类型。

返回值

  • 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)

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

参数

  • datanumberstring 类型。

返回值

  • 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 字符编码

参数

  • datastring 字符串类型。

返回值

  • string 类型,表示十六进制 HEX。

示例

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

Cloud.Utils.decodeGB2312(data)

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

参数

  • dataBuffer 字节流类型。

返回值

  • string 类型。

示例

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

Cloud.Utils.decodeGBK(data)

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

参数

  • dataBuffer 字节流类型。

返回值

  • 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)

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

参数

提示

所有日期时间函数的默认时区是 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 系统,而且在各种编程语言和应用中都被广泛采用。

参数

示例

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 时间戳,单位是毫秒。

参数

示例

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)

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

参数

示例

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 对象

参数

示例

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)

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

参数

unit 取值如下:

单位简写说明
yeary
monthM
weekw
dayd
hourh小时
minutem分钟
seconds
millisecondms毫秒

示例

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)

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

参数

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 取值如下:

单位简写文字说明
yeary当前年份的开始(1月1日 00:00:00)
monthM当前月份的开始(该月的第一天 00:00:00)
weekw当前周的开始(周一 00:00:00)
dayd当前日的开始(00:00:00)
hourh当前小时的开始(分钟和秒均为 00)
minutem当前分钟的开始(秒为 00)
seconds当前秒的开始(毫秒为 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 取值同 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)

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

参数

示例

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:周六

参数

示例

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

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

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

参数

unit 取值如下:

单位简写说明
yeary
monthM
quarterQ季度
weekw
dayd
hourh小时
minutem分钟
seconds
millisecondms毫秒

示例

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。

参数

unit 取值如下:

单位简写说明
yeary
monthM
weekw
dayd
hourh小时
minutem分钟
seconds

示例

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。

参数

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。

参数

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。

参数

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。

参数

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 之间。

参数

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

日期时间输出格式

格式符号输出示例说明
YYYY20244位数年份
YY242位数年份
MMMMJanuary月份的完整名称
MMMJan月份的缩写
MM012位数月份
M1月份
D2
DD022位数的日
d0-6星期中的第几天,星期天为0
H1424小时制的小时数
HH1424小时制的2位小时数
h212小时制的小时数
hh0212小时制的2位小时数
m5分钟
mm052位数分钟
s9
ss092位数秒
SSS9
APM大写的AM或PM
apm小写的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)

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