WebSocket

这是一个实验中的功能
此功能某些浏览器尚在开发中，请参考浏览器兼容性表格以得到在不同浏览器中适合使用的前缀。由于该功能对应的标准文档可能被重新修订，所以在未来版本的浏览器中该功能的语法和行为可能随之改变。

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

WebSocket构造器方法接受一个必须的参数和一个可选的参数：

WebSocket WebSocket(in DOMString url, in optional DOMString protocols);
WebSocket WebSocket(in DOMString url,in optional DOMString[] protocols);

参数

url
表示要连接的URL。这个URL应该为响应WebSocket的地址。
protocols 可选
可以是一个单个的协议名字字符串或者包含多个协议名字字符串的数组。这些字符串用来表示子协议，这样做可以让一个服务器实现多种WebSocket子协议（例如你可能希望通过制定不同的协议来处理不同类型的交互）。如果没有制定这个参数，它会默认设为一个空字符串。

构造器方法可能抛出以下异常：

SECURITY_ERR
试图连接的端口被屏蔽。

方法概述

void close(in optional unsigned long code, in optional DOMString reason);
void send(in DOMString data);

属性

属性名 类型 描述
binaryType DOMString

一个字符串表示被传输二进制的内容的类型。取值应当是"blob"或者"arraybuffer"。

"blob"表示使用DOMBlob 对象，而"arraybuffer"表示使用 ArrayBuffer 对象。
bufferedAmount unsigned long 调用 send() 方法将多字节数据加入到队列中等待传输，但是还未发出。该值会在所有队列数据被发送后重置为 0。而当连接关闭时不会设为0。如果持续调用send()，这个值会持续增长。只读。
extensions DOMString 服务器选定的扩展。目前这个属性只是一个空字符串，或者是一个包含所有扩展的列表。
onclose EventListener 用于监听连接关闭事件监听器。当 WebSocket 对象的readyState 状态变为 CLOSED 时会触发该事件。这个监听器会接收一个叫close的 CloseEvent 对象。
onerror EventListener 当错误发生时用于监听error事件的事件监听器。会接受一个名为“error”的event对象。
onmessage EventListener 一个用于消息事件的事件监听器，这一事件当有消息到达的时候该事件会触发。这个Listener会被传入一个名为"message"的 MessageEvent 对象。
onopen EventListener 一个用于连接打开事件的事件监听器。当readyState的值变为 OPEN 的时候会触发该事件。该事件表明这个连接已经准备好接受和发送数据。这个监听器会接受一个名为"open"的事件对象。
protocol DOMString 一个表明服务器选定的子协议名字的字符串。这个属性的取值会被取值为构造器传入的protocols参数。
readyState unsigned short 连接的当前状态。取值是 Ready state constants之一。 只读。
url DOMString 传入构造器的URL。它必须是一个绝对地址的URL。只读。

常量

Ready state 常量

这些常量是 readyState 属性的取值，可以用来描述 WebSocket 连接的状态。

常量 值 描述
CONNECTING 0 连接还没开启。
OPEN 1 连接已开启并准备好进行通信。
CLOSING 2 连接正在关闭的过程中。
CLOSED 3 连接已经关闭，或者连接无法建立。

方法

close()

关闭WebSocket连接或停止正在进行的连接请求。如果连接的状态已经是closed，这个方法不会有任何效果

void close(in optional unsigned short code, in optional DOMString reason);

参数

code 可选
一个数字值表示关闭连接的状态号，表示连接被关闭的原因。如果这个参数没有被指定，默认的取值是1000 （表示正常连接关闭）。 请看CloseEvent页面的 list of status codes来看默认的取值。
reason 可选
一个可读的字符串，表示连接被关闭的原因。这个字符串必须是不长于123字节的UTF-8 文本（不是字符）。

可能抛出的异常

INVALID_ACCESS_ERR
选定了无效的code。
SYNTAX_ERR
reason 字符串太长或者含有unpaired surrogates。

注意： 在Gecko中，Gecko 8.0 (Firefox 8.0 / Thunderbird 8.0 / SeaMonkey 2.5)之间的版本的实现不支持任何参数。

send()

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

void send(in DOMString data);
void send(in ArrayBuffer data);
void send(in Blob data);

参数

data
要发送到服务器的数据。

可能抛出的异常

INVALID_STATE_ERR
当前连接的状态不是OPEN。
SYNTAX_ERR
数据是一个包含unpaired surrogates的字符串。

注意: Gecko 6.0实现的send()方法与规范的要求有一些不同。Gecko会返回一个 boolean表示连接是否依然处于开启状态 （并且这个数据被成功放入的发送队列或者被发送）。在 Gecko 8.0中这个问题被修正了。

到了 Gecko 11.0，实现了接受 ArrayBuffer的参数的方法，但接受 Blob数据类型的方法没有被实现。

示例

// 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);
});

规范

规范 状态 注释
Unknown
WebSocket		 Unknown 初始定义

浏览器兼容性

特性 Chrome Firefox (Gecko) Internet Explorer Opera Safari
基础支持 (Yes) 4.0 (2.0) (Yes) (Yes) ?
Sub-protocol support ? 6.0 (6.0) ? ? ?
特性 Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
基础支持 ? 7.0 (7.0) ? ? ?
Sub-protocol support ? 7.0 (7.0) ? ? ?

[1] 从Gecko 6.0开始，构造器含有前缀，你需要调用MozWebSocket(): var mySocket = new MozWebSocket("http://www.example.com/socketserver");

extensions 属性直到Gecko 8.0才被支持。

在 Gecko 11.0之前，用send()方法发送的数据被限制在16MB以内。现在数据大小可以达到2 GB。

另见

文档标签和贡献者