HTMLIFrameElement — Schnittstelle · JavaScript-Referenz

Signatur

interface HTMLIFrameElement extends HTMLElement

Beschreibung

HTMLIFrameElement ist die DOM-Schnittstelle für <iframe>-Elemente. Sie erbt alle Eigenschaften und Methoden von HTMLElement und ergänzt sie um iframe-spezifische Eigenschaften wie src, srcdoc, name, width, height, allow, sandbox, referrerPolicy und loading.

Die wichtigsten Einstiegspunkte ins eingebettete Dokument sind contentWindow (das Window-Objekt des Rahmens) und contentDocument (das Document, nur bei gleichem Ursprung zugänglich). Über contentWindow.postMessage() kommuniziert man auch ursprungsübergreifend sicher mit eingebetteten Inhalten.

Typische Einsatzfälle sind das Einbetten von Drittanbieter-Inhalten (Videos, Karten, Bezahlformulare), das isolierte Rendern nutzergenerierter HTML-Inhalte über srcdoc plus sandbox sowie Vorschaufenster in Editoren. Mit loading="lazy" lässt sich das Laden bis zum Sichtbarwerden verzögern.

Die Eigenschaft sandbox ist eine DOMTokenList, mit der Rechte (allow-scripts, allow-forms, allow-same-origin usw.) gezielt freigeschaltet werden. allow steuert die Permissions Policy (z. B. camera, fullscreen).

Parameter

Name	Typ	Default	Beschreibung
$src	string	""	URL des einzubettenden Dokuments. Das Setzen löst eine Navigation des Rahmens aus.
$srcdoc	string	""	Inline-HTML, das anstelle von `src` gerendert wird (hat Vorrang).
$sandbox	DOMTokenList		Einschränkungen für den Inhalt; leere Liste bei gesetztem Attribut = maximale Einschränkung.
$allow	string	""	Permissions-Policy, z. B. `"fullscreen; camera"`.
$loading	"eager" \| "lazy"	"eager"	Steuert verzögertes Laden des Rahmens.
$referrerPolicy	string	""	Referrer-Richtlinie für Anfragen des Rahmens, z. B. `"no-referrer"`.
$name	string	""	Name des Browsing-Kontexts, nutzbar als `target` für Links und Formulare.
$width / height	string	""	Abmessungen in CSS-Pixeln als Zeichenkette (spiegelt die HTML-Attribute).
$contentWindow	WindowProxy \| null		Nur lesend: Fenster-Objekt des eingebetteten Dokuments; `null`, wenn nicht im DOM.
$contentDocument	Document \| null		Nur lesend: Dokument des Rahmens; `null` bei fremdem Ursprung.

Rückgabewert

Typ

HTMLIFrameElement

Beschreibung

Instanzen entstehen über document.createElement("iframe") oder durch Abfrage vorhandener <iframe>-Elemente.

Beispiele

iframe dynamisch erzeugen und lazy laden

const frame = document.createElement('iframe');
frame.src = 'https://www.example.com/karte';
frame.width = '600';
frame.height = '400';
frame.loading = 'lazy';
frame.title = 'Standortkarte'; // Barrierefreiheit
frame.referrerPolicy = 'no-referrer';
frame.allow = 'fullscreen';

frame.addEventListener('load', () => {
  console.log('iframe geladen:', frame.src);
});

document.body.append(frame);
console.log(frame instanceof HTMLIFrameElement);

true iframe geladen: https://www.example.com/karte

Nutzer-HTML sicher in Sandbox rendern

const preview = document.createElement('iframe');
// Nur Skripte erlauben, KEIN allow-same-origin
preview.sandbox.add('allow-scripts');
preview.srcdoc = `<h1>Vorschau</h1><script>document.body.append(' – Skript läuft')<\/script>`;
document.body.append(preview);

console.log(preview.sandbox.contains('allow-same-origin'));
console.log(preview.contentDocument); // opaker Ursprung -> kein Zugriff

false null

Mit postMessage ursprungsübergreifend kommunizieren

const frame = document.querySelector('#payment');
const ZIEL = 'https://pay.example.com';

frame.addEventListener('load', () => {
  frame.contentWindow.postMessage({ typ: 'init', betrag: 49.9 }, ZIEL);
});

window.addEventListener('message', (event) => {
  if (event.origin !== ZIEL) return; // Absender prüfen!
  console.log('Antwort aus dem iframe:', event.data);
});

Antwort aus dem iframe: { status: 'bereit' }

Auf gleich-originiges iframe-Dokument zugreifen

const frame = document.querySelector('iframe[src="/hilfe.html"]');
frame.addEventListener('load', () => {
  const doc = frame.contentDocument;
  // Höhe an Inhalt anpassen
  frame.style.height = `${doc.documentElement.scrollHeight}px`;
  console.log(doc.title);
});

Hilfe

// Wichtig · Fallstricke

Same-Origin-Policy: contentDocument liefert bei fremdem Ursprung null; Zugriffe auf contentWindow.document werfen einen SecurityError. Für Kommunikation postMessage() nutzen und im Empfänger immer event.origin prüfen, beim Senden nie "*" als Ziel verwenden, wenn Daten sensibel sind.
Sandbox-Falle: Die Kombination allow-scripts + allow-same-origin bei gleichem Ursprung hebt die Sandbox praktisch auf – das eingebettete Skript kann das sandbox-Attribut selbst entfernen.
XSS: srcdoc mit ungefiltertem Nutzer-HTML nur zusammen mit sandbox verwenden. Die eigene Seite schützt man vor Einbettung durch Dritte (Clickjacking) per Content-Security-Policy: frame-ancestors bzw. X-Frame-Options.
Das load-Event feuert auch für about:blank; ein bereits geladener Rahmen löst es beim Anhängen eines Listeners nicht erneut aus. Beim Verschieben im DOM wird der Rahmen neu geladen.
contentWindow ist null, solange das Element nicht im Dokument hängt.
Veraltete Eigenschaften wie align, frameBorder, scrolling, marginWidth, longDesc nicht mehr verwenden – stattdessen CSS. loading="lazy" ist in allen modernen Browsern verfügbar, in älteren Safari-Versionen (< 16.4) jedoch nicht.
Für Barrierefreiheit stets ein aussagekräftiges title-Attribut setzen.

Siehe auch

Window Document HTMLImageElement HTMLParamElement HTMLBaseElement