WissensdatenbankPrüfungszentrum
DEDeutsch
Sprache wählen13

CKTIS / JavaScript

window.postMessage — Nachrichten zwischen Fenstern

window.postMessage sendet Daten asynchron an ein Zielfenster, auch über verschiedene Origins hinweg. Gib vorzugsweise ein genaues `targetOrigin` an. Ohne diese Angabe ist die Zustellung auf denselben Origin beschränkt. Empfänger sollten den Origin des Senders, das sendende Fenster und die Datenstruktur prüfen.

Version: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Syntax

targetWindow.postMessage(message, targetOrigin[, transfer])
targetWindow.postMessage(message[, { targetOrigin, transfer }])

window.postMessage ist eine Browser-API des HTML Living Standard und keine Funktion einer bestimmten ECMAScript-Ausgabe. Aktuelle Browser-Engines unterstützen sie; die Anwesenheit von Node 24 in einem Repository belegt ihre Verfügbarkeit nicht. Rufe die Methode auf dem Empfangsfenster auf, zum Beispiel iframe.contentWindow oder einer Referenz auf ein geöffnetes Fenster. Das Senden von Nachrichten gewährt keinen Zugriff auf das DOM eines anderen Origins.

Der Empfänger erhält asynchron ein message-Ereignis: event.data enthält die Daten, event.origin enthält den serialisierten Origin des Senders zum Zeitpunkt des Sendens und event.source verweist auf das sendende Fenster. Ein Tupel-Origin wird durch Schema, Host und Port bestimmt, nicht durch den Pfad. Ein opaker Origin hat kein solches Tupel und wird als Zeichenfolge "null" serialisiert. Die Prüfung dieser Zeichenfolge allein kann opake Origins nicht voneinander unterscheiden. Registriere den Listener vor dem Senden; stimme bei einem neu erstellten Frame die Bereitschaft des Empfängers ab.

Gib ein genaues targetOrigin an. Stimmen die Origins nicht überein, wird die Nachricht verworfen. In der Form mit einem Optionsobjekt hat ein ausgelassenes targetOrigin den Standardwert "/" und beschränkt die Zustellung auf denselben Origin. "*" erlaubt jeden Origin — verwende es nicht für vertrauliche Daten. Empfänger sollten event.origin, event.source und die Datenstruktur prüfen und Nachrichten niemals als Code behandeln.

Daten werden per Structured-Clone-Algorithmus serialisiert, nicht als JSON. Funktionen lassen sich nicht klonen. Die transfer-Liste verschiebt Ressourcen, statt sie zu kopieren: Ein übertragener ArrayBuffer wird auf der Senderseite abgetrennt. Nicht klonierbare Daten oder doppelte Einträge in der Transferliste können einen DataCloneError verursachen. Im Beispiel sendet ein iframe in einer Sandbox mit window.parent.postMessage eine Nachricht an sein übergeordnetes Fenster. Dieses prüft, ob event.origin den Wert "null" hat und event.source auf das Fenster des iframes verweist. Anschließend prüft es die Daten und gibt received: 42 in der Konsole aus.

Beispiele

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Send a message from an iframe</title>
</head>
<body>
  <script>
    const frame = document.createElement('iframe');
    frame.title = 'Message sender';
    frame.hidden = true;
    frame.setAttribute('sandbox', 'allow-scripts');

    // Use the page's exact origin when it has an HTTP(S) origin.
    // The wildcard fallback carries only the fixed, non-sensitive fixture.
    const targetOrigin = /^https?:\/\//.test(window.origin) ? window.origin : '*';

    function receive(event) {
      // The sandboxed sender has an opaque origin, serialized as "null".
      if (event.origin !== 'null' || event.source !== frame.contentWindow) return;
      const data = event.data;
      if (data === null || typeof data !== 'object' || Array.isArray(data)) return;
      if (data.type !== 'cktis-demo' || data.value !== 42) return;

      window.removeEventListener('message', receive);
      console.log(`received: ${data.value}`);
    }

    window.addEventListener('message', receive);
    frame.srcdoc = `<!doctype html>
<html lang="en">
<head><meta charset="utf-8"><title>Message sender</title></head>
<body>
  <script>
    window.parent.postMessage({ type: 'cktis-demo', value: 42 }, ${JSON.stringify(targetOrigin)});
  <\/script>
</body>
</html>`;
    document.body.append(frame);
  </script>
</body>
</html>

Ergebnis

received: 42

Der angezeigte Code und das angegebene Ergebnis wurden in einer isolierten Umgebung mit der im Prüfnachweis für genau diese Version dokumentierten Methode verifiziert.

Quellen