通信连接组件
目录:
Activity启动器 指导
应用更新 指导
蓝牙客户端
蓝牙服务器
低功耗蓝牙
串口通信器 指导
Web客户端 指导
MQTT客户端
二进制 指导
Socket客户端 指导
WebSocket客户端 指导
下载器 指导
【UDP】 UrsAI2UDP 拓展 - UDP广播通信协议
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.MAINActivityPackage:com.android.cameraActivityClass:com.android.camera.Camera
- 执行网络搜索。 假设您要搜索的词是“vampire”(您可以随意替换自己的选择),将属性设置为:
Action:android.intent.action.WEB_SEARCHExtraKey:queryExtraValue:vampireActivityPackage:com.google.android.providers.enhancedgooglesearchActivityClass:com.google.android.providers.enhancedgooglesearch.Launcher
- 打开浏览器到指定的网页。 假设您要访问的页面是“www.fun123.cn”(您可以随意替换自己的选择),将属性设置为:
Action:android.intent.action.VIEWDataUri:http://www.fun123.cn- 调用第三方地图也可以使用这个启动器:
- 调用高德地图的uri参考地址:https://lbs.amap.com/api/uri-api/guide/mobile-web/point/#point-on-lnglat
- 调用百度地图的uri参考地址:https://lbsyun.baidu.com/index.php?title=uri/api/web
- 打开系统照相机(比照相机组件打开的界面会丰富一些)
Action:android.media.action.STILL_IMAGE_CAMERA
- 可选取多个文件(图片、音频、视频等):
Action:android.intent.action.GET_CONTENT
更多有关Activity启动器使用技巧请查看《Activity启动器如何查看并启动其他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网址)
- 读取版本文件,与本机版本号比较:有新版触发发现新版(开启内置对话框时同时弹出更新提示), 否则触发已是最新;读取失败触发更新失败。
- 下载并安装(安装包地址)
- 下载安装包,下完自动调起系统安装。安装前检查安装包与本应用包名相同且版本号更高; 未允许「安装未知应用」时先打开系统授权页,允许后回到应用自动继续安装。
蓝牙客户端
使用 蓝牙客户端 通过蓝牙将您的设备连接到其他设备。这个组件使用串行端口配置文件 (SPP) 进行通信。
如果您有兴趣使用低能耗蓝牙,请查看《App Inventor 2 低功耗蓝牙(BLE) 硬件接入、数据通信及IO控制》。
如果您希望了解经典蓝牙与BLE之间的区别,请查看《低功耗蓝牙(BLE) 和 经典蓝牙(SPP) 的区别》。
基本接入代码参考:
-
显示已配对的SPP经典蓝牙列表:

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

-
断开当前连接的设备:

-
错误处理:

-
测试demo下载:
属性
- 地址及名称
- 返回配对的蓝牙设备列表,返回的列表每个元素都是一个字符串,由设备地址、一个空格和设备的名称组成。
蓝牙设备列表为空?
你可能没有开启AI伴侣或编译后App的发现蓝牙权限,这里以AI伴侣为例,勾上即可:

需要过滤蓝牙设备列表?
- 可用状态
- 如果设备上有蓝牙功能,则返回
真,否则返回假。 - 字符编码
- 返回发送和接收文本时使用的字符集编码(如GBK,UTF-8)。
- 分隔符字节码
- 调用 ReceiveText、ReceiveSignedBytes 或 ReceiveUnsignedBytes 返回传递负数时使用的分隔符字节码。
- 错误时断开连接
- 指定 蓝牙客户端/蓝牙服务器 是否在发生错误时自动断开连接。
- 启用
- 如果启用了蓝牙,返回
真,否则返回假。 - 高位优先
- 指定发送和接收数字时是否使用最高有效位字节优先。
- 是否已连接
- 如果已建立与蓝牙设备的连接,则返回
真。 - 轮询率
- 返回蓝牙客户端配置的轮询速率值。
- 不用于定位
- 表明蓝牙不被用来确定用户位置,需安卓12或以上。
- 启用安全连接
- 指定是否启用安全连接。
事件
无
中文网注:
蓝牙客户端没有“当收到数据时”的事件(即收到服务端数据后触发的事件),只能通过定时器定期轮询接收数据,而BluetoothLE低功耗蓝牙拓展拥有这个事件。
方法
- 获取接收字节数()
- 返回输入流中可用的字节数。
- 连接(地址)
- 连接到指定地址的蓝牙设备。
连接报错? Runtime Error: Need android.permission.BLUETOOTH_CONNECT …

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

- 连接指定设备(地址,唯一编号)
- 连接到指定地址和UUID的蓝牙设备。
- 断开连接()
- 断开已连接的蓝牙设备。
- 检查设备是否配对(地址)
- 检查指定地址的蓝牙设备是否已配对。
- 接收单字节带符号数字()
- 读取带符号的 1 字节数字。
- 接收双字节带符号数字()
- 读取带符号的 2 字节数字。
- 接收四字节带符号数字()
- 读取带符号的 4 字节数字。
- 接收带符号字节数组(字节数)
- 从输入流中读取指定数量(
字节数)的带符号的字节,并将它们作为列表返回。如果
字节数为负数,则读取到分隔符字节码(分隔符字节码属性指定的)为止,分隔符字节码包含在返回的列表中。 - 接收文本(字节数)
- 从输入流中读取指定数量(
字节数)的带符号的字节,并将它们转换为文本。如果
字节数为负数,则读取到分隔符字节码(分隔符字节码属性指定的)为止。 - 接收单字节无符号数字()
- 读取一个无符号的 1 字节数字。
- 接收双字节无符号数字()
- 读取一个无符号的 2 字节数字。
- 接收四字节无符号数字()
- 读取一个无符号的 4 字节数字。
- 接收无符号字节数组(字节数)
- 从输入流中读取指定数量(
字节数)的无符号的字节,并将它们作为列表返回。如果
字节数为负数,则读取到分隔符字节码(分隔符字节码属性指定的)为止,分隔符字节码包含在返回的列表中。 - 发送单字节数字(数值)
- 将指定的
数值字符串转换成整数,并将其作为 1 个字节写入到输出流。如果
数值无法转换为整数,或转换的整数 1 个字节不够表达,将触发屏幕的 出现错误时 事件,然后方法直接返回,不会向输出流中写入任何字节。 - 发送双字节数字(数值)
- 将指定的
数值字符串转换成整数,并将其作为 2 个字节写入到输出流。如果
数值无法转换为整数,或转换的整数 2 个字节不够表达,将触发屏幕的 出现错误时 事件,然后方法直接返回,不会向输出流中写入任何字节。 - 发送四字节数字(数值)
- 将指定的
数值字符串转换成整数,并将其作为 4 个字节写入到输出流。如果
数值无法转换为整数,或转换的整数 4 个字节不够表达,将触发屏幕的 出现错误时 事件,然后方法直接返回,不会向输出流中写入任何字节。 - 发送字节数组(列表)
- 从指定列表中取出每个元素,将其转换为字符串,字符串转换成整数,并将其作为 1 个字节写入到输出流。
如果一个元素无法转换为整数,或转换的整数 1 个字节不够表达,将触发屏幕的 出现错误时 事件,然后方法直接返回,不会向输出流中写入任何字节。
- 发送文本(文本)
- 将指定文本转换为字节并将它们写入到输出流。
蓝牙服务器
使用 蓝牙服务器 组件将您的设备变成接收来自其他使用 蓝牙客户端 组件的应用程序连接的服务器。
属性
- 可用状态
- 如果设备上有蓝牙功能,则返回
真,否则返回假。 - 字符编码
- 返回发送和接收文本时使用的字符编码。
- 分隔符字节码
- 调用 ReceiveText、ReceiveSignedBytes 或 ReceiveUnsignedBytes 返回传递负数时使用的分隔符字节码。
- 启用
- 如果启用了蓝牙,返回
真,否则返回假。 - 高位优先
- 指定发送和接收数字时是否使用最高有效位字节优先。
- 接收状态
- 如果此
蓝牙服务器组件正在接受一个传入连接,则返回真。 - 连接状态
- 如果与蓝牙设备已建立连接,则返回
真。 - 启用安全连接
- 指定是否启用安全连接。
事件
- 接受连接()
- 表示已接受蓝牙连接。
中文网注:
蓝牙服务端没有“当收到数据时”的事件(即收到客户端数据后触发的事件),只能通过定时器定期轮询接收数据,而BluetoothLE低功耗蓝牙拓展拥有这个事件。
方法
- 接受连接(服务名)
- 接受使用串行端口配置文件 (SPP) 进行通信的传入连接。
- 接受与指定设备连接(服务名,唯一编号)
- 接受指定 UUID 的传入连接。
- 获取接收字节数()
- 返回输入流中可用的字节数。
- 断开连接()
- 断开当前已连接的蓝牙设备。
- 接收单字节带符号数字()
- 读取带符号的 1 字节数字。
- 接收双字节带符号数字()
- 读取带符号的 2 字节数字。
- 接收四字节带符号数字()
- 读取带符号的 4 字节数字。
- 接收带符号字节数组(字节数)
- 从输入流中读取指定数量(
字节数)的带符号的字节,并将它们作为列表返回。如果
字节数为负数,则读取到分隔符字节码(分隔符字节码属性指定的)为止,分隔符字节码包含在返回的列表中。 - 接收文本(字节数)
- 从输入流中读取指定数量(
字节数)的带符号的字节,并将它们转换为文本。如果
字节数为负数,则读取到分隔符字节码(分隔符字节码属性指定的)为止。 - 接收单字节无符号数字()
- 读取一个无符号的 1 字节数字。
- 接收双字节无符号数字()
- 读取一个无符号的 2 字节数字。
- 接收四字节无符号数字()
- 读取一个无符号的 4 字节数字。
- 接收无符号字节数组(字节数)
- 从输入流中读取指定数量(
字节数)的无符号的字节,并将它们作为列表返回。如果
字节数为负数,则读取到分隔符字节码(分隔符字节码属性指定的)为止,分隔符字节码包含在返回的列表中。 - 发送单字节数字(数值)
- 将指定的
数值字符串转换成整数,并将其作为 1 个字节写入到输出流。如果
数值无法转换为整数,或转换的整数 1 个字节不够表达,将触发屏幕的 出现错误时 事件,然后方法直接返回,不会向输出流中写入任何字节。 - 发送双字节数字(数值)
- 将指定的
数值字符串转换成整数,并将其作为 2 个字节写入到输出流。如果
数值无法转换为整数,或转换的整数 2 个字节不够表达,将触发屏幕的 出现错误时 事件,然后方法直接返回,不会向输出流中写入任何字节。 - 发送四字节数字(数值)
- 将指定的
数值字符串转换成整数,并将其作为 4 个字节写入到输出流。如果
数值无法转换为整数,或转换的整数 4 个字节不够表达,将触发屏幕的 出现错误时 事件,然后方法直接返回,不会向输出流中写入任何字节。 - 发送字节数组(列表)
- 从指定列表中取出每个元素,将其转换为字符串,字符串转换成整数,并将其作为 1 个字节写入到输出流。
如果一个元素无法转换为整数,或转换的整数 1 个字节不够表达,将触发屏幕的 出现错误时 事件,然后方法直接返回,不会向输出流中写入任何字节。
- 发送文本(文本)
- 将指定文本转换为字节并将它们写入到输出流。
- 停止接受连接()
- 停止接受传入连接。
串口通信器
串口通信组件。手机串口通信案例、接线示意与视频请参考串口通信器使用指导。
使用指导USB 串口原样收发字节;完整回显诊断、半包缓存、校验与超时案例查看 →
属性
- 波特率
- 返回当前波特率。
- 缓冲区大小
- 单次最多读取的字节数,默认 256,允许 1~8192;不是一帧的长度。可在设计器和代码块中设置。
- 是否已初始化
- 当串口已初始化时返回
真。 - 是否打开
- 当串口连接打开时返回
真。
事件
无
方法
- 关闭串口()
- 关闭串口连接。关闭成功时返回
真。 - 初始化串口()
- 初始化串口连接。
- 打开串口()
- 打开串口连接。 打开成功时返回
真。 - 读取字节()
- 读取当前到达的原始字节,返回 0~255 的列表;没有数据返回空列表,最多读取“缓冲区大小”个字节。先初始化并打开串口,不经过文本转换。半包、多包需要按协议缓存拆帧,见完整串口回显案例。
- 写入字节(字节列表)
- 将列表原样写入串口,不追加换行。可直接发送二进制组件的拼接/追加校验结果。先初始化并打开串口,发送后仍需读取设备确认;空列表不发送。
- 读取串口()
- 从串口读取数据,返回
utf-8格式的文本。(如果返回的文本是乱码,请检查发送的数据是否是utf-8编码格式文本) - 写入串口(data)
- 将给定数据写入串口。
- 写入串口并添加新行(data)
- 将给定数据写入串口,并在末尾添加一个新行。等同于:
写入串口(data + "\n")。
二进制
二进制组件:拼接字节、十六进制与文本互转、多字节整数与浮点数互转、截取与查找、累加/异或/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 数字限制),一般用不到。
Socket客户端
TCP Socket 客户端组件。
该组件用于主动连接远程 Socket 服务端,并提供文本或二进制数据的发送能力。 连接建立后会在后台线程持续监听服务端返回的数据,再通过事件把结果切回主线程抛给积木层。
Socket 客户端现已作为原生组件提供,新项目无需导入拓展;使用旧拓展的项目请先备份,再按原生组件迁移。
使用指导不可见组件,提供 TCP Socket 客户端连接、文本/二进制/文件收发功能查看 →
快速上手
- 拖一个 Socket客户端 到屏幕,属性面板填好服务器地址与端口;
- 搭下面的代码块:连上就打招呼,收到什么就显示什么。
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 拓展)的使用问题,点此参与讨论。
WebSocket客户端
WebSocket 客户端组件:连接 ws:// 或 wss://(加密)服务器,实时收发文本与二进制消息。
和 Web客户端 的「问一次答一次」不同,WebSocket 连上后一直保持连接,服务器可以随时主动推送, 适合聊天室、实时行情、订单提醒、设备状态上报等场景。和 Socket客户端(TCP)相比, 它走标准的网页端口与协议,能穿过代理和 HTTPS,服务器端几乎所有语言与云平台都直接支持。
使用指导WebSocket 客户端:连接 ws:// 或 wss:// 服务器,实时收发文本消息,适合聊天室、实时行情、设备状态推送等需要服务器主动推送的场景查看 →
快速上手
- 拖一个 WebSocket客户端 到屏幕,属性面板的 网址 填服务器地址,例如
wss://example.com/chat; - 再放一个文本输入框、一个按钮、一个标签,搭下面的代码块:打开页面就连接,点按钮发送,收到的消息接在标签后面显示。
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 及以上生效,更低版本由系统默认维持连接。
下载器
下载器组件:把网上的文件下载保存到手机,可以同时下载多个,随时报告进度,下载完成后给出文件路径。
下载由系统负责,切到后台、锁屏都不会中断,还可以在通知栏显示进度。下载完成拿到的文件路径可以直接交给 图像、音频播放器、视频播放器 等组件使用。 如果只是请求接口拿数据,用 Web客户端;更新自己的应用安装包,用应用更新。
使用指导下载器:下载网上的文件并保存到手机,可同时下载多个,报告下载进度,完成后给出文件路径查看 →
快速上手
- 拖一个 下载器、一个按钮、一个标签、一个图像到屏幕;
- 搭下面的代码块:点按钮开始下载,标签显示进度,下完把图片显示出来。
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_时间戳。
平台说明
- 安卓:使用系统下载管理。
- 鸿蒙:使用系统下载任务,积木写法完全相同;鸿蒙不允许应用直接写公共「下载」文件夹,两种保存位置都保存到应用目录。
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文本请求。参考代码块如下:

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