通信连接组件

« 返回首页

通信连接组件

目录:

  1. icon Activity启动器 指导
  2. 应用更新图标 应用更新 指导
  3. icon 蓝牙客户端
  4. icon 蓝牙服务器
  5. icon 低功耗蓝牙
  6. icon 串口通信器 指导
  7. icon Web客户端 指导
  8. icon MQTT客户端
  9. icon 二进制 指导
  10. icon Socket客户端 指导
  11. icon WebSocket客户端 指导
  12. icon 下载器 指导
  13. 【UDP】 UrsAI2UDP 拓展 - UDP广播通信协议

icon Activity启动器

使用启动Activity方法启动一个Activity(活动)的组件。

可启动的Activity包括:

  • 为 Android 应用启动另一个 App Inventor。 首先通过下载源代码并使用文件资源管理器或解压缩utility,找到一个名为“youngandroidproject/project.properties”的文件,找出另一个程序的的类。

    文件的第一行将开始使用“main=”并后跟类名。 例如:main=com.gmail.Bitdiddle.Ben.HelloPurr.Screen1(第一个组件表明它是由 Ben.Bitdiddle@gmail.com 创建)要让您的 Activity启动器 启动此应用程序,设置以下属性:

    • ActivityPackage 到类名,删除最后一个组件(例如: com.gmail.Bitdiddle.Ben.HelloPurr)
    • ActivityClass 到整个类名(例如:com.gmail.Bitdiddle.Ben.HelloPurr.Screen1)
  • 通过设置以下属性启动相机应用程序:
    • Action: android.intent.action.MAIN
    • ActivityPackage: com.android.camera
    • ActivityClass: com.android.camera.Camera
  • 执行网络搜索。 假设您要搜索的词是“vampire”(您可以随意替换自己的选择),将属性设置为:
    • Action: android.intent.action.WEB_SEARCH
    • ExtraKey: query
    • ExtraValue: vampire
    • ActivityPackage: com.google.android.providers.enhancedgooglesearch
    • ActivityClass: com.google.android.providers.enhancedgooglesearch.Launcher
  • 打开浏览器到指定的网页。 假设您要访问的页面是“www.fun123.cn”(您可以随意替换自己的选择),将属性设置为:
  • 打开系统照相机(比照相机组件打开的界面会丰富一些)
    • Action: android.media.action.STILL_IMAGE_CAMERA
  • 可选取多个文件(图片、音频、视频等):
    • Action: android.intent.action.GET_CONTENT

更多有关Activity启动器使用技巧请查看《Activity启动器如何查看并启动其他App》。

使用指导查看其他 App 的包名与类名并启动它查看 →

属性

Action
指定将用于启动Activity活动的操作。
Activity类名
指定将启动的特定组件的Class类部分。
Activity包名
指定将启动的特定组件的包部分。
数据类型
指定要传递给Activity活动的 MIME 类型。
数据URI
指定将用于启动Activity活动的数据URI。
ExtraKey
指定将传递给Activity活动的额外键。(已过时,应使用 Extras)
ExtraValue
指定将传递给Activity活动的额外值。(已过时,应使用 Extras)
Extras
返回将作为额外数据传递给Activity活动的键值对列表。
结果
返回Activity活动的结果。
结果名称
指定一个名称,用于从Activity活动中获取结果。
结果类型
从Activity活动中返回的结果 MIME 类型。
结果URI地址
从Activity活动中返回的结果URI。

事件

取消活动调用()
如果此 Activity启动器 因为Activity活动被取消而返回,则引发该事件。
活动调用结束(result)
此 Activity启动器 返回后触发的事件。

方法

处理活动信息()
返回与此 Activity启动器 对应的Activity活动名称,如果找不到相应的Activity活动,则为空字符串。
启动活动对象()
启动这个 Activity启动器 对应的Activity活动。

应用更新图标 应用更新

不可见组件:检查服务器上的版本文件,发现新版本后下载安装包,并调起系统安装,完成应用内更新。 适合自己分发、不上架应用市场的应用,比如学校、企业内部使用的应用和比赛作品。

默认使用内置对话框:发现新版自动弹出更新提示,下载时显示进度,下完自动调起安装, 只需在屏幕初始化时调用一次「检查更新」。想自己设计界面,把「使用内置对话框」设为假,改用事件即可。

使用指导版本文件与发布步骤、内置对话框、自定义界面、强制更新的完整案例查看 →

准备版本文件

在自己的服务器(或任何能直接下载的网盘直链)放一个 JSON 文件,每次发布新版时更新它:

{
  "versionCode": 12,
  "versionName": "1.2",
  "url": "https://example.com/myapp-1.2.apk",
  "notes": "1. 新增夜间模式\n2. 修复登录问题",
  "force": false
}
字段 必填 说明
versionCode 是 新版的版本号(整数),对应屏幕属性里的「版本号」,比手机上已装的大才算新版
url 是 新版安装包(APK)的下载地址
versionName 否 显示给用户的版本名,如 1.2
notes 否 更新说明,\n 换行
force 否 真 = 强制更新:对话框没有「稍后」,不能关闭

发布新版的步骤:在屏幕属性里把「版本号」加 1(「版本名」按需修改)→ 编译 APK 上传到服务器 → 修改版本文件的 versionCode 和 url。

新版安装包必须满足:与已装的应用包名相同、用同一个账号编译(签名相同)、版本号更高。 组件在安装前会自动检查,不满足时不安装,并触发更新失败。

快速上手

最简用法,使用内置对话框:

when Screen1.Initialize() {
  AppUpdate1.CheckUpdate("https://example.com/version.json")
}

自己设计界面(把「使用内置对话框」设为假):

global newApkUrl = ""

when AppUpdate1.UpdateAvailable(版本号, 版本名, 更新说明, 安装包地址, 强制更新) {
  Label1.Text = join("发现新版 ", 版本名, ":", 更新说明)
  newApkUrl = 安装包地址
  Button1.Visible = true
}

when Button1.Click() {
  AppUpdate1.DownloadAndInstall(newApkUrl)
}

when AppUpdate1.DownloadProgress(百分比) {
  Label1.Text = join("下载中 ", 百分比, "%")
}

when AppUpdate1.UpdateFailed(阶段, 消息) {
  Label1.Text = join(阶段, "失败:", 消息)
}

注意事项

  • 安装权限:安卓 8 及以上,第一次更新时系统会要求允许本应用「安装未知应用」,允许后回到应用会自动继续安装。
  • 在 AI 伴侣里测试:「本机版本号」是伴侣自己的版本号,安装那一步也会因包名不同被拦下。检查更新和下载可以在伴侣里试,完整流程请用编译出的 APK 测试。
  • 应用市场:上架 Google Play 的应用不允许自行下载安装包更新;国内应用商店对应用内自更新也有审核限制,一般要求通过商店更新。上架了应用市场的应用请用应用工具的打开应用市场。
  • 鸿蒙:系统不允许应用自行安装,「下载并安装」会触发更新失败,内置对话框的按钮改为「前往应用市场更新」(应用需已上架华为应用市场)。检查更新和各事件与安卓一致。

属性

本机版本号
当前应用的版本号(整数),对应屏幕属性里的「版本号」。
本机版本名
当前应用的版本名,如 1.0,对应屏幕属性里的「版本名」。
正在下载
是否正在下载安装包。
通知栏显示进度
下载时在通知栏显示进度条,默认为真。
使用内置对话框
默认为真:发现新版自动弹出更新对话框,下载时显示进度;强制更新时对话框不能关闭,下载完成后保留「安装」按钮。 设为假时只触发事件,界面自己设计。

事件

下载完成(安装包路径)
安装包下载完成,随后自动调起安装。
下载进度(百分比)
下载进度,0~100。
已是最新()
版本文件里的版本号不大于本机版本号。
发现新版(版本号,版本名,更新说明,安装包地址,强制更新)
发现新版本。开启内置对话框时也会触发,可用来记录或显示。
更新失败(阶段,消息)
阶段 为 检查、下载 或 安装;消息 是中文原因,如「网络不通」「版本文件缺少整数 versionCode」「手机存储空间不足」「不是本应用的安装包」「未允许本应用安装未知应用」。

方法

取消下载()
取消正在进行的下载。
检查更新(URL网址)
读取版本文件,与本机版本号比较:有新版触发发现新版(开启内置对话框时同时弹出更新提示), 否则触发已是最新;读取失败触发更新失败。
下载并安装(安装包地址)
下载安装包,下完自动调起系统安装。安装前检查安装包与本应用包名相同且版本号更高; 未允许「安装未知应用」时先打开系统授权页,允许后回到应用自动继续安装。

icon 蓝牙客户端

使用 蓝牙客户端 通过蓝牙将您的设备连接到其他设备。这个组件使用串行端口配置文件 (SPP) 进行通信。

如果您有兴趣使用低能耗蓝牙,请查看《App Inventor 2 低功耗蓝牙(BLE) 硬件接入、数据通信及IO控制》。

如果您希望了解经典蓝牙与BLE之间的区别,请查看《低功耗蓝牙(BLE) 和 经典蓝牙(SPP) 的区别》。

基本接入代码参考:

  • 显示已配对的SPP经典蓝牙列表:

  • 选择一个蓝牙设备进行连接:

  • 断开当前连接的设备:

  • 错误处理:

  • 测试demo下载:

    spp_demo

属性

地址及名称
返回配对的蓝牙设备列表,返回的列表每个元素都是一个字符串,由设备地址、一个空格和设备的名称组成。

蓝牙设备列表为空?

你可能没有开启AI伴侣或编译后App的发现蓝牙权限,这里以AI伴侣为例,勾上即可:
开启发现蓝牙设备的权限

需要过滤蓝牙设备列表?

请参考《App Inventor 2 过滤蓝牙设备列表》。

可用状态
如果设备上有蓝牙功能,则返回真,否则返回假。
字符编码
返回发送和接收文本时使用的字符集编码(如GBK,UTF-8)。
分隔符字节码
调用 ReceiveText、ReceiveSignedBytes 或 ReceiveUnsignedBytes 返回传递负数时使用的分隔符字节码。
错误时断开连接
指定 蓝牙客户端/蓝牙服务器 是否在发生错误时自动断开连接。
启用
如果启用了蓝牙,返回真,否则返回假。
高位优先
指定发送和接收数字时是否使用最高有效位字节优先。
是否已连接
如果已建立与蓝牙设备的连接,则返回 真。
轮询率
返回蓝牙客户端配置的轮询速率值。
不用于定位
表明蓝牙不被用来确定用户位置,需安卓12或以上。
启用安全连接
指定是否启用安全连接。

事件

无

中文网注:

蓝牙客户端没有“当收到数据时”的事件(即收到服务端数据后触发的事件),只能通过定时器定期轮询接收数据,而BluetoothLE低功耗蓝牙拓展拥有这个事件。

方法

获取接收字节数()
返回输入流中可用的字节数。
连接(地址)
连接到指定地址的蓝牙设备。

连接报错? Runtime Error: Need android.permission.BLUETOOTH_CONNECT …

BLUETOOTH_CONNECT_permission

这时需要请求蓝牙连接权限,参考代码如下:
请求蓝牙连接权限

连接指定设备(地址,唯一编号)
连接到指定地址和UUID的蓝牙设备。
断开连接()
断开已连接的蓝牙设备。
检查设备是否配对(地址)
检查指定地址的蓝牙设备是否已配对。
接收单字节带符号数字()
读取带符号的 1 字节数字。
接收双字节带符号数字()
读取带符号的 2 字节数字。
接收四字节带符号数字()
读取带符号的 4 字节数字。
接收带符号字节数组(字节数)
从输入流中读取指定数量(字节数)的带符号的字节,并将它们作为列表返回。

如果 字节数 为负数,则读取到分隔符字节码(分隔符字节码属性指定的)为止,分隔符字节码包含在返回的列表中。

接收文本(字节数)
从输入流中读取指定数量(字节数)的带符号的字节,并将它们转换为文本。

如果 字节数 为负数,则读取到分隔符字节码(分隔符字节码属性指定的)为止。

接收单字节无符号数字()
读取一个无符号的 1 字节数字。
接收双字节无符号数字()
读取一个无符号的 2 字节数字。
接收四字节无符号数字()
读取一个无符号的 4 字节数字。
接收无符号字节数组(字节数)
从输入流中读取指定数量(字节数)的无符号的字节,并将它们作为列表返回。

如果 字节数 为负数,则读取到分隔符字节码(分隔符字节码属性指定的)为止,分隔符字节码包含在返回的列表中。

发送单字节数字(数值)
将指定的数值字符串转换成整数,并将其作为 1 个字节写入到输出流。

如果数值无法转换为整数,或转换的整数 1 个字节不够表达,将触发屏幕的 出现错误时 事件,然后方法直接返回,不会向输出流中写入任何字节。

发送双字节数字(数值)
将指定的数值字符串转换成整数,并将其作为 2 个字节写入到输出流。

如果数值无法转换为整数,或转换的整数 2 个字节不够表达,将触发屏幕的 出现错误时 事件,然后方法直接返回,不会向输出流中写入任何字节。

发送四字节数字(数值)
将指定的数值字符串转换成整数,并将其作为 4 个字节写入到输出流。

如果数值无法转换为整数,或转换的整数 4 个字节不够表达,将触发屏幕的 出现错误时 事件,然后方法直接返回,不会向输出流中写入任何字节。

发送字节数组(列表)
从指定列表中取出每个元素,将其转换为字符串,字符串转换成整数,并将其作为 1 个字节写入到输出流。

如果一个元素无法转换为整数,或转换的整数 1 个字节不够表达,将触发屏幕的 出现错误时 事件,然后方法直接返回,不会向输出流中写入任何字节。

发送文本(文本)
将指定文本转换为字节并将它们写入到输出流。

icon 蓝牙服务器

使用 蓝牙服务器 组件将您的设备变成接收来自其他使用 蓝牙客户端 组件的应用程序连接的服务器。

属性

可用状态
如果设备上有蓝牙功能,则返回真,否则返回假。
字符编码
返回发送和接收文本时使用的字符编码。
分隔符字节码
调用 ReceiveText、ReceiveSignedBytes 或 ReceiveUnsignedBytes 返回传递负数时使用的分隔符字节码。
启用
如果启用了蓝牙,返回真,否则返回假。
高位优先
指定发送和接收数字时是否使用最高有效位字节优先。
接收状态
如果此 蓝牙服务器 组件正在接受一个传入连接,则返回真。
连接状态
如果与蓝牙设备已建立连接,则返回 真。
启用安全连接
指定是否启用安全连接。

事件

接受连接()
表示已接受蓝牙连接。

中文网注:

蓝牙服务端没有“当收到数据时”的事件(即收到客户端数据后触发的事件),只能通过定时器定期轮询接收数据,而BluetoothLE低功耗蓝牙拓展拥有这个事件。

方法

接受连接(服务名)
接受使用串行端口配置文件 (SPP) 进行通信的传入连接。
接受与指定设备连接(服务名,唯一编号)
接受指定 UUID 的传入连接。
获取接收字节数()
返回输入流中可用的字节数。
断开连接()
断开当前已连接的蓝牙设备。
接收单字节带符号数字()
读取带符号的 1 字节数字。
接收双字节带符号数字()
读取带符号的 2 字节数字。
接收四字节带符号数字()
读取带符号的 4 字节数字。
接收带符号字节数组(字节数)
从输入流中读取指定数量(字节数)的带符号的字节,并将它们作为列表返回。

如果 字节数 为负数,则读取到分隔符字节码(分隔符字节码属性指定的)为止,分隔符字节码包含在返回的列表中。

接收文本(字节数)
从输入流中读取指定数量(字节数)的带符号的字节,并将它们转换为文本。

如果 字节数 为负数,则读取到分隔符字节码(分隔符字节码属性指定的)为止。

接收单字节无符号数字()
读取一个无符号的 1 字节数字。
接收双字节无符号数字()
读取一个无符号的 2 字节数字。
接收四字节无符号数字()
读取一个无符号的 4 字节数字。
接收无符号字节数组(字节数)
从输入流中读取指定数量(字节数)的无符号的字节,并将它们作为列表返回。

如果 字节数 为负数,则读取到分隔符字节码(分隔符字节码属性指定的)为止,分隔符字节码包含在返回的列表中。

发送单字节数字(数值)
将指定的数值字符串转换成整数,并将其作为 1 个字节写入到输出流。

如果数值无法转换为整数,或转换的整数 1 个字节不够表达,将触发屏幕的 出现错误时 事件,然后方法直接返回,不会向输出流中写入任何字节。

发送双字节数字(数值)
将指定的数值字符串转换成整数,并将其作为 2 个字节写入到输出流。

如果数值无法转换为整数,或转换的整数 2 个字节不够表达,将触发屏幕的 出现错误时 事件,然后方法直接返回,不会向输出流中写入任何字节。

发送四字节数字(数值)
将指定的数值字符串转换成整数,并将其作为 4 个字节写入到输出流。

如果数值无法转换为整数,或转换的整数 4 个字节不够表达,将触发屏幕的 出现错误时 事件,然后方法直接返回,不会向输出流中写入任何字节。

发送字节数组(列表)
从指定列表中取出每个元素,将其转换为字符串,字符串转换成整数,并将其作为 1 个字节写入到输出流。

如果一个元素无法转换为整数,或转换的整数 1 个字节不够表达,将触发屏幕的 出现错误时 事件,然后方法直接返回,不会向输出流中写入任何字节。

发送文本(文本)
将指定文本转换为字节并将它们写入到输出流。
停止接受连接()
停止接受传入连接。

icon 串口通信器

串口通信组件。手机串口通信案例、接线示意与视频请参考串口通信器使用指导。

使用指导USB 串口原样收发字节;完整回显诊断、半包缓存、校验与超时案例查看 →

属性

波特率
返回当前波特率。
缓冲区大小
单次最多读取的字节数,默认 256,允许 1~8192;不是一帧的长度。可在设计器和代码块中设置。
是否已初始化
当串口已初始化时返回 真。
是否打开
当串口连接打开时返回 真。

事件

无

方法

关闭串口()
关闭串口连接。关闭成功时返回 真。
初始化串口()
初始化串口连接。
打开串口()
打开串口连接。 打开成功时返回 真。
读取字节()
读取当前到达的原始字节,返回 0~255 的列表;没有数据返回空列表,最多读取“缓冲区大小”个字节。先初始化并打开串口,不经过文本转换。半包、多包需要按协议缓存拆帧,见完整串口回显案例。
写入字节(字节列表)
将列表原样写入串口,不追加换行。可直接发送二进制组件的拼接/追加校验结果。先初始化并打开串口,发送后仍需读取设备确认;空列表不发送。
读取串口()
从串口读取数据,返回utf-8格式的文本。(如果返回的文本是乱码,请检查发送的数据是否是utf-8编码格式文本)
写入串口(data)
将给定数据写入串口。
写入串口并添加新行(data)
将给定数据写入串口,并在末尾添加一个新行。等同于:写入串口(data + "\n")。

icon 二进制

二进制组件:拼接字节、十六进制与文本互转、多字节整数与浮点数互转、截取与查找、累加/异或/CRC 校验。

字节列表就是由 0~255 的数字组成的普通列表,可直接交给蓝牙客户端、低功耗蓝牙、 Socket客户端、WebSocket客户端、MQTT客户端收发,现成的列表积木(取第几项、截取、长度、遍历)都能用。 本组件无状态:每个方法都是「字节列表进、结果出」,不需要事件。

输入很宽容:负数按补码(-1 就是 255,蓝牙「接收有符号字节」的结果可直接用),数字文本和 0x 开头的十六进制文本也认。 出错时触发屏幕的「出现错误时」,错误信息会说清是第几项、为什么不对,并返回空列表或 0。

各通信组件怎么收发二进制、怎么组合使用,见二进制数据专题;完整案例见使用指导。

使用指导拼帧加校验、解析回复、float 互转、状态位、与网络调试助手联调的完整案例查看 →

快速上手

拖一个二进制组件、一个Socket客户端、一个按钮和两个标签。点按钮发一帧「帧头 A5 + 命令 01 + 两字节数值 1500 + 累加校验」, 收到设备回复时核对校验并取出第 3、4 个字节组成的数值:

when 按钮1.Click() {
  var 帧 = 二进制1.Build([165, 1, 二进制1.NumberToBytes(1500, 2)])
  var 完整帧 = 二进制1.AppendChecksum(帧, "SUM8")
  标签1.Text = 二进制1.ToHex(完整帧)
  Socket客户端1.SendBytes(完整帧)
}

when Socket客户端1.BytesReceived(字节列表) {
  if (二进制1.VerifyChecksum(字节列表, "SUM8")) {
    标签2.Text = 二进制1.BytesToNumber(字节列表, 3, 2, false)
  } else {
    标签2.Text = "校验不对,丢弃"
  }
}

标签1 显示 A5 01 05 DC 87:05 DC 是 1500 的两个字节(高位在前),87 是前四个字节之和的低 8 位。

属性

十六进制分隔符
「字节转十六进制」输出时字节之间的分隔符。默认一个空格,输出 A5 01 FF;设为空文本输出 A501FF;设为逗号输出 A5,01,FF。
高位优先
多字节整数与浮点数的字节顺序。

真(默认)=高字节在前,也叫大端,网络协议与 Modbus 寄存器常用; 假=低字节在前,也叫小端,ESP32、STM32 等单片机直接发送内存里的数字时常用。 CRC16-MODBUS 校验按协议规定固定低字节在前,不受本属性影响。

文本编码
文本与字节互转用的编码:UTF-8(默认)、GBK(国内很多串口屏与单片机用)或 ASCII。 同时影响「拼接字节」里文本部分的转换。

方法

追加校验(字节列表,校验类型)
在字节列表末尾追加校验,返回新列表:SUM8、XOR8、CRC8 追加 1 个字节,CRC16 追加 2 个,CRC32 追加 4 个。 CRC16-MODBUS 按协议规定低字节在前,其余按「高位优先」属性。校验类型见计算校验。 例:01 03 00 00 00 0A 追加 CRC16-MODBUS → 01 03 00 00 00 0A C5 CD;A5 01 05 DC 追加 SUM8 → A5 01 05 DC 87。
Base64转字节(文本)
Base64 文本解码为字节列表,是「字节转Base64」的反向。例:pQH/ → [165, 1, 255];网址安全写法 pQH_ 也认。 空文本返回空列表;不是有效的 Base64 时报错并返回空列表。
拼接字节(各部分)
把多个部分按顺序拼成一个字节列表,一块积木拼完一整帧:
  • 数字算一个字节(0~255,负数按补码);
  • 文本按「文本编码」转成字节,例如 "OK" 是 4F 4B;
  • 列表当作字节列表整段接上,列表里的数字文本(如「分解文本」切出来的 "255")按数字处理。

注意:文本框、分解文本得到的 "12" 放在顶层是文本(两个字符 31 32),要当一个字节用请先放进列表或做一次数学运算。

字节转Base64(字节列表)
字节列表编码为 Base64 文本(不换行),用于在 JSON、网页接口里传二进制。例:[165, 1, 255] → pQH/。
字节转小数(字节列表,起始位置,字节数)
从第「起始位置」个字节(从 1 数起)开始取 4 或 8 个字节,按 IEEE754 浮点数解读成小数,按「高位优先」。 例如 41 BC 00 00 是 23.5。
字节转整数(字节列表,起始位置,字节数,有符号)
从第「起始位置」个字节(从 1 数起)开始取「字节数」个字节(1、2、3、4 或 8)拼成整数,按「高位优先」解读。

「有符号」为真时按补码解读,例如 FF FE 得 -2;为假时得 65534。温度这类可能为负的值用有符号,计数、长度用无符号。 8 字节一律按有符号;数字超过安全整数范围 ±9007199254740991 时报错,设备编号请保留字节或十六进制文本。数据不够长时报错并返回 0。

计算校验(字节列表,校验类型)
计算字节列表的校验值。「校验类型」可选(大小写与横线可省略,如 modbus、crc16modbus 都行):
类型 字节数 说明
SUM8 1 所有字节相加取低 8 位(累加和)
XOR8 1 所有字节依次异或(BCC)
CRC8 1 多项式 0x07,初值 0
CRC16-MODBUS 2 Modbus RTU 用,初值 0xFFFF
CRC16-CCITT 2 多项式 0x1021,初值 0xFFFF(CCITT-FALSE)
CRC16-XMODEM 2 多项式 0x1021,初值 0
CRC32 4 与 zip、以太网相同

对 123456789 这 9 个字符,各算法结果依次是 DD、31、F4、4B37、29B1、31C3、CBF43926,可用来核对设备端的实现。

小数转字节(数值,字节数)
小数转成 IEEE754 浮点数的字节:「字节数」为 4(单精度 float,单片机最常用)或 8(双精度 double),按「高位优先」排列。
十六进制转字节(十六进制文本)
十六进制文本转字节列表。空格、逗号、冒号、横线与 0x 前缀都会被忽略, "A5 01 ff"、"0xA5,0x01,0xFF"、"A501FF" 都行;位数为单数时报错。
文本转字节(文本)
把文本转成字节列表,每个字符按「文本编码」变成一个或几个字节。

例:"OK" → [79, 75](即 4F 4B);UTF-8 下 "你" → [228, 189, 160](E4 BD A0),GBK 下 → [196, 227](C4 E3)。 注意它是把文字本身转成字节:要把文本框里的 "ABCD" 当十六进制发成 AB CD 两个字节,用十六进制转字节, 见文本框输入十六进制按字节发送。

取位(数值,位序号)
取整数的第「位序号」位(最低位是第 0 位)是否为 1,常用于解读状态字节里的开关标志。 例:5 的二进制是 0000 0101,取第 0 位 → 真,第 1 位 → 假,第 2 位 → 真。
查找字节(字节列表,查找内容,起始位置)
从第「起始位置」个字节起查找「查找内容」第一次出现的位置(从 1 数起),找不到返回 0。 查找内容可以是一个字节(如 165)或一段字节列表(如帧头 A5 5A),用来在收到的数据里定位帧头。
整数转字节(数值,字节数)
整数转成指定字节数(1、2、3、4 或 8)的字节列表,按「高位优先」排列。 负数按补码,例如 -2 转 2 字节是 FF FE;超出该字节数能表示的范围时报错,例如 70000 放不进 2 个字节。
读取文件字节(路径)
读取不超过 1MB 的文件,返回每项为 0–255 的字节列表。路径可用保存字节到文件返回的完整路径;只写文件名时先找本应用保存的文件,再找项目素材。读不到或文件过大时触发屏幕的「出现错误时」,返回空列表。
保存字节到文件(字节列表,文件名)
把不超过 1MB 的字节列表原样写成文件,覆盖同名文件,返回完整路径,可交给上传、分享或再次读取。只写文件名时保存在本应用目录,卸载应用时一起删除;以 / 开头时按完整路径写入。失败时触发屏幕的「出现错误时」,返回空文本。
设置位(数值,位序号,置为1)
把整数的第「位序号」位(最低位是第 0 位)设为 1(「置为1」为真)或 0(为假),返回新的整数。 用来拼控制字节,例如继电器板每一位对应一路开关。
截取字节(字节列表,起始位置,长度)
从第「起始位置」个字节(从 1 数起)开始截取「长度」个字节,拆解收到的数据帧时用。 例:A5 01 05 DC 87 从第 3 个取 2 个 → 05 DC。超出数据长度时报错并返回空列表。
字节转十六进制(字节列表)
字节列表转十六进制文本(大写,字节之间用「十六进制分隔符」隔开),如 A5 01 FF。调试时显示收发内容最常用。
字节转文本(字节列表)
把字节列表按「文本编码」还原成文本,是「文本转字节」的反向。例:[79, 75] → "OK";UTF-8 下 [228, 189, 160] → "你"。 无法识别的字节显示为替换符号。
核对校验(字节列表,校验类型)
核对收到的一帧数据末尾的校验是否正确(规则与「追加校验」相同),正确返回真;校验不对或数据太短返回假。 例:A5 01 05 DC 87 按 SUM8 核对 → 真;最后一个字节改成 88 → 假。

平台说明

安卓与鸿蒙行为一致,结果逐字节相同。鸿蒙上 8 字节整数超过 2 的 53 次方时会损失精度(JavaScript 数字限制),一般用不到。

icon Socket客户端

TCP Socket 客户端组件。

该组件用于主动连接远程 Socket 服务端,并提供文本或二进制数据的发送能力。 连接建立后会在后台线程持续监听服务端返回的数据,再通过事件把结果切回主线程抛给积木层。

Socket 客户端现已作为原生组件提供,新项目无需导入拓展;使用旧拓展的项目请先备份,再按原生组件迁移。

使用指导不可见组件,提供 TCP Socket 客户端连接、文本/二进制/文件收发功能查看 →

快速上手

  1. 拖一个 Socket客户端 到屏幕,属性面板填好服务器地址与端口;
  2. 搭下面的代码块:连上就打招呼,收到什么就显示什么。
when Socket客户端1.Connected() {
  Socket客户端1.SendText("hello\n")
}

when Socket客户端1.MessageReceived(消息) {
  标签1.Text = 消息
}

when Socket客户端1.ConnectFailed(消息) {
  标签1.Text = join("连接失败:", 消息)
}

发送文本时通常在末尾加换行符 \n(Windows 风格的服务端用 \r\n),方便服务端按行读取。

和单片机、工控设备收发二进制协议帧时,用发送字节数组发、收到字节时收, 配合二进制组件拼包、算校验、解析数字、把十六进制文本转成字节。完整做法见二进制数据专题。

属性

连接状态
返回当前连接状态。

返回 true 表示当前 Socket 已建立连接; 返回 false 表示未连接、正在断开,或连接已关闭。

服务器地址
设置要连接的服务器地址。

通常填写 IP 地址或域名,例如 192.168.1.10 或 example.com。

服务器端口
设置要连接的服务器端口。

例如 80、443、9000 等。

超时毫秒
服务器连接超时时间(毫秒)

事件

收到字节时(字节列表)
收到服务器数据时触发,字节列表 是这次收到的原始字节(0~255 的数字)。

与收到消息时同时触发。 TCP 是字节流:一帧数据可能分几次到达,也可能几帧一起到达,需要时先接到一个全局列表里,再按帧头和长度拆, 做法见二进制数据专题。

连接失败时(消息)
当异步连接失败时触发。

该事件通常表示主机不可达、端口错误、超时,或地址格式不正确。

已连接时()
当异步连接成功建立后触发。

建议在该事件中开始发送数据,而不是在调用 连接() 后立即发送。

已断开时()
当本地主动断开连接并完成资源释放后触发。

该事件仅表示本地主动调用 断开() 后的完成通知, 不代表远端主动断开。

文件发送失败时(文件名,消息)
文件发送失败时触发。

未连接、文件不存在、连接中断等任何失败都会触发本事件, 消息 参数给出具体原因(同时也会通过错误弹窗提示)。

文件发送进度更新时(文件名,已发送字节数,总字节数)
文件发送过程中周期性触发。

按完成百分比推进(最多约 100 次),可在该事件中更新进度条或标签文字。

文件发送完成时(文件名,已发送字节数)
文件全部发送完成后触发。

需要在文件末尾追加结束符或继续发送下一段内容的协议, 可以在本事件中继续调用 发送文本 或下一个 发送文件。

收到消息时(消息)
当接收到服务器发来的数据时触发。

数据按 UTF-8 转成文本;要原始字节请用收到字节时。

远端连接关闭时()
当远端主动关闭连接,或接收线程检测到连接被远端中断时触发。

该事件用于区分“本地主动断开”和“服务端或网络导致连接中断”这两种情况。

方法

连接()
异步发起连接,并在连接成功后启动后台接收线程。

本方法调用后会立即返回,不会阻塞界面线程。 真正连接成功时会触发已连接时事件; 连接失败时会触发连接失败时事件,同时也会抛出错误事件。

如果当前已经连接,或者仍处于连接进行中,则本次调用会直接报错并返回。

断开()
异步断开与服务器的连接。

本方法会在后台线程关闭输入流和 Socket 本身,并在完成后触发已断开时事件。 如果当前并未连接,或者已经处于断开过程中,则会直接报错并返回。

发送字节数组(字节列表)
向服务器发送二进制数据,适合发送原始二进制协议帧。

参数是字节列表(0~255 的数字,负数按补码,数字文本也认)。格式不对或未连接时报错、不发送。 拼包、算校验、十六进制文本转字节用二进制组件。

发送文件(文件名)
把整个文件按原始字节直接发送到服务器。

文本文件、图片、音频等任意类型的文件都可以发送:内容按 64KB 分块从文件流写入 Socket, 不做任何转换, 二进制文件也能逐字节原样到达对端。大文件不会一次性读入内存。

文件名的三种写法: 以 // 开头表示工程素材(如 //logo.png); 绝对路径原样使用(如相机返回的 /storage/emulated/0/Pictures/xx.jpg); 相对文件名会依次在应用外部私有目录、内部目录、缓存目录中查找, 都找不到时再按素材名尝试——Web 组件勾选保存响应、File 组件下载的文件可直接用文件名。

发送在后台线程执行。过程中周期性触发文件发送进度更新时(最多约 100 次), 全部写出后触发文件发送完成时。本方法只写文件内容、不加任何帧, 推荐先用文件增强的「文件或目录大小」取到字节数,组成”先发长度行、再发文件”的主流协议: 接收端先读一行长度,再精确接收 N 个字节——文件内容里出现任何字节都不会被误认为边界(二进制安全)。 未连接、文件不存在、连接中断等任何失败都会触发文件发送失败时。 同一时刻只允许一个文件在发送,上一个文件结束(成功或失败)后再发下一个。

发送文本(文本)
以文本方式向服务器发送数据。

参数按 UTF-8 编码后发送。二进制协议帧请用发送字节数组。

真正的发送动作在后台线程执行,因此不会阻塞界面线程。

有关 Socket客户端(原 ClientSocketAI2Ext 拓展)的使用问题,点此参与讨论。

icon WebSocket客户端

WebSocket 客户端组件:连接 ws:// 或 wss://(加密)服务器,实时收发文本与二进制消息。

和 Web客户端 的「问一次答一次」不同,WebSocket 连上后一直保持连接,服务器可以随时主动推送, 适合聊天室、实时行情、订单提醒、设备状态上报等场景。和 Socket客户端(TCP)相比, 它走标准的网页端口与协议,能穿过代理和 HTTPS,服务器端几乎所有语言与云平台都直接支持。

使用指导WebSocket 客户端:连接 ws:// 或 wss:// 服务器,实时收发文本消息,适合聊天室、实时行情、设备状态推送等需要服务器主动推送的场景查看 →

快速上手

  1. 拖一个 WebSocket客户端 到屏幕,属性面板的 网址 填服务器地址,例如 wss://example.com/chat;
  2. 再放一个文本输入框、一个按钮、一个标签,搭下面的代码块:打开页面就连接,点按钮发送,收到的消息接在标签后面显示。
when Screen1.Initialize() {
  WebSocket客户端1.Connect()
}

when 按钮1.Click() {
  if (WebSocket客户端1.IsConnected) {
    WebSocket客户端1.SendText(文本输入框1.Text)
    文本输入框1.Text = ""
  }
}

when WebSocket客户端1.MessageReceived(消息) {
  标签1.Text = join(标签1.Text, " / ", 消息)
}

when WebSocket客户端1.ConnectFailed(消息) {
  标签1.Text = join("连接失败:", 消息)
}

断线自动重连:网络切换、服务器重启都会断开,在「已断开时」里延时几秒再连即可(主动断开时状态码是 1000,不重连):

when WebSocket客户端1.Disconnected(状态码, 原因) {
  if (状态码 != 1000) {
    after(3000) {
      WebSocket客户端1.Connect()
    }
  }
}

收发 JSON:服务器发来的多是 JSON 文本,用 Web客户端 的「用字典解码JSON文本」转成字典再按键取值; 发送时用字典的「转 JSON」或直接拼出 JSON 文本。

鉴权:本组件不能自定义请求头,令牌等参数请放在网址里,例如 wss://example.com/ws?token=abc。

二进制消息:设备或服务器发来二进制帧时,在「收到字节时」拿到字节列表;发送用「发送字节数组」,参数是字节列表。 拼包、算校验、解析数字用二进制组件,更多组合见二进制数据专题:

when WebSocket客户端1.Connected() {
  WebSocket客户端1.SendBytes(二进制1.FromHex("A5 01 00"))
}

when WebSocket客户端1.BytesReceived(字节列表) {
  标签1.Text = 二进制1.ToHex(字节列表)
}

属性

是否已连接
当前是否已连接。为 真 时才能发送消息;正在断开时也返回 假。
心跳间隔
心跳间隔(秒),默认 30。

定时向服务器发送心跳(ping),防止连接因长时间没有数据被路由器、代理断开; 连续两个间隔收不到服务器任何数据,就判定连接已断并触发已断开时(状态码 1006)。 填 0 关闭心跳。

网址
服务器地址,以 ws:// 或 wss:// 开头,例如 wss://example.com/chat。

也接受 http://、https:// 开头的地址,会自动换成对应的 ws://、wss://。

事件

连接失败时(消息)
连接没有建立成功时触发,例如网址不对、网络不通、服务器拒绝或证书不匹配,消息 为失败原因。
已连接时()
连接成功时触发。从这里开始才能发送消息。
已断开时(状态码,原因)
连接断开时触发,每次连接成功后恰好触发一次。

自己调用断开连接、服务器关闭连接、网络中断都会触发。 状态码 1000 表示正常关闭,1006 表示网络中断或心跳超时,其余由服务器给出;原因 为说明文字。

收到字节时(字节列表)
收到服务器发来的一条二进制消息时触发,字节列表 是完整的一条消息(0~255 的数字)。

二进制消息同时也会触发收到消息时(按 UTF-8 转成文本),按需处理其中一个即可;文本消息只触发「收到消息时」。

收到消息时(消息)
收到服务器发来的一条消息时触发。

服务器分多帧发送的消息会拼成一条再触发;二进制消息按 UTF-8 转成文本,要原始字节请用收到字节时。

方法

连接()
按网址连接服务器。

成功触发已连接时,失败触发连接失败时。 已连接或正在连接时再调用会报错,请先断开连接。

断开连接()
正常关闭连接(状态码 1000),完成后触发已断开时。未连接时不做任何事。
发送字节数组(字节列表)
向服务器发送一条二进制消息,参数是字节列表(0~255 的数字,负数按补码)。 格式不对或未连接时报错。拼包、算校验、十六进制文本转字节用二进制组件。
发送文本(文本)
向服务器发送一条文本消息(UTF-8)。未连接时报错,请在已连接时之后发送。

平台说明

  • 安卓:直接内置,不需要导入拓展,不额外增加安装包体积。
  • 鸿蒙:使用系统 WebSocket 能力,积木写法完全相同;心跳间隔在系统 API 21 及以上生效,更低版本由系统默认维持连接。

icon 下载器

下载器组件:把网上的文件下载保存到手机,可以同时下载多个,随时报告进度,下载完成后给出文件路径。

下载由系统负责,切到后台、锁屏都不会中断,还可以在通知栏显示进度。下载完成拿到的文件路径可以直接交给 图像、音频播放器、视频播放器 等组件使用。 如果只是请求接口拿数据,用 Web客户端;更新自己的应用安装包,用应用更新。

使用指导下载器:下载网上的文件并保存到手机,可同时下载多个,报告下载进度,完成后给出文件路径查看 →

快速上手

  1. 拖一个 下载器、一个按钮、一个标签、一个图像到屏幕;
  2. 搭下面的代码块:点按钮开始下载,标签显示进度,下完把图片显示出来。
when 按钮1.Click() {
  下载器1.Download("https://www.fun123.cn/static/images/logo.png", "")
}

when 下载器1.DownloadProgress(编号, 已下载, 总大小, 百分比) {
  标签1.Text = join("已下载 ", 百分比, "%")
}

when 下载器1.DownloadCompleted(编号, 文件路径) {
  标签1.Text = "下载完成"
  图像1.Picture = 文件路径
}

when 下载器1.DownloadFailed(编号, 原因) {
  标签1.Text = join("下载失败:", 原因)
}

同时下载多个:每次调用下载都会返回一个编号,事件里的 编号 就是它,用来分辨是哪一个下载。 可以把编号存进全局变量,或者存进字典对应到列表里的某一行。

属性

保存位置
文件保存到哪里,可选:
  • 应用目录(默认):应用自己的目录,不需要任何权限,卸载应用时一并删除;
  • 公共下载目录:手机的公共「下载」文件夹,在文件管理器里能看到,卸载应用后保留。安卓 9 及以下需要存储写入权限。
通知栏显示进度
下载时是否在通知栏显示进度,默认 真。设为 假 时不显示进度通知(鸿蒙仍会显示完成通知)。

事件

下载完成(编号,文件路径)
下载完成时触发,文件路径 为保存的完整路径。同名文件已存在时会自动改名(如 a-1.zip),以这里给出的路径为准。
下载失败(编号,原因)
下载失败或被取消时触发,原因 为中文说明,例如「网络错误,请检查网址」「服务器返回错误 404」「手机存储空间不足」「已取消」。

网址不合法等一开始就失败的情况,编号 为 -1。

下载进度(编号,已下载,总大小,百分比)
下载进度变化时触发。已下载、总大小 单位为字节,百分比 为 0~100 的整数。

服务器没有告知文件大小时,总大小 为 -1、百分比 为 0,可以改为显示已下载的字节数。

方法

取消(编号)
取消指定编号的下载,并删除已下载的部分,随后触发下载失败,原因为「已取消」。
全部取消()
取消所有正在进行的下载。
下载(URL网址,文件名)
开始下载,返回下载编号。

网址须以 http:// 或 https:// 开头。文件名 留空时从网址里取(如 .../files/说明书.pdf 取 说明书.pdf),取不到时用 download_时间戳。

平台说明

  • 安卓:使用系统下载管理。
  • 鸿蒙:使用系统下载任务,积木写法完全相同;鸿蒙不允许应用直接写公共「下载」文件夹,两种保存位置都保存到应用目录。

icon Web客户端  示例

为 HTTP GET、POST、PUT 和 DELETE 请求提供功能的非可视组件。

使用指导下载网络图片、原生表单上传文件与请求头鉴权示例查看 →

属性

允许使用Cookies
指定是否允许使用Cookies。(Cookies是一种浏览器本地缓存技术,用于缓存一些用户个性数据、身份验证信息等。常见的如“30天免登陆”功能就是将用户登录验证信息保存到Cookies,有效期30天。还有诸如你的搜索偏好,浏览偏好等设置也是通过Cookies进行保存的)
请求标头
设置请求标头。以下是一个请求标头示例截图:

请求标头

请求标头信息,格式为包含双项子列表的列表数据。其中,各子列表中第一项表示请求头的字段名,而第二项则表示对应的字段值,既可以是单个数值,也可以是包含多个数值的列表。

参考设置案例如下:

请求标头设置

常用的API请求返回json的典型设置案例如下:

请求标头设置

响应文件名称
指定保存响应数据的文件的名称,如果 保存响应信息 为真 且 响应文件名称 为空,则自动创建一个新文件名。
响应文本编码
用户指定的响应字符编码。
保存响应信息
指定是否将响应数据保存到文件中。
超时时间(ms)
返回每个请求在超时前等待响应的毫秒数,如果设置为0,则请求将无限期等待响应。
URL网址
指定待请求的URL网址.

事件

获得文件(URL网址,响应代码,响应类型,文件名)
当请求完成时触发该事件,以文件形式返回内容。
获得文本(URL网址,响应代码,响应类型,响应内容)
当请求完成时触发该事件,以文本形式返回内容。
超时(URL网址)
当请求超时触发该事件。

方法

创建数据请求(列表)
将表示名称和值对的二元素列表转换为 application/x-www-form-urlencoded 媒体类型格式的字符串,适合传递给执行POST文本请求。

参考代码块如下:

post_text

清除Cookies()
清除此 Web客户端 组件的所有 Cookies。
删除()
使用 URL网址 属性执行 HTTP DELETE 请求并获取响应数据。
执行GET请求()
使用 URL网址 属性执行 HTTP GET 请求并获取响应数据。
解码HTML文本(HTML文本)
解码给定的 HTML 文本值。例如:
HTML字符 —> 解码后文本
& &
&lt; <
&gt; >
&apos; ' (单引号)
&quot; " (双引号)
&#xhhhh; &#xhhhh;
&#nnnn; &#nnnn;
编码JSON对象(JSON对象)
以 JavaScript 对象表示形式返回内置类型(即布尔值、数字、文本、列表、字典)的值。

如果该值不能表示为 JSON,将触发屏幕的 出现错误时 事件(如果有),并且 Web 组件将返回空字符串。

解码JSON文本(JSON文本)
解码给定的 JSON 编码值以生成相应的 AppInventor 值。

返回值是一个列表/键值对列表,对应的查找方法是:在键值对中查找。

JSON 列表 [x, y, z] 解码为列表 (x y z),具有键 A 和值 B 的 JSON 对象(表示为 {A:B})解码为列表 (( A B)),即包含二元素列表(A B)的列表。

案例参考:《案例:解析天气预报结果JSON数据》、《案例:JSON转字典》。

如果你希望返回字典对象而不是结果中列表的列表,请使用方法 用字典解码JSON文本。

用字典解码JSON文本(JSON文本)
解码给定的 JSON 编码值以生成相应的 App Inventor 值。

返回值是一个字典,对应的查找方法是:获取键的值。

JSON 列表 [x, y, z] 解码为列表 (x y z),具有名称 A 和值 B 的 JSON 对象(表示为 {a: b})解码为具有键 a 和值 b 的字典。

执行PATCH文件请求(路径)
PATCH方式发送通用文件,用法类似 执行POST文件请求 。
执行PATCH文本请求(文本)
使用 URL网址 属性和指定文本执行 HTTP PATCH 请求。文本的字符集使用 UTF-8 进行编码。
执行PATCH编码文本请求(文本,字符编码)
使用 URL网址 属性和指定文本执行 HTTP PATCH 请求。文本的字符集使用指定的编码方式进行编码。
执行POST表单文件请求(路径, 文件字段名, 表单字段)
将一个文件与附加文本字段作为标准 multipart/form-data 表单发送到网址。文件字段名须与服务器要求一致,如 file 或 image;表单字段是名称和值组成的二项子列表的列表,无附加字段时传空列表。

文件名和 MIME 类型由路径推断,未知类型使用 application/octet-stream。组件负责生成分隔符;即使请求头里设置了其他 Content-Type,上传时也使用与实际表单匹配的类型。认证等其他请求头仍会发送。文件流式上传;空文件可发送,文件读取失败不会发送空请求。

根据保存响应数据设置触发获得文本或获得文件,超时沿用超时和错误事件。安卓与鸿蒙支持该方法;iOS 暂不支持。调用新方法须使用包含此方法的新版伴侣。

PHP 可通过 $_FILES['file'] 读取文件,通过 $_POST 读取附加字段。上传接口的鉴权、文件类型和大小限制仍按服务端要求配置。完整积木与 PHP 接收示例见 Web 客户端详细用法。

选图后连同标题一起上传,服务器的文件字段名是 file:

when 图像选择器1.AfterPicking() {
  Web客户端1.Url = "http://192.168.1.23:8768/upload"
  Web客户端1.PostFileWithForm(图像选择器1.Selection, "file", [["title", "我的照片"]])
}
when Web客户端1.GotText(URL网址, 响应代码, 响应类型, 响应内容) {
  标签1.Text = join(响应代码, ":", 响应内容)
}

手把手的闭环实验(电脑端接收代码、逐步验证、排错表、可下载 .aia)见 动手做:手机选图,上传到自己电脑。

执行POST文件请求(路径)
POST方式发送文件原始内容,类似 curl --data-binary @文件,可用于二进制文件上传。它不生成 multipart 表单;服务器要求表单文件字段时,请使用执行POST表单文件请求。参考代码如下:

上传文件到服务器

文件上传服务器结果如下:

文件上传服务器结果

服务器代码请参考《App Inventor 2 实现上传文件到服务器全方案总结》。

执行POST文本请求(文本)
使用 URL网址 属性和指定文本执行 HTTP POST 请求。文本的字符集使用 UTF-8 进行编码。
执行POST编码文本请求(文本,字符编码)
使用 URL网址 属性和指定文本执行 HTTP POST 请求。文本的字符集使用指定的编码方式进行编码。
执行PUT文件请求(路径)
PUT方式发送通用文件,用法类似 执行POST文件请求 。
执行PUT文本请求(文本)
使用 URL网址 属性和指定文本执行 HTTP PUT 请求。文本的字符集使用 UTF-8 进行编码。
执行PUT编码文本请求(文本,字符编码)
使用 URL网址 属性和指定文本执行 HTTP PUT 请求。文本的字符集使用指定的编码方式进行编码。
URI解码(文本)
对已编码的文本值进行URI解码操作,解码后的内容是原始的文本。如:%E6%B8%B8%20%E6%88%8F –解码–> 游 戏。
URI编码(文本)
对给定的文本进行URI编码操作,编码后可用于URL网址。如:游 戏 –编码–> %E6%B8%B8%20%E6%88%8F。
  • 空格不能用于URL网址中,需要编码成%20,中文也是一样,要编码成UTF-8格式。
解码XML文本(xml文本)
解码给定的 XML 字符串以生成列表对象。

<tag>string</tag> 解码为包含一个标签和字符串键值对的列表。

更一般地,如果 obj1, obj2, … 是标记分隔的 XML 字符串,则 <tag>obj1 obj2 ...</tag> 解码为一个列表,其中包含第一个元素是 tag 且第二个元素的对 是已解码 obj 的列表,按标签按字母顺序排序。

例如:

  • <foo>123</foo> 解码为包含一个键值对 (foo 123) 的单项列表
  • <foo>1 2 3</foo> 解码为包含一个键值对 (foo "1 2 3") 的单项列表
  • <a> <bar>456</bar> <foo>1 2 3</foo> </a> 解码为包含对 (a X) 的列表,其中 X 是一个包含 2 项的列表,分别是键值对(bar 456)和键值对(foo "1 2 3")。

如果 obj 的序列混合了标记分隔和非标记分隔的项目,则非标记分隔的项目将从序列中拉出并用“content”标记包装。

例如 <a> <bar>456</bar> many <foo>1 2 3</foo> apples<a> </code> 解码与上面类似,除了列表 X 是一个 3项 包含额外键值对的项目列表,其第一项是字符串 “content”,第二项是列表 (many, apples)。

如果结果不是格式良好的 XML,此方法会发出错误信号并返回空列表。

XML文本解码为字典(xml文本)
解码给定的 XML 字符串以生成字典对象。

该字典包括特殊键 $tag, $localName, $namespace, $namespaceUri, $attributes, 和 $content,以及指向与此处描述的结构相同的元素列表的每个节点的唯一标签。

$tag 键是完整的标签名称,例如 foo:bar。 $localName 是名称的本地部分(: 字符之后的所有内容)。如果给出了命名空间(: 字符之前的所有内容),则在$namespace中提供该命名空间,并在$namespaceUri中给出相应的 URI。 属性存储在 $attributes 的字典中,子节点以列表形式给出在 $content 下。

有关特殊Keys的更多信息

给出以下 XML 文档:

   <ex:Book xmlns:ex="http://example.com/">
     <ex:title xml:lang="en">On the Origin of Species</ex:title>
     <ex:author>Charles Darwin</ex:author>
   </ex:Book>

解析时:

  • $tag 键将是 "ex:Book"

  • $localName 键将是 "Book"

  • $namespace 键将是 "ex"

  • $namespaceUri 将是 "http://example.com/"

  • $attributes 键将是一个字典 {}(命名空间中删除了 xmlns)

  • $content 将是一个列表,包含解码后的<ex:title>和<ex:author>元素的两个项,第一项对应于 <ex:title> 元素,将有一个包含字典 {"xml:lang": "en"} 的 $attributes 键。

对于元素上的每个name=value属性,将name映射到value的键值对将存在于$attributes字典中。

除了这些特殊键之外,还有ex:title和ex:author,以允许比遍历$content列表更快的查找速度。

低功耗蓝牙(内置版)

准备真实 BLE 外设,填广播名称及固件定义的服务、通知、写入特征 UUID。名称可包含匹配,确保附近没有同名设备;通知特征需要外设支持 notify。这里用 UTF-8(utf16 为 false),外设二进制协议请改用读写字节积木。案例二的 Connected 事件替换案例一同名事件,不要重复放两个同名事件积木。

详细背景与协议案例见专题文档。以下接口按当前内置组件描述符列出,与拓展版不混用。

使用指导内置版接入步骤、连接收发案例与参数边界查看 →

属性

广播扫描周期(AdvertisementScanPeriod)
广播扫描周期:返回广播扫描周期的值(毫秒ms)。
广播者设备地址列表(AdvertiserAddresses)
广播者设备地址列表:返回在广播扫描期间找到的设备地址列表。
广播者设备名称列表(AdvertiserNames)
广播者设备名称列表:返回广播扫描期间找到的设备名称列表。
自动重连(AutoReconnect)
如果为 真,App将尝试重连已断开的设备(比如:距离过大导致的连接断开等)。注意:这不适用于通过调用 Disconnect 方法断开的连接,这类断开连接需要通过调用 Connect 或 ConnectWithAddress 进行重新连接。
电池电量(BatteryValue)
返回电池电量。
已连接设备名称(ConnectedDeviceName)
已连接设备的广播名称。如果没有连接任何设备或不支持低功耗蓝牙,则返回空字符串。
已连接设备信号强度(ConnectedDeviceRssi)
返回连接设备的 RSSI(Received Signal Strength Indicator:接收信号强度指示)。
连接超时(ConnectionTimeout)
建立连接的超时时间(单位:秒):调用 Connect 或 ConnectWithAddress 后,BluetoothLE 组件等待与设备建立连接的时间(以秒为单位),如果在给定的时间内未建立连接,则将中止尝试并触发 ConnectionFailed 事件。
设备特征列表(DeviceCharacteristics)
已连接设备所广播的每个特征对应的三元组列表,包含服务UUID、特征UUID 和特征名称(如果有)。列表格式为 ((服务 1 特征 1 名称 1) (服务 2 特征 2 名称 2) …)。如果未连接任何设备或不支持低功耗蓝牙,则将返回空列表。
设备列表(DeviceList)
以字符串形式返回BLE设备的有序列表。
设备服务列表(DeviceServices)
键值对列表,每个广播服务对应一个键值对:服务UUID 及 服务名称(如果有)。列表的格式为 ((uuid1 name1) (uuid2 name2) …)。如果没有连接任何设备或不支持低功耗蓝牙,则将返回一个空列表。
设备是否在广播(IsDeviceAdvertising)
如果设备当前正在广播,则返回 真,否则返回 假。
设备是否已连接(IsDeviceConnected)
如果BLE设备已连接,则返回 真,否则返回 假。
字符串以空字节结尾(NullTerminateStrings)
指示 BluetoothLE 组件在向连接的设备发送字符串数据时,是否以\0空字节(真)或不以\0空字节(假)结束字符串。
正在扫描(Scanning)
BLE组件的扫描状态。
发射功率(TxPower)
返回传输功率。

方法

广播数据(AdvertisementData)
参数:设备地址:文本, 服务UUID:文本。返回指定地址设备相关的广播数据。
广播者地址(AdvertiserAddress)
参数:设备名称:文本。返回指定名称的设备MAC地址。
广播者服务UUID(AdvertiserServiceUuids)
参数:设备地址:文本。返回广播设备上可用的服务列表。
特征是否可读(CanReadCharacteristic)
参数:服务UUID:文本, 特征UUID:文本。测试指定的特征是否可以读取。
特征是否可订阅(CanRegisterForCharacteristic)
参数:服务UUID:文本, 特征UUID:文本。测试指定的特征是否可用于注册通知。
特征是否可写(CanWriteCharacteristic)
参数:服务UUID:文本, 特征UUID:文本。测试指定的特征是否可以写入。
特征是否可确认写入(CanWriteCharacteristicWithResponse)
参数:服务UUID:文本, 特征UUID:文本。测试指定的特征是否可以通过设备确认进行写入。
按索引取特征(CharacteristicByIndex)
参数:索引:数字。从已连接设备支持的特征列表中返回指定索引的特征UUID,索引从 1 开始。
连接(Connect)
参数:索引:数字。使用 Connect 方法连接到设备列表中指定索引处的BLE设备。
按名称连接(ConnectMatchingName)
参数:名称:文本。扫描附近的低功耗蓝牙设备,连接第一个名字包含 name 的设备(名字只要包含即可,不必完全相同)。
连接指定类型设备(ConnectToDeviceType)
参数:设备:组件, 名称:文本。连接到使用 name 和 device 指定的已发现的正在广播的第一个设备。
按服务和名称连接(ConnectToDeviceWithServiceAndName)
参数:服务UUID:文本, 名称:文本。连接到使用 name 和 serviceUuid 指定的已发现的正在广播的第一个设备。
按地址连接(ConnectWithAddress)
参数:地址:文本。如果已知BLE设备的MAC地址(如:已存储并从微数据库中读取),则使用 ConnectWithAddress 方法连接到该设备。如果设备列表中没有任何设备与给定MAC地址匹配,则将触发 ConnectionFailed 事件。否则,如果连接成功,则将触发 Connected 事件。
断开连接(Disconnect)
如果BLE设备已连接,则断开当前的设备连接。
按地址断开(DisconnectWithAddress)
参数:地址:文本。断开指定MAC地址的已连接的BLE设备。
已发现设备地址(FoundDeviceAddress)
参数:索引:数字。获取设备列表中指定索引处设备的MAC地址。索引为BLE设备列表中的位置,从 1 开始。
已发现设备名称(FoundDeviceName)
参数:索引:数字。获取设备列表中指定索引处设备的名称。
已发现设备信号强度(FoundDeviceRssi)
参数:索引:数字。获取设备列表中指定索引处设备的信号强度(RSSI),取值在 -100 到 0 之间,越接近 0 信号越强。
获取服务的特征(GetCharacteristicsForService)
参数:服务UUID:文本。返回指定服务所支持的特征列表。该列表包含服务UUID 提供的每个特征的 (UUID, 名称) 键值对。
读字节(ReadBytes)
参数:服务UUID:文本, 特征UUID:文本, 有符号:布尔值。从连接的BLE设备中读取一个或多个 8-bit (1 字节)整型值。服务UUID和特征UUID是必需的。signed 参数指示在转换为 App Inventor数字 时是否应将字节解释为有符号值。读取字节后,将触发 BytesReceived 事件。
读取已连接设备信号强度(ReadConnectedRssi)
启动对已连接设备的接收信号强度指示 (RSSI) 的读取。结果值将通过 RssiChanged 事件中参数给出。
读浮点数(ReadFloats)
参数:服务UUID:文本, 特征UUID:文本, 半精度浮点:布尔值。从连接的BLE设备读取一个或多个 IEEE 754 浮点数。服务UUID和特征UUID是必需的。shortFloat 参数指示浮点数是 16 位半精度浮点数还是 32 位单精度浮点数。读取浮点数后,将触发 FloatsReceived 事件。
读整数(ReadIntegers)
参数:服务UUID:文本, 特征UUID:文本, 有符号:布尔值。从连接的BLE设备读取一个或多个 32-bit (4 字节)整型值。服务UUID和特征UUID是必需的。signed 参数指示在转换为 App Inventor数字 时是否应将整数解释为有符号值。读取整数后,将触发 IntegersReceived 事件。
读短整数(ReadShorts)
参数:服务UUID:文本, 特征UUID:文本, 有符号:布尔值。从连接的BLE设备读取一个或多个 16-bit (2 字节)短整型值。服务UUID和特征UUID是必需的。signed 参数指示在转换为 App Inventor数字 时是否应将 short短整型值 解释为有符号值。读取 short短整型值 后,将触发 ShortsReceived
读字符串(ReadStrings)
参数:服务UUID:文本, 特征UUID:文本, UTF16编码:布尔值。从连接的BLE设备读取一个或多个 以\0空字节结尾的字符串。服务UUID和特征UUID是必需的。utf16 参数指示在转换为 App Inventor字符串 时是否应将内容解码为 UTF-16(真)或 UTF-8(假)编码格式。读取字符串后,将触发 StringsReceived 事件。
订阅字节(RegisterForBytes)
参数:服务UUID:文本, 特征UUID:文本, 有符号:布尔值。注册用以在已连接BLE设备的一个或多个 8-bit(单字节)整型值发生变化时接收更新。服务UID 和特性UUID 是必需的。signed 参数指示在转换为 App Inventor数字 时是否应将字节解释为有符号值。每当收到更改时,将触发 BytesReceived 事件。
订阅浮点数(RegisterForFloats)
参数:服务UUID:文本, 特征UUID:文本, 半精度浮点:布尔值。注册用以在已连接BLE设备的一个或多个 IEEE 754 浮点数发生变化时接收更新。服务UID 和特性UUID 是必需的。shortFloat 参数指示浮点数是 16 位半精度浮点数还是 32 位单精度浮点数。每当收到更改时,就会触发 FloatsReceived 事件。
订阅整数(RegisterForIntegers)
参数:服务UUID:文本, 特征UUID:文本, 有符号:布尔值。注册用以在已连接BLE设备的一个或多个 32-bit (4 字节)整型值发生变化时接收更新。服务UID 和特性UUID 是必需的。signed 参数指示在将整数转换为 App Inventor数字 时是否应将其解释为有符号值。每当收到更改时,都会触发 IntegersReceived 事件。
订阅短整数(RegisterForShorts)
参数:服务UUID:文本, 特征UUID:文本, 有符号:布尔值。注册用以在已连接BLE设备的一个或多个 16-bit (2 字节)短整型值发生变化时接收更新。服务UID 和特性UUID 是必需的。signed 参数指示在转换为 App Inventor数字 时是否应将 short短整型值 解释为有符号值。每当收到更改时,就会触发 ShortsReceived 事件。
订阅字符串(RegisterForStrings)
参数:服务UUID:文本, 特征UUID:文本, UTF16编码:布尔值。注册用以在已连接BLE设备的一个或多个 以\0空字节结尾的字符串 发生更改时接收更新。服务UID 和特性UUID 是必需的。utf16 参数指示在转换为 App Inventor字符串 时是否应将内容解码为 UTF-16(真)或 UTF-8(假)编码格式。每当收到更改时,都会触发 StringsReceived 事件。
请求MTU(RequestMTU)
参数:字节数:数字。为 BluetoothLE 连接请求新的最大传输单元 (MTU)。此功能仅在两个设备都支持蓝牙 4.2 或更高版本时才受支持。如果 MTU 更改成功,则 MTUChanged 事件将被触发。默认 MTU 为 20。
扫描广播(ScanAdvertisements)
参数:扫描时长:数字。扫描广播BLE设备。
扫描指定类型设备(ScanForDevice)
参数:设备:组件。扫描特定类型的设备。设备组件必须实现 BLEDevice 接口才能使此方法正常工作。
扫描指定服务(ScanForService)
参数:服务UUID:文本。通过服务UUID扫描 广播特定BLE服务 的设备。
按索引取服务(ServiceByIndex)
参数:索引:数字。返回服务列表中给定索引处的服务UUID。
开始广播(StartAdvertising)
参数:数据:文本, 服务UUID:文本。创建并发布蓝牙低功耗广播。
开始扫描(StartScanning)
开始扫描蓝牙低功耗设备。
停止广播(StopAdvertising)
停止蓝牙低功耗广播(之前调用 StartAdvertising 的广播)。
停止扫描(StopScanning)
停止扫描蓝牙低功耗设备。
停止扫描广播(StopScanningAdvertisements)
停止扫描蓝牙低功耗广播。
支持的特征(SupportedCharacteristics)
以字符串形式返回所连接设备支持的特征列表。
支持的服务(SupportedServices)
以字符串形式返回所连接设备支持的服务列表。
取消订阅(UnregisterForValues)
参数:服务UUID:文本, 特征UUID:文本。取消注册指定的服务和特征的更新。
写字节(WriteBytes)
参数:服务UUID:文本, 特征UUID:文本, 有符号:布尔值, 值:任意类型。将一个或多个 8-bit 整数值写入已连接的BLE设备。服务UID 和特性UUID 是必需的。参数可以是 单个数值 或 数值列表。如果 signed 为真,则可接受的值介于 -128 和 127 之间。如果 signed 为假,则可接受的值介于 0 和 255 之间。
写字节并确认(WriteBytesWithResponse)
参数:服务UUID:文本, 特征UUID:文本, 有符号:布尔值, 值:任意类型。将一个或多个 8-bit 整数值写入已连接的BLE设备,并等待通过 BytesWritten 事件确认。服务UID 和特性UUID 是必需的。参数可以是 单个数值 或 数值列表。如果 signed 为真,则可接受的值介于 -128 和 127 之间。如果 signed 为假,则可接受的值介于 0 和 255 之间。
写浮点数(WriteFloats)
参数:服务UUID:文本, 特征UUID:文本, 半精度浮点:布尔值, 值:任意类型。将一个或多个 IEEE 754 浮点数写入已连接的BLE设备。服务UID 和特性UUID 是必需的。参数可以是 单个浮点值 或 浮点值列表。如果 shortFloat 为真,则每个数值将被压缩以适合 16 位半精度浮点值。如果 shortFloat 为假,则每个数值将作为 32 位单精度浮点值发送。
写浮点数并确认(WriteFloatsWithResponse)
参数:服务UUID:文本, 特征UUID:文本, 半精度浮点:布尔值, 值:任意类型。将一个或多个 IEEE 754 浮点值写入已连接的BLE设备,并等待通过 FloatsWritten 事件确认。服务UID 和特性UUID 是必需的。参数可以是 单个浮点值 或 浮点值列表。如果 shortFloat 为假,则每个数值将作为 32 位单精度浮点值发送。
写整数(WriteIntegers)
参数:服务UUID:文本, 特征UUID:文本, 有符号:布尔值, 值:任意类型。将一个或多个 32 位整型值写入已连接的BLE设备。服务UID 和特性UUID 是必需的。参数可以是 单个数值 或 数值列表。如果 signed 为真,则可接受的值介于 -2147483648 和 2147483647 之间。如果 signed 为假,则可接受的值介于 0 和 4294967295 之间。
写整数并确认(WriteIntegersWithResponse)
参数:服务UUID:文本, 特征UUID:文本, 有符号:布尔值, 值:任意类型。将一个或多个 32 位整型值写入连接的BLE设备,并等待通过 IntegersWritten 事件确认。服务UID 和特性UUID 是必需的。参数可以是 单个数值 或 数值列表。如果 signed 为真,则可接受的值介于 -2147483648 和 2147483647 之间。如果 signed 为假,则可接受的值介于 0 和 4294967295 之间。
写短整数(WriteShorts)
参数:服务UUID:文本, 特征UUID:文本, 有符号:布尔值, 值:任意类型。将一个或多个 16 位短整型值写入已连接的BLE设备。服务UID 和特性UUID 是必需的。参数可以是 单个数值 或 数值列表。如果 signed 为真,则可接受的值介于 -32768 和 32767 之间。如果 signed 为假,则可接受的值介于 0 和 65535 之间。
写短整数并确认(WriteShortsWithResponse)
参数:服务UUID:文本, 特征UUID:文本, 有符号:布尔值, 值:任意类型。将一个或多个 16 位短整型值写入连接的BLE设备,并等待通过 ShortsWritten 事件确认。服务UID 和特性UUID 是必需的。参数可以是 单个数值 或 数值列表。如果 signed 为真,则可接受的值介于 -32768 和 32767 之间。如果 signed 为假,则可接受的值介于 0 和 65535 之间。
写字符串(WriteStrings)
参数:服务UUID:文本, 特征UUID:文本, UTF16编码:布尔值, 值:任意类型。将一个或多个字符串写入已连接的BLE设备。服务UID 和特性UUID 是必需的。参数可以是 单个字符串 或 字符串列表。如果 utf16 为真,则将使用 UTF-16 小端序(little endian)编码发送字符串。如果 utf16 为假,则将使用 UTF-8 编码发送字符串。
写字符串并确认(WriteStringsWithResponse)
参数:服务UUID:文本, 特征UUID:文本, UTF16编码:布尔值, 值:任意类型。将一个或多个字符串写入已连接的BLE设备,并等待通过 StringsWritten 事件确认。服务UID 和特性UUID 是必需的。参数可以是 单个字符串 或 字符串列表。如果 utf16 为真,则将使用 UTF-16 小端序(little endian)编码发送字符串。如果 utf16 为假,则将使用 UTF-8 编码发送字符串。

事件

收到字节时(BytesReceived)
参数:服务UUID:文本, 特征UUID:文本, 字节值:列表。当从连接的蓝牙BLE设备接收到一个或多个字节值时,将触发该事件。根据上次调用 ReadBytes 或 RegisterForBytes 时给定的 serviceUuid 和 characteristicUuid 的 sign 参数,byteValues 列表将包含从 -128 到 127 (signed = true) 或 0 到 255 (signed = false) 的数字。
字节已写入时(BytesWritten)
参数:服务UUID:文本, 特征UUID:文本, 字节值:列表。当将一个或多个字节值写入连接的蓝牙设备时,将触发该事件。byteValues 将是实际写入设备的值列表。如果原始输入太长而无法放入单个传输单元(通常为 23 个字节),则情况可能会有所不同。
已连接时(Connected)
App成功连接到BLE设备后,将触发该事件。这可能是调用 Connect 或 ConnectWithAddress 的结果,或者如果在请求连接时 AutoReconnect 属性为 真,则可能是自动重新连接的结果。
连接失败时(ConnectionFailed)
参数:原因:文本。当尝试连接设备失败时,将触发该事件。如果提供了具体的失败原因,则会通过 reason 参数给出。
发现设备时(DeviceFound)
当发现新的BLE设备时,将触发该事件。
已断开时(Disconnected)
当BLE设备断开连接时,将触发该事件。这可能是由于调用 Disconnect 或 DisconnectWithAddress 引起的,或者在设备移开或重置以致发生连接丢失后引起的。
收到浮点数时(FloatsReceived)
参数:服务UUID:文本, 特征UUID:文本, 浮点值:列表。当从连接的蓝牙设备接收到一个或多个 IEEE 754 浮点值时,将触发该事件。根据上次调用 ReadFloats 或 RegisterForFloats 的 shortFloat 参数(对于给定的 serviceUuid 和 characteristicUuid),floatValues 列表
浮点数已写入时(FloatsWritten)
参数:服务UUID:文本, 特征UUID:文本, 浮点值:列表。当将一个或多个 IEEE 754 浮点值写入连接的蓝牙设备时,将触发该事件。floatValues 将是实际写入设备的值列表。如果原始输入太长而无法放入单个传输单元(通常为 11 个短浮点数或 5 个常规浮点数),则情况可能会有所不同。
收到整数时(IntegersReceived)
参数:服务UUID:文本, 特征UUID:文本, 整数值:列表。当从连接的蓝牙设备接收到一个或多个 32-bit 整型数值时,将触发该事件。根据上次调用 ReadIntegers 或 RegisterForIntegers 时给定 serviceUuid 和 characteristicUuid 的 sign 参数,intValues 列表将包含从 -2147483648 到 2147483647 (signed = true) 或 0 到 4294967296 (signed = false) 的数字。
整数已写入时(IntegersWritten)
参数:服务UUID:文本, 特征UUID:文本, 整数值:列表。当将一个或多个 32-bit 整型数值写入连接的蓝牙设备时,将触发该事件。intValues 将是实际写入设备的值列表。如果原始输入太长而无法放入单个传输单元(通常为 5 个整数),则情况可能会有所不同。
MTU变化时(MTUChanged)
参数:字节数:数字。当BLE设备将其最大传输单元 (MTU) 成功更改为不同的值时,将触发该事件。此事件为 RequestMTU 方法块调用时的响应。
信号强度变化时(RssiChanged)
参数:信号强度:数字。当发现BLE设备的 RSSI(接收信号强度指示)发生变化时触发该事件。
收到短整数时(ShortsReceived)
参数:服务UUID:文本, 特征UUID:文本, 短整数值:列表。当从连接的蓝牙设备接收到一个或多个短整型值时,将触发该事件。根据上次调用 ReadShorts 或 RegisterForShorts 时给定的 serviceUuid 和 characteristicUuid 的 sign 参数,shortValues 列表将包含从 -32768 到 32767 (signed = true) 或 0 到 65535 (signed = false) 的数字。
短整数已写入时(ShortsWritten)
参数:服务UUID:文本, 特征UUID:文本, 短整数值:列表。当将一个或多个短整数值写入连接的蓝牙设备时,将触发该事件。shortValues 将是实际写入设备的值列表。如果原始输入太长而无法放入单个传输单元(通常为 11 个短整数),则情况可能会有所不同。
收到字符串时(StringsReceived)
参数:服务UUID:文本, 特征UUID:文本, 字符串值:列表。当从连接的蓝牙设备接收到一个或多个字符串时,将触发该事件。根据上次调用 ReadStrings 或 RegisterForStrings 时给定的 serviceUuid 和 characteristicUuid 的 utf16 参数,stringValues 列表将包含 UTF-16 小端序 (utf16 = true) 或 UTF-8 解码 (utf16 = false) 字符串。字符串长度受蓝牙设备的最大传输单元 (MTU) 限制,通常为 23 个字节。
字符串已写入时(StringsWritten)
参数:服务UUID:文本, 特征UUID:文本, 字符串值:列表。当将一个或多个字符串写入连接的蓝牙设备时,将触发该事件。stringValues 将是实际写入设备的值列表。如果原始输入太长而无法放入单个传输单元(通常为 22 个字节),则情况可能会有所不同。

MQTT客户端(内置版)

准备自己有权限访问的 MQTT Broker;属性面板配置服务器、端口、协议和账号,每个设备使用不同 ClientID。两个客户端订阅相同主题,一个发布另一个应收到。内置版保留基础连接与文本/字节收发,不含拓展的遗嘱、自签名证书等高级入口。

详细背景与协议案例见专题文档。以下接口按当前内置组件描述符列出,与拓展版不混用。

使用指导内置版接入步骤、连接收发案例与参数边界查看 →

属性

服务器地址(Broker)
MQTT 服务器地址,例如 broker.emqx.io。
客户端ID(ClientID)
客户端ID,同一服务器上必须唯一,留空时每次连接自动生成随机 ID。
是否已连接(IsConnected)
是否已连接到服务器。
最近错误信息(LastErrorMessage)
最近一次出错的文字说明。
端口(Port)
服务器端口:TCP 一般 1883,SSL/TLS 一般 8883。
协议(Protocol)
连接协议:TCP(不加密)、SSL 或 TLS(加密)。
用户名(UserName)
连接 MQTT 服务器时用于身份验证的用户名,服务器不要求时留空。
密码(UserPassword)
连接 MQTT 服务器时用于身份验证的密码,服务器不要求时留空。

方法

连接(Connect)
参数:清除会话:布尔值。连接到服务器。CleanSession 为真时不保留上次会话的订阅与未收消息。
断开连接(Disconnect)
断开与服务器的连接。
发布消息(Publish)
参数:主题:文本, 消息:文本。向主题发布文本消息(QoS 0、不保留)。
发布二进制消息(PublishBytes)
参数:主题:文本, 字节列表:列表。发布一条二进制消息(保留标志为假,QoS 为 0),参数是字节列表(0~255 的数字)。例:[165, 1, 255] 发布 A5 01 FF 三个字节。拼包、校验、十六进制转字节用二进制组件;订阅方「收到消息时」的 Payload 就是字节列表。
发布消息(完整参数)(PublishEx)
参数:主题:文本, 消息:文本, 保留标志:布尔值, 服务质量:数字。向主题发布文本消息,可指定保留标志与 QoS。
订阅(Subscribe)
参数:主题:文本, 服务质量:数字。订阅主题,可用通配符 + 与 #;QoS 为 0、1、2。收到的消息在「收到消息时」事件里。
取消订阅(Unsubscribe)
参数:主题:文本。取消订阅主题。

事件

连接状态变化时(ConnectionStateChanged)
参数:新状态:数字, 状态文本:文本。连接状态变化时触发,NewState 为状态码(0 已断开、1 连接中、2 已连接、3 断开中、4 连接中断),StateString 为状态文本。
出现错误时(ErrorOccurred)
参数:操作名:文本, 错误代码:数字, 错误信息:文本。发生错误时触发:ActionName 出错的操作、ErrorCode 错误码、ErrorMessage 错误信息。
收到消息时(MessageReceived)
参数:主题:文本, 负载:列表, 消息:文本, 保留标志:布尔值, 重复标志:布尔值。收到消息。Payload 是原始字节列表(0~255 的数字),Message 是同一内容按 UTF-8 转成的文本。例:收到「OK」时 Payload 为 [79, 75]、Message 为「OK」;二进制协议交给二进制组件解析 Payload。
文档反馈