WebSocket: WebSocket() Konstruktor

Baseline Weitgehend verfügbar *

Diese Funktion ist gut etabliert und funktioniert auf vielen Geräten und in vielen Browserversionen. Sie ist seit Juli 2015 browserübergreifend verfügbar.

* Einige Teile dieser Funktion werden möglicherweise unterschiedlich gut unterstützt.

Hinweis: Diese Funktion ist in Web Workers verfügbar.

Der WebSocket() Konstruktor gibt ein neues WebSocket-Objekt zurück und versucht sofort, eine Verbindung zur angegebenen WebSocket-URL herzustellen.

Die URL des Ziel-WebSocket-Servers, zu dem eine Verbindung hergestellt werden soll. Die URL muss eines der folgenden Schemen verwenden: ws, wss, http oder https, und darf kein URL-Fragment enthalten. Wenn eine relative URL angegeben wird, ist sie relativ zur Basis-URL des aufrufenden Skripts.

protocols Optional

Ein einzelner String oder ein Array von Strings, die das/die Subprotokoll(e) darstellen, das/die der Client in der Reihenfolge der Präferenz verwenden möchte. Wenn es weggelassen wird, wird standardmäßig ein leeres Array verwendet, d.h. [].

Ein einzelner Server kann mehrere WebSocket-Subprotokolle implementieren und verschiedene Arten von Interaktionen je nach dem angegebenen Wert handhaben. Beachten Sie jedoch, dass pro Verbindung nur ein Subprotokoll ausgewählt werden kann.

Die erlaubten Werte sind diejenigen, die im Sec-WebSocket-Protocol HTTP-Header angegeben werden können. Diese sind Werte, die aus dem IANA WebSocket Subprotocol Name Registry ausgewählt wurden, wie soap, wamp, ship und so weiter, oder können ein benutzerdefinierter Name sein, der zwischen dem Client und dem Server ausdrücklich verstanden wird.

Hinweis: Die Verbindung wird nicht hergestellt, bis das Subprotokoll mit dem Server ausgehandelt ist. Das ausgewählte Protokoll kann dann von WebSocket.protocol abgelesen werden: Es wird der leere String sein, wenn keine Verbindung hergestellt werden kann.

Ausnahmen

SyntaxError DOMException

Ausgelöst, wenn:

das Parsen der url fehlschlägt
url ein anderes Schema als ws, wss, http oder https hat
url ein Fragment hat
einer der Werte in protocols mehr als einmal vorkommt oder anderweitig die Anforderungen für Elemente nicht erfüllt, die den Wert der Felder Sec-WebSocket-Protocol gemäß der WebSocket-Protokollspezifikation ausmachen

Beispiele

Die folgenden Beispiele zeigen, wie Sie eine Verbindung zu einem WebSocket herstellen könnten.

Der untenstehende Code zeigt, wie wir mithilfe einer URL mit dem Schema wss eine Verbindung zu einem Socket herstellen können:

const wssWebSocket = new WebSocket("wss://websocket.example.org");
console.log(wssWebSocket.url); // 'wss://websocket.example.org'

// Do something with socket

wssWebSocket.close();

Der Code für die Verbindung zu einer HTTPS-URL ist nahezu identisch. Im Hintergrund wird dies durch den Browser zu einer „WSS“-Verbindung aufgelöst, sodass die WebSocket.url das Schema „wss:“ haben wird.

const httpsWebSocket = new WebSocket("https://websocket.example.org");
console.log(httpsWebSocket.url); // 'wss://websocket.example.org'

// Do something with socket

httpsWebSocket.close();

Wir können auch relative URLs auflösen. Die absolute URL hängt von der Basis-URL des Kontexts ab, in dem sie aufgerufen wird.

relativeWebSocket = new WebSocket("/local/url");

// Do something with socket

relativeWebSocket.close();

Die vorherigen Beispiele zeigen, wie ein WebSocket konstruiert wird, aber die Verbindung wird asynchron hergestellt. Der Aufruf von send() vor dem Auslösen des open-Ereignisses führt zu einer InvalidStateError-Ausnahme, weil readyState noch CONNECTING ist. Wenn die Verbindung nicht hergestellt werden kann (zum Beispiel, wenn der Server nicht erreichbar ist oder das Handshake fehlschlägt), wird ein error-Ereignis ausgelöst, gefolgt von einem close-Ereignis, dessen wasClean-Eigenschaft false ist — daher endet jeder Verbindungsversuch letztendlich entweder mit einem open-Ereignis oder einem close-Ereignis. Das folgende Beispiel zeigt, wie man auf die Verbindung wartet, bevor man sendet, und wie man die error- und close-Ereignisse behandelt:

// Create WebSocket connection.
const socket = new WebSocket("wss://websocket.example.org");

// Connection opened
socket.addEventListener("open", (event) => {
  socket.send("Hello Server!");
});

// Listen for messages
socket.addEventListener("message", (event) => {
  console.log("Message from server:", event.data);
});

// Handle errors
socket.addEventListener("error", (event) => {
  console.error("WebSocket error:", event);
});

// Handle disconnection
socket.addEventListener("close", (event) => {
  if (event.wasClean) {
    console.log(`Closed cleanly, code=${event.code}, reason=${event.reason}`);
  } else {
    console.log("Connection died");
  }
});