MessageEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface MessageEvent extends Event

Beschreibung

MessageEvent ist der Ereignistyp, den der Browser bei allen nachrichtenbasierten Kommunikationskanälen auslöst. Dazu gehören window.postMessage() (Kommunikation zwischen Fenstern und iframes), Web Workers, MessagePort/MessageChannel, BroadcastChannel, WebSocket, EventSource (Server-Sent Events) und RTCDataChannel. Das Ereignis heißt fast immer message. Bei Fehlern beim Deserialisieren wird stattdessen messageerror ausgelöst.

Die wichtigsten schreibgeschützten Eigenschaften sind:

data: die eigentliche Nutzlast. Sie kann jeden Wert enthalten, den der Structured-Clone-Algorithmus verarbeiten kann, also Objekte, Arrays, Map, Blob, ArrayBuffer usw. Bei WebSockets ist es ein String, Blob oder ArrayBuffer.
origin: der Ursprung des Absenders (z. B. "https://example.com"). Diesen Wert muss man unbedingt prüfen.
lastEventId: die letzte Ereignis-ID (nur bei Server-Sent Events).
source: eine Referenz auf den Absender (WindowProxy, MessagePort oder ServiceWorker), über die man antworten kann.
ports: ein Array von MessagePort-Objekten, die zusammen mit der Nachricht übertragen wurden.

Normalerweise erzeugt man MessageEvent nicht selbst, sondern empfängt es in einem Event-Listener. Mit dem Konstruktor new MessageEvent(type, init) kann man aber eigene Ereignisse erstellen, etwa für Tests oder um Nachrichten zu simulieren.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, üblicherweise `"message"` (Konstruktor-Parameter).
$init.data	any	null	Die Nutzlast der Nachricht.
$init.origin	string	""	Ursprung des Absenders.
$init.lastEventId	string	""	Letzte Ereignis-ID (Server-Sent Events).
$init.source	WindowProxy\|MessagePort\|ServiceWorker\|null	null	Referenz auf den Absender der Nachricht.
$init.ports	MessagePort[]	[]	Mitgeschickte `MessagePort`-Objekte.
$init.bubbles / init.cancelable	boolean	false	Standard-Optionen von `EventInit`.

Rückgabewert

Typ

MessageEvent

Beschreibung

Eine neue MessageEvent-Instanz (beim Konstruktor-Aufruf).

Beispiele

Nachricht aus einem iframe sicher empfangen

const ERLAUBTER_URSPRUNG = 'https://widget.example.com';

const onMessage = (event) => {
  // Ursprung IMMER prüfen
  if (event.origin !== ERLAUBTER_URSPRUNG) return;

  const { typ, hoehe } = event.data ?? {};
  if (typ === 'resize') {
    document.querySelector('#widget').style.height = `${hoehe}px`;
    // Über event.source antworten
    event.source.postMessage({ typ: 'ack' }, event.origin);
  }
};

window.addEventListener('message', onMessage);
// Später aufräumen:
// window.removeEventListener('message', onMessage);

Kommunikation mit einem Web Worker

// main.js
const worker = new Worker('rechner.js');

worker.onmessage = (event) => {
  console.log('Ergebnis:', event.data.summe);
};
worker.onmessageerror = (event) => {
  console.error('Nachricht nicht deserialisierbar', event);
};

worker.postMessage({ zahlen: [1, 2, 3, 4] });

// rechner.js
// self.addEventListener('message', (event) => {
//   const summe = event.data.zahlen.reduce((a, b) => a + b, 0);
//   self.postMessage({ summe });
// });

Ergebnis: 10

MessageEvent selbst erzeugen (z. B. für Tests)

const target = new EventTarget();

target.addEventListener('message', (event) => {
  console.log(event instanceof MessageEvent, event.data, event.origin);
});

const ev = new MessageEvent('message', {
  data: { text: 'Hallo' },
  origin: 'https://test.local'
});

target.dispatchEvent(ev);

true { text: 'Hallo' } https://test.local

WebSocket-Nachrichten als JSON verarbeiten

const ws = new WebSocket('wss://echo.example.org');

ws.addEventListener('open', () => ws.send(JSON.stringify({ ping: Date.now() })));

ws.addEventListener('message', (event) => {
  if (typeof event.data === 'string') {
    const nachricht = JSON.parse(event.data);
    console.log('Empfangen:', nachricht);
  }
});

Empfangen: { ping: 1718000000000 }

// Wichtig · Fallstricke

Sicherheit: Bei window.postMessage kann jedes Fenster Nachrichten an Ihre Seite senden. Prüfen Sie event.origin deshalb immer gegen eine feste Whitelist, und zwar mit exaktem Vergleich, nicht mit includes() oder startsWith(). Behandeln Sie event.data als nicht vertrauenswürdige Eingabe. Geben Sie die Daten niemals ungeprüft an innerHTML, eval() oder location.href weiter, sonst droht XSS. Beim Antworten geben Sie als Ziel-Ursprung einen konkreten Wert an, nicht "*".

Leeres origin: Bei Workern, MessageChannel und BroadcastChannel ist origin oft ein leerer String und source ist null. Bei Seiten mit undurchsichtigem Ursprung (z. B. file:// oder sandboxed iframes) lautet origin "null".

Structured Clone: Funktionen, DOM-Knoten und Klasseninstanzen (ihr Prototyp geht verloren) lassen sich nicht übertragen. Der Versuch, sie zu senden, wirft beim Absender einen DataCloneError. Übertragbare Objekte wie ArrayBuffer kann man per Transfer-Liste ohne Kopie verschieben.

MessagePort: Wenn Sie addEventListener('message') statt onmessage verwenden, müssen Sie port.start() aufrufen, damit Nachrichten ankommen.

Kompatibilität: MessageEvent wird in allen modernen Browsern unterstützt. In Node.js ist es ab Version 15 global verfügbar.

Siehe auch

Window.postMessage() Worker WebSocket GestureEvent MIDIMessageEvent