WebSocket: message — Ereignis · JavaScript-Referenz

Signatur

webSocket.addEventListener("message", handler)

Beschreibung

Das message-Ereignis ist der zentrale Empfangskanal einer WebSocket-Verbindung. Jedes Mal, wenn der Server einen vollständigen Nachrichtenrahmen sendet, erhält der Handler ein MessageEvent. Die Nutzdaten stehen in event.data.

Den Handler registrieren Sie entweder über socket.addEventListener("message", handler) oder über die Eigenschaft socket.onmessage = handler. Mit addEventListener sind mehrere Handler möglich und sie lassen sich per removeEventListener gezielt wieder entfernen. Bei onmessage gibt es nur einen Handler, den eine neue Zuweisung ersetzt.

Welchen Typ event.data hat, hängt von der Nachricht ab:

Textnachrichten kommen immer als string an, JSON-Daten müssen Sie also selbst mit JSON.parse() umwandeln.
Binärnachrichten kommen je nach socket.binaryType als Blob (Standard) oder als ArrayBuffer an.

Das Ereignis steigt nicht auf (bubbelt nicht) und lässt sich nicht abbrechen. Nachrichten kommen in der Reihenfolge an, in der der Server sie gesendet hat.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname, hier immer `"message"`.
$handler Pflicht	(event: MessageEvent) => void		Callback, der für jede empfangene Nachricht ein `MessageEvent` erhält. Wichtige Eigenschaften: `data` (Nutzdaten: `string`, `Blob` oder `ArrayBuffer`) und `origin` (Herkunft des Servers).
$options	boolean \| AddEventListenerOptions	false	Optionen wie `once` (Handler nur einmal ausführen) oder `signal` (Handler per `AbortSignal` entfernen).

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler erhält ein MessageEvent, sein Rückgabewert wird ignoriert.

Beispiele

JSON-Nachrichten mit addEventListener empfangen

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

socket.addEventListener("open", () => {
  socket.send(JSON.stringify({ type: "chat", text: "Hallo Server!" }));
});

socket.addEventListener("message", (event) => {
  // Textnachrichten sind immer Strings
  if (typeof event.data !== "string") return;
  try {
    const msg = JSON.parse(event.data);
    console.log(`[${msg.type}] ${msg.text}`);
  } catch {
    console.log("Kein JSON:", event.data);
  }
});

[chat] Hallo Server!

onmessage-Eigenschaft und Handler wieder entfernen

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

// Variante 1: on-Property (ersetzt vorherige Zuweisungen)
socket.onmessage = (event) => console.log("onmessage:", event.data);

// Variante 2: benannter Handler, später entfernbar
const logOnce = (event) => {
  console.log("Erste Nachricht:", event.data);
  socket.removeEventListener("message", logOnce);
};
socket.addEventListener("message", logOnce);

socket.onopen = () => {
  socket.send("eins");
  socket.send("zwei");
};

// Aufräumen: onmessage deaktivieren
// socket.onmessage = null;

onmessage: eins Erste Nachricht: eins onmessage: zwei

Binärdaten als ArrayBuffer verarbeiten

const socket = new WebSocket("wss://echo.websocket.org");
socket.binaryType = "arraybuffer"; // statt Standard "blob"

socket.addEventListener("open", () => {
  socket.send(new Uint8Array([1, 2, 3, 255]));
});

socket.addEventListener("message", (event) => {
  if (event.data instanceof ArrayBuffer) {
    const bytes = new Uint8Array(event.data);
    console.log("Bytes:", [...bytes]);
  } else {
    console.log("Text:", event.data);
  }
});

Bytes: [1, 2, 3, 255]

Handler mit AbortController entfernen

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

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

// z. B. beim Verlassen einer Ansicht
setTimeout(() => {
  controller.abort(); // Handler wird entfernt
  socket.close(1000, "Ansicht geschlossen");
}, 5000);

// Wichtig · Fallstricke

Datentyp prüfen: Ist binaryType nicht gesetzt, kommen Binärdaten als Blob an. Um sie auszulesen, brauchen Sie await event.data.arrayBuffer() oder await event.data.text(), dabei kann sich aber die Verarbeitungsreihenfolge ändern. Für geordnete Binärverarbeitung sollten Sie binaryType = "arraybuffer" setzen.
Sicherheit: Behandeln Sie empfangene Daten immer als nicht vertrauenswürdig. Geben Sie sie nie ungeprüft per innerHTML aus (XSS-Gefahr), sondern nutzen Sie textContent. Umschließen Sie JSON.parse() mit try/catch und prüfen Sie die Struktur der Daten. Nutzen Sie in Produktion wss://, denn Browser blockieren ws:// auf HTTPS-Seiten als Mixed Content.
Kein Gegendruck (Backpressure): Sendet der Server schneller, als der Handler die Nachrichten verarbeitet, stauen sie sich im Speicher. Aufwendige Arbeit sollten Sie in einen Web Worker auslagern oder die Nachrichten bündeln. Die neuere WebSocketStream-API bietet Gegendruck, ist aber noch nicht in allen Browsern verfügbar.
Zeitpunkt der Registrierung: Registrieren Sie den Handler direkt nach new WebSocket() im selben synchronen Codeblock, damit keine frühen Nachrichten verloren gehen.
Kompatibilität: Das Ereignis wird von allen modernen Browsern unterstützt, außerdem ab Node.js 22 durch den globalen WebSocket-Client. In Web Workern ist es ebenfalls verfügbar.

Siehe auch

WebSocket MessageEvent WebSocket.prototype.send() WebSocket.binaryType EventTarget.prototype.addEventListener() WakeLockSentinel: release