WebSocket

此类表示 WebSocket。它扩展了 EventEmitter。

一、状态常量

常量	值	描述
CONNECTING	0	连接尚未打开。
OPEN	1	连接是开放的，可以进行通信。
CLOSING	2	连接正在关闭。
CLOSED	3	连接已关闭。

二、创建WebSocket对象实例

new WebSocket(address[, protocols][, options])

• address:{String|url.URL}： 要连接到的 URL。

• protocols:{String|Array} ：子协议的列表。

• options:{Object}：

  • autoPong:{Boolean}：指定是否自动发送 pong 以响应 ping。默认值为 true。
  • allowSynchronousEvents:{Boolean}：指定是否可以在同一刻度中多次发出任何 message、ping 和 pong 事件。默认值为 true。将其设置为 false 可提高与 WHATWG 标准的兼容性，但可能会对性能产生负面影响。
  • finishRequest:{Function}：一个函数，可用于在发送每个 HTTP 请求之前自定义其标头。请参阅下面的说明。
  • followRedirects:{Boolean}：用于生成屏蔽键的函数。它需要一个 Buffer，该 Buffer 必须同步填充，并在发送消息之前为每条消息调用。默认情况下，缓冲区填充了加密性强的随机字节。
  • handshakeTimeout:{Number}： 握手请求的超时时间（以毫秒为单位）。每次重定向后都会重置此值。
  • maxPayload:{Number} ：允许的最大消息大小（以字节为单位）。默认值为 100 MiB（104857600 字节）。
  • maxRedirects:{Number} ： 允许的最大重定向数。默认值为 10。
  • origin:{String}：Origin 或 Sec-WebSocket-Origin 标头的值，具体取决于 protocolVersion。
  • perMessageDeflate:{Boolean|Object} ：用/禁用 permessage-deflate。
  • protocolVersion:{Number}：Sec-WebSocket-Version 标头的值。
  • skipUTF8Validation:{Boolean}：指定是否跳过文本和关闭消息的 UTF-8 验证。默认值为 false。仅当服务器受信任时才设置为 true。
  • http.request() 或 https.request() 中允许的任何其他选项。如果从使用 address 参数给出的 URL 解析，则给出的选项没有任何效果。

警告

1、perMessageDeflate 默认值为 true。使用对象时，服务器的参数是相同的。唯一的区别是请求的方向。例如，serverNoContextTakeover 可用于要求服务器禁用上下文接管。

2、finishRequest 是用参数调用的

• request:{http.ClientRequest}
• websocket

对于每个 HTTP GET 请求（初始请求和由重定向引起的任何请求），当它准备好发送时，以允许在最后一刻自定义标头。如果设置了finishRequest，那么一旦设置完请求头，它就负责调用 request.end()这适用于无法提前提供某些标头的利基用例，例如，因为它们依赖于底层套接字。

二、事件

1、close

• code:{Number}
• reason:{Buffer}

提示

在连接关闭时发出。代码是一个数值，指示状态代码，说明连接关闭的原因。reason 是一个 Buffer，其中包含一个人类可读的字符串，用于解释连接关闭的原因

2、error

• error:{Error} 发生错误时发出。错误可能具有 code 属性用于描述已发生的特定类型的错误，与下面错误代码下定义的字符串值之一匹配。

  code	含义
  WS_ERR_EXPECTED_FIN	收到 WebSocket 帧时未设置 FIN 位
  WS_ERR_EXPECTED_MASK	WebSocket 服务器已接收到未屏蔽的 WebSocket 帧
  WS_ERR_INVALID_CLOSE_CODE	收到带有无效关闭代码的 WebSocket 关闭帧
  WS_ERR_INVALID_CONTROL_PAYLOAD_LENGTH	接收到有效负载长度无效的控制帧
  WS_ERR_INVALID_OPCODE	收到带有无效操作码的 WebSocket 帧
  WS_ERR_INVALID_UTF8	收到包含无效 UTF-8 数据的文本或关闭帧
  WS_ERR_UNEXPECTED_MASK	WebSocket 客户端接收到被屏蔽的 WebSocket 帧
  WS_ERR_UNEXPECTED_RSV_1	收到 WebSocket 帧时意外设置了 RSV1 位
  WS_ERR_UNEXPECTED_RSV_2_3	意外接收到设置了 RSV2 或 RSV3 位的 WebSocket 帧
  WS_ERR_UNSUPPORTED_DATA_PAYLOAD_LENGTH	接收的数据帧的长度超过支持的最大长度（2^53 - 1，由于 JavaScript 语言限制）
  WS_ERR_UNSUPPORTED_MESSAGE_LENGTH	收到的消息的长度超过了 maxPayload 选项配置的受支持的最大长度

3、message

• data:{ArrayBuffer|Blob|Buffer|Buffer[]}
• isBinary:{Boolean} 在收到消息时发出。data 是消息内容。isBinary 指定消息是否为二进制消息。

4、open

在建立连接时发出。

5、ping

• data:{Buffer}

在接收到 ping 时发出。

6、pong

• data: {Buffer}

在接收到pong时发射。

7、redirect

• url:{String}
• request:{http.ClientRequest}

提示

在执行重定向之前发出。url 是重定向 URL。request 是 HTTP的GET 请求。通过此事件，可以使用 request.getHeader() 和 request.removeHeader() API 检查headers并在每次重定向的基础上删除它们。request对象只能用于此目的。当此事件至少有一个侦听器时，默认情况下不会删除任何标头，即使重定向到不同的域也是如此。

8、unexpected-response

• request:{http.ClientRequest}
• response: {http.IncomingMessage}

提示

当服务器响应不是预期的响应时发出，例如 401 响应。此事件使人们能够读取响应以提取有用的信息。如果服务器发送无效响应，并且此事件没有侦听器，则会发出错误。

9、upgrade

• response:{http.IncomingMessage}

提示

在握手过程中从服务器接收到响应标头时发出。这允许您从服务器读取标头，例如set-cookie标头。

三、注册事件

提示

WebSocket.addEventListener() 方法用于为 WebSocket 对象注册事件监听器，它是基于 EventTarget 接口的实现。该方法允许你监听 WebSocket 的 open、message、error 和 close 事件，提供了一种更灵活的方式来处理 WebSocket 事件

websocket.addEventListener(type, listener[, options])

参数解释：

• type:String: 一个字符串，表示要监听的事件类型。可以是 'open'、'message'、'error' 或 'close'。
• listener:Function | Object : 事件处理函数或实现 EventListener 接口的对象。当指定的事件触发时，这个函数会被调用，接收一个事件对象作为参数。
• options:Object (可选): 额外的配置选项。可以包含以下属性：
  • once:Boolean: 如果为 true，则表示监听器在触发一次后会被自动移除。
  • capture:Boolean: 如果为 true，表示在事件的捕获阶段触发监听器。通常 WebSocket 事件不需要使用这个选项。
  • passive:Boolean: 如果为 true，表示监听器不会调用 preventDefault

// 创建 WebSocket 连接
const socket = new WebSocket('ws://localhost:8080/ws');

// 监听 WebSocket 打开事件
socket.addEventListener('open', function(event) {
    console.log('WebSocket 连接成功');
});

// 监听 WebSocket 收到消息事件
socket.addEventListener('message', function(event) {
    console.log('收到消息:', event.data);
});

// 监听 WebSocket 错误事件
socket.addEventListener('error', function(event) {
    console.error('WebSocket 发生错误:', event);
});

// 监听 WebSocket 关闭事件
socket.addEventListener('close', function(event) {
    console.log('WebSocket 连接关闭');
});

四、移除事件

removeEventListener(type, listener)

• type:{String}一个字符串，表示要删除的事件类型。
• listener:{Function|Object} 要删除的侦听器。

删除模拟 EventTarget 接口的事件侦听器。此方法仅删除使用 websocket.addEventListener() 添加的侦听器。

// 创建一个 WebSocket 连接
const ws = new WebSocket('ws://localhost:8080/ws/coupon');

// 定义一个事件监听器函数
function messageListener(event) {
    console.log('Received message:', event.data);
}

// 使用 addEventListener 添加事件监听器
ws.addEventListener('message', messageListener);

// 连接成功后发送消息
ws.addEventListener('open', () => {
    console.log('WebSocket connection opened.');
    ws.send('Hello Server!');
});

// 在某个时刻移除消息事件监听器
setTimeout(() => {
    console.log('Removing message listener.');
    ws.removeEventListener('message', messageListener);
}, 5000); // 5秒后移除监听器

五、实例属性

1、bufferedAmount

• {Number}

提示

已使用对 send() 的调用排队但尚未传输到网络的数据字节数。这在以下方面偏离了 HTML 标准：

1. 如果立即发送数据，则值为 0
2. 所有成帧字节都包括在内

2、close([code[, reason]])

• code:{Number}一个数值，指示状态代码，说明为什么关闭连接。
• reason:String|Buffer} 连接关闭的原因。

提示

启动结束握手

3、isPaused

• {Boolean}

提示

websocket 是否已暂停

4、extensions

• {Object}

提示

包含协商扩展的对象

5、protocol

• {String}

服务器选择的子协议。

6、readyState

• {Number}

连接的当前状态。这是就绪状态常量之一。

7、url

• 属性: {String} WebSocket 服务器的 URL。这个属性是 WebSocket 客户端特有的，服务器端的 WebSocket 客户端没有这个属性。

const ws = new WebSocket('ws://localhost:8080/ws/coupon');

ws.addEventListener('open', () => {
    console.log('WebSocket connection opened.');
    
    // 获取 WebSocket 服务器的 URL
    console.log('WebSocket URL:', ws.url);
});

六、实例方法

1、onclose

• {Function}

连接关闭时要调用的事件侦听器。侦听器会收到一个名为“close”的 CloseEvent。

2、onerror

• {Function}

发生错误时要调用的事件侦听器。侦听器会收到一个名为“error”的 ErrorEvent。

3、onmessage

• {Function}

收到消息时要调用的事件侦听器。侦听器会收到一个名为“message”的 MessageEvent。

4、onopen

• {Function}

建立连接时要调用的事件侦听器。侦听器会收到一个名为“open”的 OpenEvent。

5、pause()

暂停 WebSocket，导致其停止发出事件。在调用此方法后，一些事件可能仍会被发出，直到所有缓冲数据被消耗完为止。如果 WebSocket 的状态是 CONNECTING（正在连接）或 CLOSED（已关闭），此方法将不会执行任何操作。

6、ping([data[, mask]][, callback])

• data: {Array|Number|Object|String|ArrayBuffer|Buffer|DataView|TypedArray|Blob} 要在 ping 帧中发送的数据。
• mask:{Boolean}指定是否应屏蔽数据。当 websocket 不是服务器客户端时，默认为 true。
• callback:{Function} 一个可选的回调，在写出 ping 帧时调用。如果发生错误，将使用错误作为其第一个参数来调用回调。

发送 ping。如果就绪状态为 CONNECTING，则此方法将引发错误。

7、pong([data[, mask]][, callback])

• data: {Array|Number|Object|String|ArrayBuffer|Buffer|DataView|TypedArray|Blob} 要在 pong 帧中发送的数据。
• mask:{Boolean}指定是否应屏蔽数据。当 websocket 不是服务器客户端时，默认为 true。
• callback:{Function} 一个可选的回调，在写出 pong 帧时调用。如果发生错误，将使用错误作为其第一个参数来调用回调。

发送一个pong。如果就绪状态为 CONNECTING，则此方法将引发错误。

7、resume()

使暂停的 WebSocket 恢复发出事件。如果 WebSocket 的状态是 CONNECTING（正在连接）或 CLOSED（已关闭），此方法将不会执行任何操作

8、send(data[, options][, callback])

• data:{Array|Number|Object|String|ArrayBuffer|Buffer|DataView|TypedArray|Blob}要发送的数据，仅当对象Buffer.from() 的要求时，才受支持。如果不满足这些约束，则会引发 TypeError。

• options: {Object}

  • binary:{Boolean} ： 指定数据是否应作为二进制文件发送。默认值为自动检测。
  • compress:{Boolean} ：指定是否应压缩数据。启用 permessage-deflate 时，默认值为 true。
  • fin:{Boolean} ：指定数据是否是消息的最后一个片段。默认值为 true。
  • mask:{Boolean}：指定是否应屏蔽数据。当 websocket 不是服务器客户端时，默认为 true。

• callback:{Function} ：一个可选的回调，在写出数据时调用。如果发生错误，将使用错误作为其第一个参数来调用回调。

通过连接发送数据。如果 WebSocket 的状态是 CONNECTING（正在连接），此方法将抛出错误。

9、terminate()

• 功能: 强行关闭 WebSocket 连接。这个方法会立即中断连接，不会等待数据传输完成或执行任何清理操作。在内部，这个方法调用 socket.destroy() 来强制关闭连接。

const ws = new WebSocket('ws://localhost:8080/ws/coupon');

// 连接成功后
ws.addEventListener('open', () => {
    console.log('WebSocket connection opened.');
    
    // 强行关闭 WebSocket 连接
    ws.terminate();
    console.log('WebSocket connection terminated.');
});