Scripting
开始
文档
更新日志
开始
文档
更新日志
简体中文

WebScoket

WebSocket 类提供了创建和管理 WebSocket 连接的接口，允许与服务器进行实时通信。你可以通过 WebSocket 连接发送和接收文本和二进制数据，包括字节缓冲区。

概述

WebSocket 是一种通信协议，允许客户端与服务器之间进行全双工通信。这使其非常适用于实时应用程序，如即时消息、通知或数据流。

类：WebSocket

构造函数

new WebSocket(url: string)

创建一个新的 WebSocket 连接到指定的 URL，并立即尝试建立连接。

  • 参数：

    • url: string：要连接的 WebSocket 服务器 URL。示例："ws://example.com/socket" 或 "wss://example.com/socket"（对于安全的 WebSocket 连接）。

  • 返回：一个表示连接的 WebSocket 对象。

属性

  • url: string
    WebSocket 连接的 URL。此属性为只读。

  • onopen?: () => void
    可选的回调函数，当 WebSocket 连接成功建立时触发。

  • onerror?: (error: Error) => void
    可选的回调函数，当 WebSocket 连接或通信发生错误时触发。

  • onmessage?: (message: string | Data) => void
    可选的回调函数，当从 WebSocket 服务器接收到消息时触发。message 参数可以是字符串或二进制数据（由 Data 类表示）。

  • onclose?: (reason?: string) => void
    可选的回调函数，当 WebSocket 连接关闭时触发。reason 参数提供了关闭连接的可选解释。

方法

send(message: string | Data): void

通过 WebSocket 连接向服务器发送数据。

  • 参数：

    • message: string | Data：要发送到服务器的数据。可以是字符串或 Data 类的实例。

  • 返回：void

close(code?: 1000 | 1001 | 1002 | 1003, reason?: string): void

关闭 WebSocket 连接。如果连接已经关闭，则此方法不执行任何操作。

  • 参数：

    • code?: 1000 | 1001 | 1002 | 1003：可选的 WebSocket 连接关闭代码。常见的代码包括：
      • 1000：正常关闭
      • 1001：离开
      • 1002：协议错误
      • 1003：不支持的数据类型
    • reason?: string：可选的关闭连接原因。此字符串的长度不得超过 123 字节（UTF-8 编码）。

  • 返回：void

事件处理

你可以使用 addEventListener 来监听 WebSocket 事件，并使用 removeEventListener 来移除事件监听器。

addEventListener(event: "open", listener: () => void): void

为 "open" 事件添加事件监听器，该事件在 WebSocket 连接建立时触发。

addEventListener(event: "error", listener: (error: Error) => void): void

为 "error" 事件添加事件监听器，该事件在 WebSocket 连接发生错误时触发。

addEventListener(event: "message", listener: (message: string | Data) => void): void

为 "message" 事件添加事件监听器，该事件在从 WebSocket 服务器接收到消息时触发。

addEventListener(event: "close", listener: (reason?: string) => void): void

为 "close" 事件添加事件监听器，该事件在 WebSocket 连接关闭时触发。

removeEventListener(event: "open", listener: () => void): void

移除 "open" 事件的事件监听器。

removeEventListener(event: "error", listener: (error: Error) => void): void

移除 "error" 事件的事件监听器。

removeEventListener(event: "message", listener: (message: string | Data) => void): void

移除 "message" 事件的事件监听器。

removeEventListener(event: "close", listener: (reason?: string) => void): void

移除 "close" 事件的事件监听器。

示例使用

建立 WebSocket 连接

1const ws = new WebSocket("wss://example.com/socket")
2
3// 设置事件监听器
4ws.addEventListener("open", () => {
5  console.log("连接已建立！")
6  ws.send("你好，服务器！")
7})
8
9ws.addEventListener("message", (message) => {
10  console.log("接收到消息：", message)
11})
12
13ws.addEventListener("error", (error) => {
14  console.log("WebSocket 错误：", error)
15})
16
17ws.addEventListener("close", (reason) => {
18  console.log("连接已关闭：", reason)
19})

发送字符串消息

1const ws = new WebSocket("wss://example.com/socket")
2
3ws.addEventListener("open", () => {
4  ws.send("你好，这是测试消息！")
5})

使用 Data 发送二进制数据

1const ws = new WebSocket("wss://example.com/socket")
2
3ws.addEventListener("open", () => {
4  const data = Data.fromString("一些消息")
5  ws.send(data) // 发送二进制数据
6})

处理二进制数据

1const ws = new WebSocket("wss://example.com/socket")
2
3ws.addEventListener("message", (message) => {
4  if (message instanceof Data) {
5    const byteArray = message.getBytes()
6    if (byteArray) {
7      console.log("接收到的二进制数据：", byteArray)
8    }
9  }
10})

关闭 WebSocket 连接

1const ws = new WebSocket("wss://example.com/socket")
2
3ws.addEventListener("open", () => {
4  console.log("连接已建立！")
5  // 使用自定义原因关闭连接
6  ws.close(1000, "测试后关闭连接")
7})

注意事项

  • send() 方法可以处理文本和二进制数据。对于二进制数据，你可以使用 Data 类来处理字节缓冲区。
  • 对于二进制数据，请确保你的 WebSocket 服务器能够处理二进制数据，例如 ArrayBuffer 或 Uint8Array。
  • close() 方法可以接受 code 和可选的 reason 参数来指定 WebSocket 连接如何关闭。
大纲