组件：WS客户端

WS客户端组件是一个不可视组件，用于在轻语言应用中建立 WebSocket 连接，实现与服务器的全双工实时通信。它不依赖于任何 UI 元素，仅提供一系列方法用于连接、发送、接收和关闭 WebSocket 连接。适用于实时消息推送、在线聊天、数据监控、协同编辑等需要长连接通信的场景。

典型使用场景：

  • 实时聊天应用（即时通讯、客服系统）
  • 数据推送（股票行情、体育比分、系统通知）
  • 在线协作（多人文档编辑、白板同步）
  • 游戏服务器通信（实时对战、状态同步）
  • 物联网设备控制（远程指令下发、状态上报）

快速索引

你想知道什么直接看这里
如何连接 WebSocket 服务器连接(服务端地址)
如何发送消息发送数据(数据)
如何关闭连接关闭()
如何获取连接状态取连接状态()
如何监听连接成功置连接成功回调(回调函数)
如何接收消息置收到消息回调(回调函数)
如何监听连接关闭置连接被关闭回调(回调函数)
如何监听错误置发生错误回调(回调函数)
连接状态码含义见下方“连接状态详解”

基础示例

最简单的 WebSocket 使用流程：连接服务器 → 发送消息 → 接收消息 → 关闭连接。

变量 ws = 创建 WS客户端()

' 1. 设置事件回调（需在连接前设置）
ws.置连接成功回调((事件源) => {
    调试输出("WebSocket 连接成功")
    ' 连接成功后发送一条消息
    ws.发送数据("Hello Server!")
})

ws.置收到消息回调((事件源) => {
    ' 事件源中包含了收到的消息数据
    变量 消息 = 事件源.data
    调试输出("收到服务器消息：" + 消息)
})

ws.置连接被关闭回调((事件源) => {
    调试输出("WebSocket 连接已关闭")
})

ws.置发生错误回调((事件源) => {
    调试输出("WebSocket 错误：" + 事件源.message)
})

' 2. 发起连接
变量 结果 = ws.连接("ws://localhost:8080/ws")
如果(结果 == 假)
    调试输出("浏览器不支持 WebSocket 或连接失败")
结束 如果

' 3. 后续操作（例如在延时后关闭）
延时执行(() => {
    ws.关闭()
}, 10000)

综合示例：实时聊天客户端

本示例模拟一个简单的聊天室客户端，包含连接、发送消息、接收消息、显示在线状态等功能。

' ========== 创建 WebSocket 客户端 ==========
变量 ws = 创建 WS客户端()

' ========== 设置事件回调 ==========
' 连接成功
ws.置连接成功回调((事件源) => {
    调试输出("✅ 连接成功")
    弹出提示("已连接到聊天服务器")
    ' 发送登录消息（假设服务器需要认证）
    变量 登录数据 = JSON编码({ type: "login", username: "张三" })
    ws.发送数据(登录数据)
})

' 收到消息
ws.置收到消息回调((事件源) => {
    变量 数据 = 事件源.data
    调试输出("📨 收到消息：" + 数据)
    ' 尝试解析为 JSON
    尝试
        变量 消息对象 = JSON解析(数据)
        如果(消息对象.类型 == "message")
            显示聊天消息(消息对象.用户名, 消息对象.内容)
        否则 如果(消息对象.类型 == "online")
            更新在线列表(消息对象.用户列表)
        结束 如果
    捕获 异常
        ' 非 JSON 消息直接显示
        显示聊天消息("系统", 数据)
    结束 尝试
})

' 连接关闭
ws.置连接被关闭回调((事件源) => {
    调试输出("🔌 连接已关闭")
    弹出提示("与服务器的连接已断开")
    ' 可在此尝试自动重连
})

' 发生错误
ws.置发生错误回调((事件源) => {
    调试输出("❌ 发生错误：" + 事件源.message)
    弹出提示("WebSocket 错误，请检查网络")
})

' ========== 连接服务器 ==========
变量 服务器地址 = "ws://chat.example.com:8080/ws"
如果(ws.连接(服务器地址) == 假)
    弹出提示("浏览器不支持 WebSocket 或地址无效")
结束 如果

' ========== 发送消息函数 ==========
函数 发送聊天消息(内容)
    如果(ws.取连接状态() != 1)  ' 1 表示已连接
        弹出提示("未连接到服务器")
        返回
    结束 如果
    变量 消息对象 = { type: "message", content: 内容 }
    ws.发送数据(JSON编码(消息对象))
结束 函数

' ========== 模拟发送一条消息 ==========
延时执行(() => {
    发送聊天消息("大家好，我是新来的！")
}, 2000)

' ========== 显示消息函数（示例） ==========
函数 显示聊天消息(用户名, 内容)
    ' 实际开发中可在此更新 UI，例如添加标签到聊天列表
    调试输出(用户名 + "：" + 内容)
结束 函数

函数 更新在线列表(用户列表)
    调试输出("当前在线用户：" + 数组到文本(用户列表, ", "))
结束 函数

' ========== 在页面关闭时断开连接 ==========
事件 页面被关闭()
    ws.关闭()
结束 事件

函数详解

连接(服务端地址)

  • 功能： 尝试建立与指定 WebSocket 服务器的连接。
  • 参数： 服务端地址（文本型），支持两种格式：
    • ws:// 开头（非加密连接），例如 "ws://127.0.0.1:8080/path"
    • wss:// 开头（加密连接，类似 HTTPS），例如 "wss://example.com:443/wss"
  • 返回值： 逻辑型，真 表示浏览器支持 WebSocket 且连接请求已发起（但不代表连接成功）；假 表示浏览器不支持 WebSocket 或地址格式错误。
  • 注意： 连接结果需通过 置连接成功回调 和 置发生错误回调 来监听。
  • 示例： ws.连接("ws://localhost:8080/ws")

发送数据(数据)

  • 功能： 通过已建立的 WebSocket 连接向服务器发送文本数据。
  • 参数： 数据（文本型），要发送的字符串内容（可以是纯文本或 JSON 字符串）。
  • 返回值： 无。
  • 注意： 仅在连接状态为 1（已连接）时发送才有效，否则会静默失败或报错（取决于浏览器实现）。
  • 示例： ws.发送数据("Hello")

关闭()

  • 功能： 主动关闭 WebSocket 连接，释放资源。关闭后会触发 置连接被关闭回调。
  • 返回值： 无。
  • 示例： ws.关闭()

取连接状态()

  • 功能： 获取当前连接状态码。
  • 返回值： 数值型，可能的取值及含义：
    • 0：正在连接（Connecting）
    • 1：已连接（Open）
    • 2：正在关闭（Closing）
    • 3：已关闭（Closed）
  • 示例： 如果(ws.取连接状态() == 1) 调试输出("连接正常")

回调设置函数

所有回调函数必须在调用 连接() 之前设置，否则可能错过连接成功等早期事件。

置连接成功回调(回调函数)

  • 功能： 设置连接成功时的回调函数。
  • 参数： 回调函数，格式为 (事件源) => { ... }，其中 事件源 是原生 WebSocket 事件对象，包含连接相关信息。
  • 示例： 
    ws.置连接成功回调((事件源) => {
    调试输出("连接成功，协议：" + 事件源.target.protocol)
})

置收到消息回调(回调函数)

  • 功能： 设置接收到服务器消息时的回调函数。
  • 参数： 回调函数，格式为 (事件源) => { ... }，事件源.data 为接收到的消息内容（文本字符串）。
  • 示例： 
    ws.置收到消息回调((事件源) => {
    变量 消息 = 事件源.data
    调试输出("收到：" + 消息)
})

置连接被关闭回调(回调函数)

  • 功能： 设置连接被关闭时的回调函数（包括主动关闭、服务器关闭、网络异常等）。
  • 参数： 回调函数，格式为 (事件源) => { ... }，事件源 包含关闭码（code）和关闭原因（reason）。
  • 示例： 
    ws.置连接被关闭回调((事件源) => {
    调试输出("关闭码：" + 事件源.code + "，原因：" + 事件源.reason)
})

置发生错误回调(回调函数)

  • 功能： 设置发生错误时的回调函数（例如连接失败、网络中断、数据格式错误等）。
  • 参数： 回调函数，格式为 (事件源) => { ... }，事件源.message 包含错误描述。
  • 示例： 
    ws.置发生错误回调((事件源) => {
    调试输出("错误：" + 事件源.message)
})

事件说明

WS客户端组件的事件与上述回调函数一一对应，适用于在 .spldg 设计文件中使用 VB6 风格事件绑定（但通常不可视组件较少使用设计文件，建议直接使用回调函数）。

事件对应回调触发时机
连接成功(事件源)置连接成功回调WebSocket 连接成功建立
收到消息(事件源)置收到消息回调接收到服务器消息
连接被关闭(事件源)置连接被关闭回调连接被关闭（任何原因）
发生错误(事件源)置发生错误回调发生错误（如连接失败）

⚠️ 注意事项

  1. 回调设置顺序：所有回调函数应在调用 连接() 之前设置，否则可能错过连接成功等事件。
  2. 连接状态检查：发送消息前建议通过 取连接状态() 检查是否为 1（已连接），避免发送失败。
  3. 消息格式：发送数据() 仅支持文本字符串，如需发送二进制数据（如文件、图片），需先进行 Base64 或 ArrayBuffer 编码（目前版本可能不支持，需查阅更新）。
  4. 自动重连：组件本身不提供自动重连机制，可在 置连接被关闭回调 或 置发生错误回调 中手动实现重连逻辑（注意延迟和次数限制）。
  5. 安全性：生产环境建议使用 wss:// 加密连接，防止数据被窃听。
  6. 心跳保活：部分服务器要求客户端定期发送心跳包（如 Ping/Pong），可在 置连接成功回调 中启动定时器，定期发送心跳数据。
  7. 同源策略：WebSocket 不受同源策略限制，但服务器需支持跨域 WebSocket 连接（通过 Origin 头验证）。
  8. 资源释放：在页面关闭或组件销毁时，应主动调用 关闭() 释放连接资源，避免内存泄漏。
  9. 浏览器兼容性：WebSocket 在现代浏览器中广泛支持，但 IE 等旧浏览器不支持，可通过 连接() 返回值判断。
  10. 错误处理：务必设置 置发生错误回调，否则连接失败时可能无提示，导致用户困惑。

相关文档

  • 文档不可视类型组件_SSE —— Server-Sent Events 单向推送
  • 文档不可视类型组件_后台任务 —— Web Worker 多线程
  • 文档轻语言网站：发送网络请求与接口请求 —— HTTP 请求
  • 文档轻语言网站：轻语言语法速查 —— 拉姆达表达式、JSON 操作等