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

Socket客户端使用指导

• Socket客户端使用指导
  • 快速上手
  • 搭建与测试
  • 案例：主动连接与断开
  • 属性、方法与事件速查
  • 常见问题与验收
  • 完整 .aia 源码与操作指导
    • TCP通信
  • 电脑端完整代码
  • 反复连接与断开

TCP Socket 客户端组件。

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

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），方便服务端按行读取。

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

搭建与测试

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

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

案例：主动连接与断开

放连接、断开按钮和标签，属性面板配置真实 TCP 服务器地址与端口。该服务器必须接受原始 TCP，不能填 WebSocket 网址。

when 按钮_连接.Click() {
  Socket客户端1.Connect()
}
when 按钮_断开.Click() {
  Socket客户端1.Disconnect()
}
when Socket客户端1.Disconnected() {
  标签1.Text = "连接已断开"
}

TCP 接收块不保证恰好是一条业务消息；协议应规定换行、固定长度或长度前缀，应用按协议拼接拆分。

属性、方法与事件速查

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

常见问题与验收

完整 .aia 源码与操作指导

下载 .aia 源码

需要手机与电脑在同一局域网，先运行随页提供的TCP回显服务。所有收发用实际Socket；TCP没有消息边界，一次发送可能分多次接收，本页展示每次真实字节片段，不把一个接收事件当成整帧。测试文件在应用私有目录创建。

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

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

TCP通信

导入方法：项目 → 导入项目（.aia）→ 选择下载的 .aia 源码文件。 需要手机与电脑在同一局域网，先运行随页提供的TCP回显服务。所有收发用实际Socket；TCP没有消息边界，一次发送可能分多次接收，本页展示每次真实字节片段，不把一个接收事件当成整帧。测试文件在应用私有目录创建。 覆盖检查 24/24。首次载入及保存重开均0个错误，真实后台导入、安装包编译通过；真机／伴侣／硬件联调尚未实测。全部属性读写、方法与事件的操作入口和预期结果见组件指导。

电脑端完整代码

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

python3 tcp-peer.py

#!/usr/bin/env python3
"""实际TCP回显对端：接收文本、二进制和文件原始字节；CLOSE换行请求关闭。"""
import socketserver

class 回显处理器(socketserver.BaseRequestHandler):
    def handle(self):
        print("连接：", self.client_address, flush=True)
        尾部 = b""
        while True:
            数据 = self.request.recv(65536)
            if not 数据:
                return
            if b"CLOSE\n" in 尾部 + 数据:
                print("按客户端请求关闭", flush=True)
                return
            尾部 = (尾部 + 数据)[-5:]
            print("收到", len(数据), "字节：", 数据.hex(" ").upper(), flush=True)
            self.request.sendall(数据)

class 回显服务(socketserver.ThreadingTCPServer):
    allow_reuse_address = True
    daemon_threads = True

if __name__ == "__main__":
    with 回显服务(("0.0.0.0", 8766), 回显处理器) as 服务:
        print("TCP已监听8766；手机填写电脑局域网IP，Ctrl+C结束。", flush=True)
        try:
            服务.serve_forever()
        except KeyboardInterrupt:
            pass

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

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

反复连接与断开

Disconnect 在后台关闭连接。不要在同一个按钮事件里紧接着执行 Connect；等 Disconnected 后再连接。连接中或已经连接时重复调用 Connect 会报错，并不会建立第二条连接。

重连时应允许发送按钮在新的 Connected 之后才可用；服务器主动关闭时等待 RemoteConnectionClosed，再由用户重试。当前本机测试覆盖同一客户端连续10轮断开重连，以及远端关闭后的重连收发；这些结果不替代旧版第三方扩展或手机运行验证。