WebSocket: WebSocket() Konstruktor

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

* Some parts of this feature may have varying levels of support.

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.

Syntax

js
new WebSocket(url)
new WebSocket(url, protocols)

Parameter

url

Die URL des Ziel-WebSocket-Servers, mit dem eine Verbindung hergestellt werden soll. Die URL muss eines der folgenden Schemata verwenden: ws, wss, http oder https und darf kein URL-Fragment enthalten. Wenn eine relative URL angegeben wird, bezieht sie sich auf die Basis-URL des aufrufenden Skripts.

protocols Optional

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

Ein einzelner Server kann mehrere WebSocket-Unterprotokolle implementieren und verschiedene Arten von Interaktionen in Abhängigkeit vom angegebenen Wert behandeln. Beachten Sie jedoch, dass nur ein Unterprotokoll pro Verbindung ausgewählt werden kann.

Die erlaubten Werte sind jene, die im Sec-WebSocket-Protocol HTTP-Header angegeben werden können. Diese sind Werte, die aus dem IANA WebSocket Subprotocol Name Registry ausgewählt werden, wie soap, wamp, ship und so weiter, oder es kann ein benutzerdefinierter Name sein, der zwischen Client und Server gemeinsames Verständnis hat.

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

Ausnahmen

SyntaxError DOMException

Wird ausgelöst, wenn:

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

Beispiele

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

Der unten stehende Code zeigt, wie wir eine Verbindung zu einem Socket unter Verwendung einer URL mit dem wss-Schema herstellen können:

js
const wssWebSocket = new WebSocket('wss://websocket.example.org');
console.log(wssWebSocket.url); // 'wss://websocket.example.org'
... // Do something with socket
wssWebSocket.close();

Der Code zur Verbindung mit einer HTTPS-URL ist nahezu der gleiche. Im Hintergrund löst der Browser dies zu einer "WSS"-Verbindung auf, sodass die WebSocket.url das Schema "wss:" haben wird.

js
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 Kontextes ab, in dem sie aufgerufen wird.

js
relativeWebSocket = new WebSocket('/local/url');
... // Do something with socket
relativeWebSocket.close();

Spezifikationen

Specification
WebSockets
# ref-for-dom-websocket-websocket①

Browser-Kompatibilität

Siehe auch

  • RFC 6455 (die WebSocket-Protokollspezifikation)