← 返回WebSocket客户端组件参考 · 全部使用指导

WebSocket客户端使用指导

• WebSocket客户端使用指导
  • 快速上手
  • 搭建与测试
  • 属性、方法与事件速查
  • 常见问题与验收
  • 完整 .aia 源码与操作指导
    • WebSocket通信
  • 电脑端完整代码

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

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

快速上手

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(字节列表)
}

搭建与测试

在设计器拖入本组件和案例涉及的按钮、标签、布局等组件，按案例中的名称重命名。先运行最小案例，确认事件返回，再增加业务逻辑。示例中的素材先上传到项目，服务器地址、令牌、文件路径换成自己的值。

可见组件需要有非零宽高；不可见工具组件必须由属性或方法启动。设计器展示样式不等于运行时已加载数据或绑定目标。联机测试应使用包含本组件的 AI 伴侣；涉及系统入口或权限的行为还要编译安装后验证。

属性、方法与事件速查

完整参数类型、默认值和平台说明见组件参考。下表按调用入口列出用途；有完成事件的方法在事件中读取结果。

常见问题与验收

完整 .aia 源码与操作指导

下载 .aia 源码

手机与电脑在同一局域网；先运行随页提供的Python WebSocket对端。文本和二进制帧分开回显，接收事件显示真实数据。局域网测试使用ws，实际服务按协议配置wss和证书。

导入 WebSocketAllFeatures.aia，连接最新伴侣，或编译独立安装包。真机／伴侣运行尚未实测。

所有返回值均用于界面反馈，错误由底部错误区展示。设计器采用明确非默认配置，初始化与界面同步。API 覆盖检查按最终 AIA 检查方法、事件、属性读取与设置及设计器配置，不能替代真实设备验证。

WebSocket通信

导入方法：项目 → 导入项目（.aia）→ 选择下载的 .aia 源码文件。 手机与电脑在同一局域网；先运行随页提供的Python WebSocket对端。文本和二进制帧分开回显，接收事件显示真实数据。局域网测试使用ws，实际服务按协议配置wss和证书。 覆盖检查 16/16。首次载入及保存重开均0个错误，真实后台导入、安装包编译通过；真机／伴侣／硬件联调尚未实测。全部属性读写、方法与事件的操作入口和预期结果见组件指导。

电脑端完整代码

手机与电脑连接同一个局域网，把下面代码保存为 websocket-peer.py。启动命令如下（Windows把 .venv/bin/python 改为 .venv\Scripts\python.exe）：

python3 -m venv .venv
.venv/bin/python -m pip install websockets
.venv/bin/python websocket-peer.py

#!/usr/bin/env python3
"""实际WebSocket回显对端：保留文本／二进制类型，并支持正常关闭。"""
import asyncio
from websockets.asyncio.server import serve

async def 回显(连接):
    async for 消息 in 连接:
        if isinstance(消息, str) and 消息 == "CLOSE":
            await 连接.close(code=1000, reason="按客户端请求关闭")
            return
        print("文本：" if isinstance(消息, str) else "二进制：", 消息, flush=True)
        await 连接.send(消息)

async def 主程序():
    async with serve(回显, "0.0.0.0", 8767) as 服务:
        print("WebSocket已监听8767；手机填ws://电脑IP:8767，Ctrl+C结束。", flush=True)
        await 服务.serve_forever()

if __name__ == "__main__":
    try:
        asyncio.run(主程序())
    except KeyboardInterrupt:
        pass

电脑监听地址 0.0.0.0 表示接受局域网连接；手机连接地址必须是电脑实际局域网IP，不是 0.0.0.0 或手机自己的 127.0.0.1。允许本机防火墙对应TCP端口。若失败先核对服务终端和两端网络，修正后再连接。

电脑脚本本机协议回显检查见案例验证记录；手机硬件与真实网络尚未联调。

对端使用官方的 asyncio 服务入口，参考 websockets 官方入门文档。