Schreiben von WebSocket-Clientanwendungen
Hinweis: Dieses Feature ist verfügbar in Web Workers.
WebSocket-Clientanwendungen verwenden die WebSocket API, um mit WebSocket-Servern über das WebSocket-Protokoll zu kommunizieren.
Hinweis: Die Beispielausschnitte in diesem Artikel stammen von unserem WebSocket-Chat-Client/Server-Beispiel. Sehen Sie den Code.
Erstellen eines WebSocket-Objekts
Um über das WebSocket-Protokoll zu kommunizieren, müssen Sie ein WebSocket
-Objekt erstellen; dies wird automatisch versuchen, die Verbindung zum Server zu öffnen.
Der WebSocket-Konstruktor akzeptiert einen erforderlichen und einen optionalen Parameter:
webSocket = new WebSocket(url, protocols);
url
-
Die URL, mit der Sie eine Verbindung herstellen möchten; dies sollte die URL sein, auf die der WebSocket-Server antworten wird. Dies sollte das URL-Schema
wss://
verwenden, obwohl einige Software möglicherweise erlauben, das unsicherews://
für eine lokale Verbindung zu verwenden. Relative URL-Werte sowiehttps://
- undhttp://
-Schemata sind auch in den meisten aktuellen Browserversionen erlaubt. protocols
Optional-
Entweder ein einzelner Protokoll-String oder ein Array von Protokoll-Strings. Diese Strings werden verwendet, um Unterprotokolle anzugeben, damit ein einzelner Server mehrere WebSocket-Unterprotokolle implementieren kann (zum Beispiel könnten Sie möchten, dass ein Server verschiedene Arten von Interaktionen abhängig vom angegebenen
protocol
handhaben kann). Wenn Sie keinen Protokoll-String angeben, wird ein leerer String angenommen.
Der Konstruktor wird einen SecurityError
auslösen, wenn das Ziel den Zugriff nicht erlaubt.
Dies kann passieren, wenn Sie versuchen, eine unsichere Verbindung zu verwenden (die meisten User Agents erfordern jetzt eine sichere Verbindung für alle WebSocket-Verbindungen, es sei denn, sie befinden sich auf demselben Gerät oder möglicherweise im selben Netzwerk).
Verbindungsfehler
Wenn ein Fehler bei dem Versuch auftritt, eine Verbindung herzustellen, wird zuerst eine error
event an das WebSocket
-Objekt gesendet (wodurch alle Handler aufgerufen werden), gefolgt von einem close
event, das den Grund für das Schließen der Verbindung angibt.
Der Browser kann auch eine detailliertere Fehlermeldung sowie einen Abschlusscode, wie in RFC 6455, Abschnitt 7.4 definiert, über das CloseEvent
an seine Konsole ausgeben.
Beispiele
Dieses einfache Beispiel erstellt einen neuen WebSocket, der eine Verbindung zum Server unter wss://www.example.com/socketserver
herstellt.
Ein benutzerdefiniertes Protokoll namens „protocolOne“ wird in der Anforderung für den Socket in diesem Beispiel angegeben, obwohl dies weggelassen werden kann.
const exampleSocket = new WebSocket(
"wss://www.example.com/socketserver",
"protocolOne",
);
Bei der Rückgabe ist exampleSocket.readyState
CONNECTING
.
Der readyState
wird OPEN
, sobald die Verbindung bereit ist, Daten zu übertragen.
Wenn Sie eine Verbindung öffnen möchten und bei den Protokollen flexibel sind, die Sie unterstützen, können Sie ein Array von Protokollen angeben:
const exampleSocket = new WebSocket("wss://www.example.com/socketserver", [
"protocolOne",
"protocolTwo",
]);
Sobald die Verbindung hergestellt ist (d. h. readyState
ist OPEN
), wird exampleSocket.protocol
Ihnen sagen, welches Protokoll der Server ausgewählt hat.
Das Herstellen einer WebSocket-Verbindung basiert auf dem HTTP Upgrade-Mechanismus, sodass die Anforderung für das Protokoll-Upgrade implizit ist, wenn wir den Webserver als ws://www.example.com
oder wss://www.example.com
ansprechen.
Senden von Daten an den Server
Sobald Sie Ihre Verbindung geöffnet haben, können Sie beginnen, Daten an den Server zu übertragen.
Um dies zu tun, rufen Sie die send()
-Methode des WebSocket
-Objekts für jede Nachricht auf, die Sie senden möchten:
exampleSocket.send("Here's some text that the server is urgently awaiting!");
Sie können Daten als String, Blob
oder ArrayBuffer
senden.
Da das Herstellen einer Verbindung asynchron und anfällig für Fehler ist, gibt es keine Garantie, dass das sofortige Aufrufen der send()
-Methode nach dem Erstellen eines WebSocket-Objekts erfolgreich sein wird.
Wir können uns zumindest sicher sein, dass der Versuch, Daten zu senden, nur dann stattfindet, wenn eine Verbindung hergestellt ist, indem wir einen onopen
-Ereignishandler definieren, der die Arbeit übernimmt:
exampleSocket.onopen = (event) => {
exampleSocket.send("Here's some text that the server is urgently awaiting!");
};
Verwenden von JSON zur Übertragung von Objekten
Eine nützliche Sache, die Sie tun können, ist die Verwendung von JSON, um ziemlich komplexe Daten an den Server zu senden. Ein Chatprogramm kann beispielsweise mit einem Server interagieren, indem es ein Protokoll verwendet, das mit JSON-kapsulierten Datenpaketen implementiert ist:
// 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.
const 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 = "";
}
Empfangen von Nachrichten vom Server
WebSockets ist eine ereignisgesteuerte API; wenn Nachrichten empfangen werden, wird ein message
-Ereignis an das WebSocket
-Objekt gesendet. Um es zu verarbeiten, fügen Sie einen Ereignislistener für das message
-Ereignis hinzu oder verwenden Sie den onmessage
-Ereignishandler.
Um mit dem Hören auf eingehende Daten zu beginnen, können Sie Folgendes tun:
exampleSocket.onmessage = (event) => {
console.log(event.data);
};
Empfangen und Interpretieren von JSON-Objekten
Betrachten wir zuerst die Chat-Clientanwendung, die in Verwenden von JSON zur Übertragung von Objekten erwähnt wurde. Es gibt verschiedene Arten von Datenpaketen, die der Client empfangen könnte, wie z.B.:
- Login-Handshake
- Nachrichtentext
- Aktualisierungen der Benutzerliste
Der Code, der diese eingehenden Nachrichten interpretiert, könnte so aussehen:
exampleSocket.onmessage = (event) => {
const f = document.getElementById("chat-box").contentDocument;
let text = "";
const msg = JSON.parse(event.data);
const time = new Date(msg.date);
const timeStr = time.toLocaleTimeString();
switch (msg.type) {
case "id":
clientID = msg.id;
setUsername();
break;
case "username":
text = `User <em>${msg.name}</em> signed in at ${timeStr}<br>`;
break;
case "message":
text = `(${timeStr}) ${msg.name} : ${msg.text} <br>`;
break;
case "reject-username":
text = `Your username has been set to <em>${msg.name}</em> because the name you chose is in use.<br>`;
break;
case "user-list":
document.getElementById("user-list-box").innerText = msg.users.join("\n");
break;
}
if (text.length) {
f.write(text);
document.getElementById("chat-box").contentWindow.scrollByPages(1);
}
};
Hier verwenden wir JSON.parse()
, um das JSON-Objekt zurück in das ursprüngliche Objekt zu konvertieren, und untersuchen dann dessen Inhalt und reagieren entsprechend.
Textdatenformat
Text, der über eine WebSocket-Verbindung empfangen wird, liegt im UTF-8-Format vor.
Schließen der Verbindung
Wenn Sie die WebSocket-Verbindung beendet haben, rufen Sie die close()
-Methode von WebSocket auf:
exampleSocket.close();
Es kann hilfreich sein, das Attribut bufferedAmount
der Verbindung zu überprüfen, bevor Sie versuchen, die Verbindung zu schließen, um festzustellen, ob noch Daten im Netzwerk übertragen werden sollen.
Wenn dieser Wert nicht 0 ist, sind noch ausstehende Daten vorhanden, sodass Sie möglicherweise warten möchten, bevor Sie die Verbindung schließen.
Sicherheitsüberlegungen
WebSockets sollten nicht in einer gemischten Inhaltsumgebung verwendet werden; das heißt, Sie sollten keine unsichere WebSocket-Verbindung von einer Seite öffnen, die über HTTPS geladen wurde, oder umgekehrt. Die meisten Browser erlauben jetzt nur noch sichere WebSocket-Verbindungen und unterstützen deren Verwendung in unsicheren Kontexten nicht mehr.