HTMLIFrameElement.contentDocument — Eigenschaft · JavaScript-Referenz

Signatur

HTMLIFrameElement.contentDocument

Beschreibung

Die schreibgeschützte Eigenschaft contentDocument gibt das aktive Document im eingebetteten Browsing-Kontext eines <iframe> zurück. Darüber kann das übergeordnete Dokument das DOM des Frames direkt lesen und ändern, z. B. Elemente abfragen, Stile einfügen oder Inhalte dynamisch erzeugen.

Das funktioniert nur, wenn beide Dokumente denselben Ursprung (Same Origin: Protokoll, Host und Port) haben. Bei fremdem Ursprung oder wenn gar kein Dokument vorhanden ist, liefert die Eigenschaft null. Einen Fehler wirft sie dabei nicht. Für Kommunikation über Ursprungsgrenzen hinweg ist window.postMessage() der richtige Weg.

Die Eigenschaft ist gleichwertig mit iframe.contentWindow.document, nur kürzer. Das DOM des Frames sollte man erst nach dem load-Ereignis des iframes anfassen. Vorher kann contentDocument noch auf ein vorläufiges, leeres about:blank-Dokument zeigen, das beim Laden der eigentlichen Seite ersetzt wird.

Rückgabewert

Typ

Document | null

Beschreibung

Das aktive Document des iframes bei gleichem Ursprung. null, wenn der Ursprung abweicht, das iframe nicht im DOM hängt oder kein Browsing-Kontext existiert.

Beispiele

Inhalt eines Same-Origin-iframes nach dem Laden auslesen

const frame = document.querySelector('#vorschau');

frame.addEventListener('load', () => {
  const doc = frame.contentDocument;
  if (!doc) {
    console.warn('Kein Zugriff – vermutlich fremder Ursprung');
    return;
  }
  const titel = doc.querySelector('h1')?.textContent;
  console.log('Überschrift im Frame:', titel);
});

frame.src = '/hilfe/einleitung.html';

Überschrift im Frame: Einleitung

Leeres iframe dynamisch befüllen (z. B. als Druckvorschau)

const frame = document.createElement('iframe');
document.body.append(frame);

// Ein iframe ohne src enthält about:blank mit dem Ursprung der Elternseite
const doc = frame.contentDocument;
doc.body.innerHTML = '<h2>Rechnung Nr. 4711</h2><p>Summe: 99,00 €</p>';

const style = doc.createElement('style');
style.textContent = 'body { font-family: serif; }';
doc.head.append(style);

console.log(doc.body.children.length);

2

Cross-Origin-Zugriff erkennen

const frame = document.createElement('iframe');
frame.src = 'https://example.org/';
document.body.append(frame);

frame.addEventListener('load', () => {
  console.log(frame.contentDocument);          // fremder Ursprung
  console.log(frame.contentWindow !== null);   // Window-Proxy gibt es trotzdem
  frame.contentWindow.postMessage({ typ: 'ping' }, 'https://example.org');
});

null true

Höhe des iframes an seinen Inhalt anpassen

const passeHoeheAn = (frame) => {
  const doc = frame.contentDocument;
  if (!doc) return;
  frame.style.height = `${doc.documentElement.scrollHeight}px`;
};

const frame = document.querySelector('#artikel');
frame.addEventListener('load', () => passeHoeheAn(frame));

// Wichtig · Fallstricke

Same-Origin-Policy: Bei fremdem Ursprung ist der Wert null, es wird keine Ausnahme ausgelöst. Deshalb vor jedem Zugriff auf null prüfen. Zugriffe über contentWindow.document werfen dagegen einen SecurityError.
Zeitpunkt: Vor dem load-Ereignis kann ein vorläufiges about:blank-Dokument zurückkommen, das später ersetzt wird. Event-Listener oder Änderungen daran gehen dann verloren.
sandbox: Hat ein iframe das Attribut sandbox ohne allow-same-origin, bekommt sein Inhalt einen eigenen, undurchsichtigen Ursprung. contentDocument ist dann auch bei gleicher URL null.
document.domain zum Lockern der Same-Origin-Prüfung ist veraltet und wird von modernen Browsern zunehmend ignoriert. Besser postMessage() verwenden.
Sicherheit: Wer HTML per innerHTML in das Frame-Dokument schreibt, riskiert XSS genauso wie im Hauptdokument, weil der Code dort mit demselben Ursprung läuft. Nicht vertrauenswürdige Eingaben immer bereinigen, oder srcdoc zusammen mit sandbox nutzen.
Wird von allen aktuellen Browsern unterstützt. Ab IE 8 war die Eigenschaft ebenfalls vorhanden.

Siehe auch

Document HTMLIFrameElement.credentialless HTMLIFrameElement.contentWindow HTMLIFrameElement.privateToken HTMLIFrameElement.loading