Scripting
文档
更新日志
隐私
文档
更新日志
隐私
简体中文

WebSocketSession（WebSocket 会话） PRO

需要 Scripting PRO

WebSocketSession 类表示一个已建立的 WebSocket 连接会话。 它由服务器端的 HttpServer.registerWebsocket() 注册的处理函数自动创建，用于与客户端进行双向实时通信。

概述

通过 WebSocketSession，你可以：

  • 接收客户端发送的文本或二进制数据；
  • 向客户端发送消息（文本或二进制）；
  • 处理连接的建立与断开事件；
  • 关闭连接会话。

WebSocketSession 通常由 WebSocket 事件回调函数接收，如 onConnected、handleText、handleBinary 等。

使用场景

  • 构建实时聊天、协作或通知系统；
  • 实现实时状态同步或设备控制；
  • 处理自定义协议的二进制数据通信；
  • 构建本地 WebSocket 服务，与其他设备或网页通信。

方法

writeText(text: string): void

向客户端发送一条文本消息。

参数：

参数名 类型 说明
text string 要发送的文本内容。

示例：

1server.registerWebsocket("/chat", {
2  onConnected: (session) => {
3    session.writeText("Welcome to the chat room!")
4  },
5  handleText: (session, text) => {
6    console.log("Client says:", text)
7    session.writeText("You said: " + text)
8  }
9})

writeData(data: Data): void

向客户端发送一条二进制消息。

参数：

参数名 类型 说明
data Data 要发送的二进制数据对象。

示例：

1server.registerWebsocket("/binary", {
2  onConnected: (session) => {
3    const msg = Data.fromRawString("Binary hello", "utf-8")
4    session.writeData(msg)
5  }
6})

close(): void

关闭当前 WebSocket 会话连接。

调用后，连接会断开，且不再触发任何接收事件。

示例：

1server.registerWebsocket("/ws", {
2  handleText: (session, text) => {
3    if (text === "bye") {
4      session.writeText("Goodbye!")
5      session.close()
6    }
7  }
8})

与 HttpServer.registerWebsocket() 的配合使用

WebSocketSession 实例通过 registerWebsocket() 注册的事件回调函数获得。

注册示例

1const connectedSessions: WebSocketSession[] = []
2
3server.registerWebsocket("/ws", {
4  onConnected: (session) => {
5    connectedSessions.push(session)
6    console.log("Client connected")
7    session.writeText("Connection established!")
8  },
9  handleText: (session, text) => {
10    console.log("Received:", text)
11    // 广播消息给所有连接的客户端
12    for (const s of connectedSessions) {
13      s.writeText("Broadcast: " + text)
14    }
15  },
16  handleBinary: (session, data) => {
17    console.log("Received binary data:", data.length)
18  },
19  onDisconnected: (session) => {
20    const index = connectedSessions.indexOf(session)
21    if (index !== -1) connectedSessions.splice(index, 1)
22    console.log("Client disconnected")
23  }
24})

常用事件回调（由 HttpServer 提供）

回调函数 触发时机 参数 说明
onConnected 客户端成功建立连接时 (session: WebSocketSession) 创建新的会话对象。
onDisconnected 客户端断开连接时 (session: WebSocketSession) 会话结束。
onPong 收到客户端 Ping/Pong 响应时 (session: WebSocketSession) 用于检测连接健康状态。
handleText 收到文本消息时 (session: WebSocketSession, text: string) 处理文本通信。
handleBinary 收到二进制数据时 (session: WebSocketSession, data: Data) 处理二进制通信。

示例：构建简单的实时聊天室

1const sessions: WebSocketSession[] = []
2
3server.registerWebsocket("/chat", {
4  onConnected: (session) => {
5    sessions.push(session)
6    session.writeText("Welcome! There are " + sessions.length + " users online.")
7  },
8  handleText: (session, text) => {
9    for (const s of sessions) {
10      s.writeText(text) // 广播消息
11    }
12  },
13  onDisconnected: (session) => {
14    const index = sessions.indexOf(session)
15    if (index !== -1) sessions.splice(index, 1)
16  }
17})

客户端通过 JavaScript 连接：

1const ws = new WebSocket("ws://localhost:8080/chat")
2ws.onmessage = e => console.log("Server:", e.data)
3ws.send("Hello everyone!")

类型定义

1class WebSocketSession {
2  writeText(text: string): void
3  writeData(data: Data): void
4  close(): void
5}

总结

方法 说明 使用场景
writeText() 向客户端发送文本消息 聊天、通知、状态同步
writeData() 发送二进制数据 文件传输、实时流、设备数据
close() 关闭连接 主动断开连接或清理资源
大纲