WebSocket: open — Ereignis · JavaScript-Referenz

Signatur

webSocket.addEventListener("open", handler)

Beschreibung

Das open-Event eines WebSocket-Objekts signalisiert, dass der Handshake mit dem Server erfolgreich war. Ab jetzt steht readyState auf WebSocket.OPEN (1) und Daten lassen sich mit send() übertragen. Man registriert den Handler entweder mit addEventListener("open", handler) oder über die Eigenschaft onopen.

Typische Aufgaben im Handler sind: eine Anmelde- oder Authentifizierungsnachricht senden, Kanäle abonnieren, Nachrichten aus einer Warteschlange abschicken, die während des Verbindungsaufbaus angefallen sind, und die Oberfläche auf „verbunden“ umstellen. Außerdem ist das der richtige Ort, um einen Zähler für Wiederverbindungsversuche zurückzusetzen.

Das Event ist ein einfaches Event ohne zusätzliche Eigenschaften. Es bubbelt nicht und lässt sich nicht abbrechen. Nach dem Auslösen stehen die vom Server ausgehandelten Werte in socket.protocol (gewähltes Unterprotokoll) und socket.extensions bereit.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Eventname `"open"`.
$handler Pflicht	(event: Event) => void		Callback, der nach dem Verbindungsaufbau aufgerufen wird. Er erhält ein einfaches `Event`, dessen `target` der `WebSocket` ist.
$options	boolean \| AddEventListenerOptions	false	Optionen wie `{ once: true }` oder `{ signal }`, mit denen sich der Listener automatisch entfernen lässt.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler erhält ein Event-Objekt.

Beispiele

Mit addEventListener anmelden und abonnieren

const socket = new WebSocket("wss://echo.websocket.org");

socket.addEventListener("open", (event) => {
  console.log("Verbunden, readyState:", event.target.readyState);
  socket.send(JSON.stringify({ type: "subscribe", channel: "news" }));
});

socket.addEventListener("message", (event) => {
  console.log("Empfangen:", event.data);
});

Verbunden, readyState: 1

Über die Eigenschaft onopen und Listener wieder entfernen

const socket = new WebSocket("wss://echo.websocket.org");

// Variante 1: Eigenschaft (ersetzt einen vorher gesetzten Handler)
socket.onopen = () => console.log("onopen: Verbindung steht");

// Variante 2: benannter Listener, der sich wieder entfernen lässt
const handleOpen = () => {
  console.log("Listener: Verbindung steht");
  socket.removeEventListener("open", handleOpen);
};
socket.addEventListener("open", handleOpen);

// Handler über die Eigenschaft entfernen:
// socket.onopen = null;

onopen: Verbindung steht Listener: Verbindung steht

Verbindung als Promise abwarten und Warteschlange leeren

const connect = (url) =>
  new Promise((resolve, reject) => {
    const socket = new WebSocket(url);
    socket.addEventListener("open", () => resolve(socket), { once: true });
    socket.addEventListener("error", reject, { once: true });
  });

const queue = ["hallo", "welt"];

const main = async () => {
  try {
    const socket = await connect("wss://echo.websocket.org");
    console.log("Unterprotokoll:", socket.protocol || "(keins)");
    while (queue.length) socket.send(queue.shift());
  } catch {
    console.error("Verbindung fehlgeschlagen");
  }
};

main();

Unterprotokoll: (keins)

// Wichtig · Fallstricke

Nicht zu früh senden: Wenn man send() aufruft, bevor open ausgelöst wurde (readyState === 0), wirft der Aufruf eine InvalidStateError-DOMException. Deshalb Nachrichten puffern oder auf das Event warten.
Handler sofort registrieren: Den Listener im selben synchronen Durchlauf wie new WebSocket() anhängen. Das Event wird zwar asynchron ausgelöst, ein Listener, der erst später (z. B. nach einem await) registriert wird, kann es aber verpassen.
Kein erneutes Auslösen: open tritt pro Objekt höchstens einmal auf. Eine Wiederverbindung braucht ein neues WebSocket-Objekt, dessen Handler man erneut registrieren muss.
Fehlschlag: Scheitert der Handshake, kommt kein open, sondern error und danach close.
onopen und addEventListener: Eine Zuweisung an onopen überschreibt einen vorher gesetzten Handler. Mit addEventListener lassen sich dagegen mehrere Listener anhängen.
Sicherheit: Auf HTTPS-Seiten nur wss:// verwenden, denn ws:// wird als Mixed Content blockiert. Zur Authentifizierung keine Geheimnisse in die URL schreiben. Besser ist es, nach open ein kurzlebiges Token als erste Nachricht zu senden. Auf dem Server den Origin-Header prüfen.
Das Event wird von allen modernen Browsern unterstützt. In Node.js gibt es seit Version 22 einen globalen WebSocket-Client.

Siehe auch

WebSocket WebSocket.prototype.send() WebSocket.readyState CloseWatcher: close WebSocket: close