综合演示：WebSocket使用演示

文档概述

本例程演示如何在轻语言网站中使用 WS客户端 不可视组件与远程 WebSocket 服务端建立双向长连接通信。完整覆盖了 WS 连接、收发消息、错误处理与连接关闭的全流程，是轻语言中实现实时通讯、数据推送、在线协作等场景的入门示例。

💡 本演示使用公共测试服务器 wss://echo.websocket.org/，该服务器会将收到的消息原样回传（echo），便于本地无需自建服务端即可验证收发链路。

学习目标

阅读本文档后，你应当能够掌握以下内容：

不可视组件的声明与使用：变量页_Ws客户 = 创建 WS客户端()
WebSocket 连接地址的两种协议：ws://（非加密）与 wss://（加密）
WS 客户端四个核心回调：连接成功、收到消息、发生错误、连接被关闭
事件源对象 WS事件源 的使用方式（如 WS事件源.data 取消息内容）
不可视组件的命名规范（页_ 前缀表页面级变量）

涉及组件

本演示实际使用到的组件如下：

组件	名称	作用	参考文档
页面	`<页面>`	页面根容器	文档`框架基础类_页面`
绝对布局	`<绝对布局>`	父级定位容器	文档`布局类组件_绝对布局`
编辑框	`<编辑框1>`	多行显示收到的消息日志，逐行追加	文档`文本类组件_编辑框`
编辑框	`<编辑框2>`	单行输入待发送内容（提示文本占位）	文档`文本类组件_编辑框`
按钮	`<按钮1/2/3>`	分别对应连接服务器、发送消息、关闭服务器	文档`文本类组件_按钮`
WS客户端	代码中 `创建`	不可视组件，承载 WebSocket 连接与回调	文档`不可视类型组件_WS客户端`

📌 WS客户端 是不可视组件，无法在 .spldg 中以 XML 标签声明，必须在 .spl 中通过 创建 WS客户端() 动态实例化。

涉及函数与关键字

以下为本演示代码中出现的轻语言关键字与内置函数：

关键字： 变量、创建、事件 ... 结束事件

WS客户端方法：

连接(服务端地址) —— 连接 WebSocket 服务端，返回是否开始尝试连接
发送数据(数据) —— 通过已建立的连接发送文本消息
关闭() —— 主动关闭 WebSocket 连接
置连接成功回调(回调) —— 连接建立成功时触发，回调参数为 (事件源)
置收到消息回调(回调) —— 收到服务端消息时触发，回调参数为 (WS事件源)
置发生错误回调(回调) —— 连接发生异常时触发，回调参数为 (事件源)
置连接被关闭回调(回调) —— 连接被关闭时触发，回调无参数

编辑框方法：

追加文本行(文本) —— 向编辑框追加一行文本（自动换行）

调试函数：

调试输出(内容) —— 在控制台输出调试信息

程序结构与运行流程

本项目由成对的两个文件组成：

首页.spldg   ← 页面布局文件（XML 格式）
首页.spl     ← 页面逻辑文件（轻语言代码）

运行时流程如下：

浏览器打开网站 → 加载 首页 页面
框架解析 首页.spldg 构建 DOM，执行 首页.spl 中的 页面加载完毕 事件（本演示在该事件中无操作，仅作占位）
用户点击「连接服务器」→ 触发 按钮1.被单击 → 调用 页_Ws客户.连接(...) 并注册 4 个回调
连接成功后触发 置连接成功回调，控制台输出 "WS连接服务端成功"
用户在 编辑框2 输入内容后点击「发送消息」→ 触发 按钮2.被单击 → 调用 页_Ws客户.发送数据(编辑框2.内容)
服务端 echo 回消息 → 触发 置收到消息回调 → 在 编辑框1 中追加显示 WS事件源.data
用户点击「关闭服务器」→ 触发 按钮3.被单击 → 调用 页_Ws客户.关闭()，连接被关闭后触发 置连接被关闭回调

数据模型

WS 客户端的回调参数 WS事件源（或称 事件源）是浏览器原生 MessageEvent 对象，常用属性如下：

属性	类型	说明
`data`	文本/二进制	服务端发送的消息内容（文本协议时为字符串）
`origin`	文本	消息来源 URL
`timeStamp`	数值	事件创建时间戳

本演示中通过 WS事件源.data 取出消息文本并追加到 编辑框1。

程序源代码

首页.spldg

<?xml version="1.0" encoding="utf-8"?>
<页面 标题="页面标题" 宽度="500" 高度="453">
  <绝对布局 名称="根布局">
    <按钮 名称="按钮1" 左边="10" 宽度="119" 顶边="168" 高度="40" 文本="连接服务器" />
    <编辑框 名称="编辑框1" 左边="10" 顶边="9" 高度="144" 宽度="461" />
    <按钮 名称="按钮2" 宽度="119" 高度="40" 左边="352" 顶边="252" 文本="发送消息" />
    <编辑框 名称="编辑框2" 宽度="336" 高度="67" 左边="135" 顶边="168" 提示文本="请输入待发送的内容" />
    <按钮 名称="按钮3" 宽度="119" 高度="40" 左边="10" 顶边="223" 文本="关闭服务器" />
  </绝对布局>
</页面>

首页.spl

' ****************************************************************************
' 版权说明：Copyright（C） All Rights Reserved VcnStudio
' 程序版本：V1.0
' 程序作者：
' 联系信息：
' 窗口描述：默认首页。
' ****************************************************************************

' WS客户端组件为不可视组件，我们声明一个页面对象
变量 页_Ws客户 = 创建 WS客户端()

事件 页面加载完毕()
    
结束 事件

事件 按钮1.被单击(源对象,事件源)
    ' 使用公用WS服务器测试
	页_Ws客户.连接("wss://echo.websocket.org/")
    页_Ws客户.置连接成功回调(()=>{
        调试输出("WS连接服务端成功")
    })
    页_Ws客户.置收到消息回调((WS事件源)=>{
        调试输出("WS收到消息：")
        调试输出(WS事件源)
        编辑框1.追加文本行(WS事件源.data)
    })
    页_Ws客户.置发生错误回调((WS事件源)=>{
        调试输出("WS发生错误：")
        调试输出(WS事件源)
    })
    页_Ws客户.置连接被关闭回调(()=>{
        调试输出("WS连接被关闭")
    })
结束 事件

事件 按钮2.被单击(源对象,事件源)
    页_Ws客户.发送数据(编辑框2.内容)
结束 事件

事件 按钮3.被单击(源对象,事件源)
    页_Ws客户.关闭()
结束 事件

关键代码解读

1. 不可视组件的实例化方式

变量 页_Ws客户 = 创建 WS客户端()

WS客户端 是不可视组件，不能在 .spldg 中以 <WS客户端> 标签声明
必须在 .spl 顶部以 变量 声明并 创建 实例化，作用域为整个页面
命名约定：页_ 前缀表示「页面级变量」，便于与函数内局部变量（局_）和模块级变量（程_）区分

2. WebSocket 协议前缀

页_Ws客户.连接("wss://echo.websocket.org/")

ws:// 为非加密连接（类似 HTTP），适用于本地调试或无 TLS 的内网服务
wss:// 为加密连接（类似 HTTPS），适用于生产环境，需要服务端配置证书
本演示使用的 echo.websocket.org 是公共服务，会把收到的消息原样回传

3. 四个回调的注册时机

页_Ws客户.连接("wss://echo.websocket.org/")  ' ① 先发起连接
页_Ws客户.置连接成功回调(...)              ' ② 再注册回调
页_Ws客户.置收到消息回调(...)
页_Ws客户.置发生错误回调(...)
页_Ws客户.置连接被关闭回调(...)

注意：本演示先调用 连接 再注册回调。这是因为 连接 是异步的——返回后并未真正建立连接，回调注册会在连接握手完成前完成。但更稳妥的写法是先注册回调，再发起连接，避免握手过快导致回调未就绪时事件已触发。

4. 收到消息回调的事件源参数

页_Ws客户.置收到消息回调((WS事件源)=>{
    编辑框1.追加文本行(WS事件源.data)
})

回调参数名可自定义（本例为 WS事件源，区别于按钮事件的 事件源）
WS事件源.data 即服务端发来的消息内容
编辑框1.追加文本行(...) 会自动换行追加，适合做消息日志显示

5. 发送与关闭的调用条件

事件 按钮2.被单击(源对象,事件源)
    页_Ws客户.发送数据(编辑框2.内容)
结束 事件

发送数据 要求连接已处于「已连接」状态（状态码 1）
若未连接就发送，浏览器会抛出 InvalidStateError
生产环境中应先通过 取连接状态() 判断或在 UI 上禁用发送按钮

注意事项

回调注册时机：建议先调用 置...回调 再调用 连接，避免极端网络下握手过快导致事件丢失。本演示代码顺序在多数情况下可工作，但生产环境请调整为更严谨的顺序。
发送前需判断连接状态：未连接时调用 发送数据 会抛出原生异常，建议先调用 取连接状态() 判断是否为 1（已连接）。
echo.websocket.org 为公共测试服务：仅供联调使用，不保证可用性与稳定性，生产环境请部署自己的 WebSocket 服务端。
消息协议：本演示发送与接收均为文本字符串。如需发送二进制数据（如 Blob/ArrayBuffer），需在连接前设置 binaryType 属性（请参考浏览器 WebSocket 文档）。
WS客户端不可视：不要在 .spldg 中尝试声明 WS客户端，必须通过 创建 实例化。
跨域限制：WebSocket 不受同源策略限制，但仍需服务端允许你的来源 origin。

学习要点总结

知识点	关键代码	适用场景
不可视组件实例化	`变量页_Ws客户 = 创建 WS客户端()`	WS、SSE、后台任务等不可视组件
WS 连接	`页_Ws客户.连接("wss://...")`	实时通讯
连接成功回调	`置连接成功回调(回调)`	握手完成后初始化
收到消息回调	`置收到消息回调((WS事件源)=>{...})`	接收服务端推送
错误回调	`置发生错误回调(回调)`	异常处理与重连
关闭回调	`置连接被关闭回调(回调)`	断线提示与清理
发送消息	`发送数据(文本)`	客户端 → 服务端
关闭连接	`关闭()`	主动断开
事件源属性	`WS事件源.data`	取消息内容
追加文本行	`编辑框1.追加文本行(...)`	日志/消息流显示

轻语言网站开发SDK文档