HTMLIFrameElement.contentWindow — Eigenschaft · JavaScript-Referenz

Signatur

get HTMLIFrameElement.contentWindow

Beschreibung

Die schreibgeschützte Eigenschaft contentWindow liefert das Browsing-Kontext-Fenster eines <iframe>-Elements. Darüber erreichen Sie das eingebettete Dokument als eigenständiges Window, z. B. um Nachrichten per postMessage() zu senden, die Navigation zu steuern oder bei gleicher Herkunft (Same-Origin) direkt auf document, globale Variablen und Funktionen des Frames zuzugreifen.

Ist das iframe nicht im DOM eingehängt, gibt die Eigenschaft null zurück. Sobald das Element in ein Dokument eingefügt wird, entsteht ein Browsing-Kontext – zunächst mit einem leeren about:blank-Dokument, das nach dem Laden der eigentlichen src ersetzt wird. Deshalb sollten Sie auf das load-Event warten, bevor Sie mit dem Inhalt arbeiten.

Bei fremder Herkunft (Cross-Origin) greift die Same-Origin-Policy: Sie erhalten zwar ein Fensterobjekt, können aber nur auf wenige Eigenschaften und Methoden zugreifen – etwa postMessage(), location (nur schreibend), close(), focus(), blur(), frames, length, parent, top und opener. Jeder andere Zugriff wirft einen SecurityError (DOMException).

Im Unterschied zu contentDocument, das bei Cross-Origin einfach null liefert, ist contentWindow damit der zentrale Einstiegspunkt für die sichere, herkunftsübergreifende Kommunikation mit eingebetteten Inhalten.

Rückgabewert

Typ

WindowProxy | null

Beschreibung

Das Window-Objekt des eingebetteten Browsing-Kontexts oder null, wenn das iframe nicht in einem Dokument eingehängt ist.

Beispiele

Nachricht an ein Cross-Origin-iframe senden

const frame = document.querySelector('#payment-frame');

frame.addEventListener('load', () => {
  // Ziel-Origin immer explizit angeben, nie '*'
  frame.contentWindow.postMessage(
    { type: 'init', amount: 49.9 },
    'https://pay.example.com'
  );
});

// Antwort aus dem iframe empfangen
window.addEventListener('message', (event) => {
  if (event.origin !== 'https://pay.example.com') return;
  if (event.source !== frame.contentWindow) return;
  console.log('Antwort:', event.data);
});

Antwort: { status: 'ready' }

Same-Origin: Funktion und DOM im iframe nutzen

const frame = document.createElement('iframe');
console.log(frame.contentWindow); // noch nicht im DOM

frame.src = '/widgets/chart.html'; // gleiche Herkunft
document.body.append(frame);

frame.addEventListener('load', () => {
  const win = frame.contentWindow;
  console.log(win.document.title);
  // Globale Funktion im iframe aufrufen (falls definiert)
  win.renderChart?.([3, 7, 2]);
});

null Umsatz-Diagramm

Cross-Origin-Zugriff sicher abfangen

const frame = document.querySelector('iframe[src^="https://video.example.org"]');

const canReadDocument = (iframe) => {
  try {
    // Wirft bei fremder Herkunft einen SecurityError
    return Boolean(iframe.contentWindow.document);
  } catch (err) {
    console.warn(err.name);
    return false;
  }
};

console.log(canReadDocument(frame));

SecurityError false

Frame drucken oder fokussieren

const printFrame = document.querySelector('#invoice-frame');

document.querySelector('#print-btn').addEventListener('click', () => {
  const win = printFrame.contentWindow;
  win.focus();
  win.print(); // nur bei gleicher Herkunft erlaubt
});

// Wichtig · Fallstricke

Timing: Direkt nach dem Einfügen enthält contentWindow ein vorläufiges about:blank-Dokument. Zugriffe vor dem load-Event landen oft im falschen Dokument oder gehen verloren.
Nicht eingehängt = null: Wird das iframe aus dem DOM entfernt, wird der Browsing-Kontext zerstört; gespeicherte Referenzen zeigen danach auf ein totes Fenster. Beim erneuten Einhängen wird der Inhalt neu geladen.
Sicherheit bei postMessage(): Geben Sie immer eine konkrete Ziel-Origin statt '*' an, sonst können sensible Daten an eine nachträglich umgeleitete Seite gelangen. Prüfen Sie eingehende Nachrichten stets per event.origin und idealerweise event.source === frame.contentWindow.
Same-Origin-Policy: Zugriffe auf document, globale Variablen o. Ä. über Herkunftsgrenzen werfen einen SecurityError. Das sandbox-Attribut ohne allow-same-origin macht auch eigene Inhalte zu einer opaken Herkunft.
XSS-Risiko: Bei gleicher Herkunft hat das iframe umgekehrt über parent/top vollen Zugriff auf die Elternseite. Nicht vertrauenswürdige Inhalte daher nur mit sandbox einbetten.
Die Eigenschaft wird in allen modernen Browsern unterstützt; instanceof Window schlägt für Frame-Fenster fehl, da jedes Fenster eigene globale Konstruktoren besitzt.

Siehe auch

Window Window.parent HTMLIFrameElement.credentialless HTMLIFrameElement.contentDocument HTMLIFrameElement.loading