WebSocket client applications use the WebSocket API to communicate with WebSocket servers using the WebSocket protocol.
注意： 此特征可用于 Web 工作者 .注意： The example snippets in this article are taken from our WebSocket chat client/server sample. See the code ，那么 try out the example for yourself .
In order to communicate using the WebSocket protocol, you need to create a
WebSocket
object; this will automatically attempt to open the connection to the server.
The WebSocket constructor accepts one required and one optional parameter:
webSocket = new WebSocket(url, protocols);
url
wss://
, although some software may allow you to use the insecure
ws://
for local connections.
protocols
可选
协议
). If you don't specify a protocol string, an empty string is assumed.
The constructor will throw a
SecurityError
if the destination doesn't allow access. This may happen if you attempt to use an insecure connection (most
user agents
now require a secure link for all WebSocket connections unless they're on the same device or possibly on the same network).
If an error occurs while attempting to connect, first a simple event with the name
error
is sent to the
WebSocket
object (thereby invoking its
onerror
handler), and then the
CloseEvent
is sent to the
WebSocket
object (thereby invoking its
onclose
handler) to indicate the reason for the connection's closing.
The browser may also output to its console a more descriptive error message as well as a closing code as defined in
RFC 6455, Section 7.4
透过
CloseEvent
.
This simple example creates a new WebSocket, connecting to the server at
wss://www.example.com/socketserver
. A custom protocol of "protocolOne" is named in the request for the socket in this example, though this can be omitted.
var exampleSocket = new WebSocket("wss://www.example.com/socketserver", "protocolOne");
On return,
exampleSocket.readyState
is
CONNECTING
。
readyState
will become
OPEN
once the connection is ready to transfer data.
If you want to open a connection and are flexible about the protocols you support, you can specify an array of protocols:
var exampleSocket = new WebSocket("wss://www.example.com/socketserver", ["protocolOne", "protocolTwo"]);
Once the connection is established (that is,
readyState
is
OPEN
),
exampleSocket.protocol
will tell you which protocol the server selected.
Establishing a WebSocket relies on the
HTTP Upgrade mechanism
, so the request for the protocol upgrade is implicit when we address the web server as
ws://www.example.com
or
wss://www.example.com
.
Once you've opened your connection, you can begin transmitting data to the server. To do this, simply call the
WebSocket
对象的
send()
method for each message you want to send:
exampleSocket.send("Here's some text that the server is urgently awaiting!");
You can send data as a string,
Blob
，或
ArrayBuffer
.
As establishing a connection is asynchronous and prone to failure there is no guarantee that calling the
send()
method immediately after creating a WebSocket object will be successful. We can at least be sure that attempting to send data only takes place once a connection is established by defining an
onopen
event handler to do the work:
exampleSocket.onopen = function (event) {
exampleSocket.send("Here's some text that the server is urgently awaiting!");
};
One handy thing you can do is use JSON to send reasonably complex data to the server. For example, a chat program can interact with a server using a protocol implemented using packets of JSON-encapsulated data:
// Send text to all users through the server
function sendText() {
// Construct a msg object containing the data the server needs to process the message from the chat client.
var msg = {
type: "message",
text: document.getElementById("text").value,
id: clientID,
date: Date.now()
};
// Send the msg object as a JSON-formatted string.
exampleSocket.send(JSON.stringify(msg));
// Blank the text input element, ready to receive the next line of text from the user.
document.getElementById("text").value = "";
}
WebSockets is an event-driven API; when messages are received, a
message
event is sent to the
WebSocket
object. To handle it, add an event listener for the
message
event, or use the
onmessage
event handler. To begin listening for incoming data, you can do something like this:
exampleSocket.onmessage = function (event) {
console.log(event.data);
}
Let's consider the chat client application first alluded to in Using JSON to transmit objects . There are assorted types of data packets the client might receive, such as:
The code that interprets these incoming messages might look like this:
exampleSocket.onmessage = function(event) {
var f = document.getElementById("chatbox").contentDocument;
var text = "";
var msg = JSON.parse(event.data);
var time = new Date(msg.date);
var timeStr = time.toLocaleTimeString();
switch(msg.type) {
case "id":
clientID = msg.id;
setUsername();
break;
case "username":
text = "<b>User <em>" + msg.name + "</em> signed in at " + timeStr + "</b><br>";
break;
case "message":
text = "(" + timeStr + ") <b>" + msg.name + "</b>: " + msg.text + "<br>";
break;
case "rejectusername":
text = "<b>Your username has been set to <em>" + msg.name + "</em> because the name you chose is in use.</b><br>"
break;
case "userlist":
var ul = "";
for (i=0; i < msg.users.length; i++) {
ul += msg.users[i] + "<br>";
}
document.getElementById("userlistbox").innerHTML = ul;
break;
}
if (text.length) {
f.write(text);
document.getElementById("chatbox").contentWindow.scrollByPages(1);
}
};
Here we use
JSON.parse()
to convert the JSON object back into the original object, then examine and act upon its contents.
Text received over a WebSocket connection is in UTF-8 format.
When you've finished using the WebSocket connection, call the WebSocket method
close()
:
exampleSocket.close();
It may be helpful to examine the socket's
bufferedAmount
attribute before attempting to close the connection to determine if any data has yet to be transmitted on the network. If this value isn't 0, there's pending data still, so you may wish to wait before closing the connection.
WebSockets should not be used in a mixed content environment; that is, you shouldn't open a non-secure WebSocket connection from a page loaded using HTTPS or vice-versa. Most browsers now only allow secure WebSocket connections, and no longer support using them in insecure contexts.
WebSockets_API