SocketClient

SocketClient 表示客户端侧的 WebSocket 连接（由你的运行时在 JS 中发起到远端服务的连接）。通过它你可以主动连接、监听事件、发送文本或二进制数据，并在断线时做清理或重连。

下面是 SocketClient 的完整说明（与 SocketServer 文档风格一致）。

构造函数

const wsCli = new SocketClient(options)

参数：options

字段	类型	必填	说明
`url`	`string`	是	目标 WebSocket 地址，支持 `ws://` / `wss://`，可携带查询参数
`header`	`Record<string,string>`	否	自定义请求头（如鉴权 Token 等）
`subprotocols`	`string[]`	否	WebSocket 子协议列表（如 `["chat.v1","json.v1"]`）
`timeout`	`number`	否	连接超时时间（毫秒）
`handshakeTimeout`	`number`	否	握手阶段超时时间（毫秒）
`pingInterval`	`number`	否	心跳发送间隔（毫秒），如由运行时内置则可省略

方法与事件总览

名称	类型	参数	返回值	说明
`on`	方法	`eventName:string, callback(...args))`	`void`	监听 `open` / `message` / `error` / `close`
`send`	方法	`data: string \| Uint8Array \| ArrayBuffer \| byte[]`	`void`	发送文本或二进制数据
`close`	方法	—	`void`	主动关闭连接

on

使用 on 监听 4 类事件：open、message、error、close。

事件说明

on("open", callback()) 连接建立完成（握手成功）时触发。
on("message", callback(data, messageType)) 收到服务器消息时触发。
- data：消息内容；文本为 string，二进制为 Buffer/Uint8Array/ArrayBuffer（取决于 binaryType 和运行时）
- messageType："text" | "binary"（某些实现也可能是数值枚举 1/2）
on("error", callback(error)) 连接或收发过程出现错误时触发。
- error：错误对象或错误信息
on("close", callback()) 连接关闭时触发（远端关闭或本地 close()）。

示例

const wsCli = new SocketClient({url: "wss://example.com/ws?token=xxx"});

wsCli.on("open", () => {
    console.log("[Client] 连接已建立");
});

wsCli.on("message", (data, messageType) => {
    if (messageType === "text") {
        console.log("收到文本：", data);
    } else {
        console.log("收到二进制：", data.byteLength || data.length, "bytes");
    }
});

wsCli.on("error", (err) => {
    console.error("[Client] 发生错误：", err);
});

wsCli.on("close", () => {
    console.log("[Client] 连接已关闭");
});

send

说明

send(data)：向服务端发送一条消息；data 可为字符串（文本）或二进制（Uint8Array/ArrayBuffer/Buffer）。

建议：发送 JSON 时先 JSON.stringify；发送音频/文件片段等数据时使用二进制。

示例（文本与二进制）

// 文本
wsCli.send(JSON.stringify({event: "login", data: {user: "susu"}}));

// 二进制（例如音频帧）
const pcm = new Uint8Array(320); // mock
wsCli.send(pcm);

close

说明

close()：主动关闭连接；会随后触发 close 事件。

示例

wsCli.on("error", (e) => {
    console.error("client error:", e);
    wsCli.close(); // 出错时主动收尾，防资源泄漏
});

生命周期说明（Client）

连接阶段：构造 SocketClient 并开始握手；成功后触发 open。
通信阶段：使用 send() 发送消息；用 on("message") 接收服务端推送或响应。
异常阶段：网络抖动、鉴权失败、协议错误等会触发 error。
关闭阶段：远端关闭或本地 close()，触发 close，完成清理。

实践建议：在 error/close 中做清理（停止定时器、关闭文件句柄、释放缓存）；如需自动重连，可在 close 中发起新的 SocketClient（避免递归重连过快，可加入退避策略）。

SocketClient

ON THIS PAGE