WebSocket

WebSocket 对象提供了用于创建和管理 WebSocket 连接，以及可以通过该连接发送和接收数据的 API。

使用WebSocket()构造函数来构造一个 WebSocket。

构造函数

• WebSocket(url[, protocols\])

  返回一个 WebSocket 对象。

常量

Constant	Value
WebSocket.CONNECTING	0
WebSocket.OPEN	1
WebSocket.CLOSING	2
WebSocket.CLOSED	3

属性

• WebSocket.binaryType 使用二进制的数据类型连接。

• WebSocket.bufferedAmount 只读

  未发送至服务器的字节数。

• WebSocket.extensions 只读

  服务器选择的扩展。

• WebSocket.onclose

  用于指定连接关闭后的回调函数。

• WebSocket.onerror

  用于指定连接失败后的回调函数。

• WebSocket.onmessage

  用于指定当从服务器接受到信息时的回调函数。

• WebSocket.onopen

  用于指定连接成功后的回调函数。

• WebSocket.protocol 只读

  服务器选择的下属协议。

• WebSocket.readyState 只读

  当前的链接状态。

• WebSocket.url 只读

  WebSocket 的绝对路径。

方法

• WebSocket.close([code[, reason\]])

  关闭当前链接。

• WebSocket.send(data)

  对要传输的数据进行排队。

事件

使用 addEventListener() 或将一个事件监听器赋值给本接口的 oneventname 属性，来监听下面的事件。

• close

  当一个 WebSocket 连接被关闭时触发。 也可以通过 onclose 属性来设置。

• error

  当一个 WebSocket 连接因错误而关闭时触发，例如无法发送数据时。 也可以通过 onerror 属性来设置。

• message

  当通过 WebSocket 收到数据时触发。 也可以通过 onmessage 属性来设置。

• open

  当一个 WebSocket 连接成功时触发。 也可以通过 onopen 属性来设置。

示例

// Create WebSocket connection.
const socket = new WebSocket('ws://localhost:8080');

// Connection opened
socket.addEventListener('open', function (event) {
    socket.send('Hello Server!');
});

// Listen for messages
socket.addEventListener('message', function (event) {
    console.log('Message from server ', event.data);
});

构造函数

WebSocket() 构造函数返回一个 WebSocket对象 .

语法

var aWebSocket = new WebSocket(url [, protocols]);

参数

• url要连接的 URL；这应该是 WebSocket 服务器将响应的 URL。
• protocols (可选) 一个协议字符串或者一个包含协议字符串的数组。这些字符串用于指定子协议，这样单个服务器可以实现多个 WebSocket 子协议（例如，您可能希望一台服务器能够根据指定的协议（protocol）处理不同类型的交互）。如果不指定协议字符串，则假定为空字符串。

抛出异常

• SECURITY_ERR 正在尝试连接的端口被阻止。

实例属性

WebSocket.binaryType

webSocket.binaryType 返回 websocket 连接所传输二进制数据的类型。

语法

var binaryType = aWebSocket.binaryType;

返回值

一条DOMString:

• "blob"如果传输的是 Blob 类型的数据。

• "arraybuffer"如果传输的是 ArrayBuffer 类型的数据。

WebSocket.bufferedAmount

WebSocket.bufferedAmount是一个只读属性，用于返回已经被send()方法放入队列中但还没有被发送到网络中的数据的字节数。一旦队列中的所有数据被发送至网络，则该属性值将被重置为 0。但是，若在发送过程中连接被关闭，则属性值不会重置为 0。如果你不断地调用send()，则该属性值会持续增长。

语法

var bufferedAmount = aWebSocket.bufferedAmount;

返回值

一个无符号的长字符串。

WebSocket.extensions

**WebSocket.extensions**是只读属性，返回服务器已选择的扩展值。目前，链接可以协定的扩展值只有空字符串或者一个扩展列表。

语法

var extensions = aWebSocket.extensions;

返回值

一个 dom 字符串

WebSocket.protocol

WebSocket.protocol 是个只读属性，用于返回服务器端选中的子协议的名字；这是一个在创建 WebSocket 对象时，在参数 protocols 中指定的字符串，当没有已建立的链接时为空串。

语法

var protocol = aWebSocket.protocol;

返回值

一个 dom 字符串

WebSocket.readyState

概要

返回当前 WebSocket 的链接状态，只读。

语法

var readyState = WebSocket.readyState;

值

以下其中之一

• 0 (WebSocket.CONNECTING) 正在链接中

• 1 (WebSocket.OPEN) 已经链接并且可以通讯

• 2 (WebSocket.CLOSING) 连接正在关闭

• 3 (WebSocket.CLOSED) 连接已关闭或者没有链接成功

WebSocket.url

**WebSocket.url**是一个只读属性，返回值为当构造函数创建WebSocket实例对象时 URL 的绝对路径。

语法

var url = aWebSocket.url;

实例方法

WebSocket.close()

WebSocket.close() 方法关闭 WebSocket 连接或连接尝试（如果有的话）。如果连接已经关闭，则此方法不执行任何操作。

语法

WebSocket.close();

参数

• code 可选 一个数字状态码，它解释了连接关闭的原因。如果没有传这个参数，默认使用 1005。CloseEvent的允许的状态码见状态码列表 。

• reason 可选 一个人类可读的字符串，它解释了连接关闭的原因。这个 UTF-8 编码的字符串不能超过 123 个字节。

WebSocket.send()

WebSocket.send() 方法将需要通过 WebSocket 链接传输至服务器的数据排入队列，并根据所需要传输的 data bytes 的大小来增加 bufferedAmount的值。若数据无法传输（例如数据需要缓存而缓冲区已满）时，套接字会自行关闭。

语法

WebSocket.send("Hello server!");

参数

• data 用于传输至服务器的数据。它必须是以下类型之一：

• USVString 文本字符串。字符串将以 UTF-8 格式添加到缓冲区，并且 bufferedAmount 将加上该字符串以 UTF-8 格式编码时的字节数的值。

• ArrayBuffer 您可以使用一有类型的数组对象发送底层二进制数据；其二进制数据内存将被缓存于缓冲区，bufferedAmount 将加上所需字节数的值。

• Blob Blob 类型将队列 blob 中的原始数据以二进制中传输。 bufferedAmount 将加上原始数据的字节数的值。

• ArrayBufferView 您可以以二进制帧的形式发送任何 JavaScript 类数组对象 ；其二进制数据内容将被队列于缓冲区中。值 bufferedAmount 将加上必要字节数的值。

事件

WebSocket.onclose

WebSocket.onclose 属性返回一个事件监听器，这个事件监听器将在 WebSocket 连接的readyState 变为 CLOSED时被调用，它接收一个名字为“close”的 CloseEvent 事件。

语法

WebSocket.onclose = function(event) {
  console.log("WebSocket is closed now.");
};

WebSocket: error

当websocket的连接由于一些错误事件的发生 (例如无法发送一些数据) 而被关闭时，一个error事件将被引发。

Bubbles	No
Cancelable	No
Interface	Event
Event handler property	onerror

示例

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

// Listen for possible errors
// 监听可能发生的错误
socket.addEventListener('error', function (event) {
  console.log('WebSocket error: ', event);
});

WebSocket: message event

message 事件会在 WebSocket 接收到新消息时被触发。

起泡（Bubbles）	不
可取消	不
接口	MessageEvent
事件处理程序属性	onmessage

例子

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

// 监听消息
socket.addEventListener('message', function (event) {
    console.log('Message from server ', event.data);
});

WebSocket.onopen

**WebSocket.onopen**属性定义一个事件处理程序，当WebSocket 的连接状态readyState 变为1时调用;这意味着当前连接已经准备好发送和接受数据。这个事件处理程序通过 事件（建立连接时）触发。

语法

aWebSocket.onopen = function(event) {
  console.log("WebSocket is open now.");
};