Window.frameElement — Eigenschaft · JavaScript-Referenz

Signatur

Window.frameElement

Beschreibung

window.frameElement ist eine schreibgeschützte Eigenschaft. Sie gibt das Element im übergeordneten Dokument zurück, das das aktuelle Browsing-Kontext-Fenster einbettet – typischerweise ein <iframe>, seltener ein <object>, <embed> oder ein veraltetes <frame>. Über dieses Element kann ein eingebettetes Dokument z. B. seine eigene Größe anpassen, Attribute wie data-* auslesen oder sich selbst ausblenden.

Wird die Seite nicht eingebettet (Top-Level-Fenster), ist der Wert null. Ebenfalls null ist er, wenn das übergeordnete Dokument einen anderen Ursprung (Origin) hat: Aus Sicherheitsgründen gibt der Browser das Element nur bei gleicher Herkunft (Same-Origin) heraus. Eine Ausnahme wird dabei nicht geworfen.

Für die reine Frage „Laufe ich in einem Frame?“ ist window.self !== window.top zuverlässiger, weil es auch bei fremdem Ursprung funktioniert. frameElement ist dann sinnvoll, wenn man tatsächlich auf das einbettende DOM-Element zugreifen möchte.

Rückgabewert

Typ

Element | null

Beschreibung

Das einbettende Element (meist HTMLIFrameElement, ggf. HTMLObjectElement, HTMLEmbedElement oder HTMLFrameElement) oder null, wenn das Fenster nicht eingebettet ist oder der Eltern-Ursprung abweicht.

Beispiele

Prüfen, ob die Seite in einem Same-Origin-iframe läuft

// Im eingebetteten Dokument ausführen
const host = window.frameElement;

if (host) {
  console.log(`Eingebettet in <${host.tagName.toLowerCase()}> mit id="${host.id}"`);
} else if (window.self !== window.top) {
  console.log('Eingebettet, aber Eltern-Ursprung ist fremd');
} else {
  console.log('Top-Level-Fenster');
}

Eingebettet in <iframe> mit id="vorschau"

iframe-Höhe automatisch an den Inhalt anpassen

// Im Kind-Dokument (gleicher Ursprung wie Elternseite)
const resizeHost = () => {
  const frame = window.frameElement;
  if (!frame) return;
  frame.style.height = `${document.documentElement.scrollHeight}px`;
};

window.addEventListener('load', resizeHost);
new ResizeObserver(resizeHost).observe(document.body);

Konfiguration aus data-Attributen des iframes lesen

// Elternseite: <iframe src="widget.html" data-theme="dark" data-lang="de"></iframe>
// Im Widget:
const { theme = 'light', lang = 'en' } = window.frameElement?.dataset ?? {};
document.documentElement.dataset.theme = theme;
document.documentElement.lang = lang;
console.log(theme, lang);

dark de

// Wichtig · Fallstricke

Cross-Origin: Bei abweichendem Ursprung des Elterndokuments liefert frameElement stillschweigend null – nicht verwechseln mit „nicht eingebettet“. Für die Frame-Erkennung window.self !== window.top verwenden; für Kommunikation über Ursprungsgrenzen hinweg window.postMessage() nutzen.
Sandbox: Ein <iframe sandbox> ohne allow-same-origin erhält einen opaken Ursprung; frameElement ist dann ebenfalls null.
Sicherheit: Wer Zugriff auf frameElement hat, kann das Elterndokument über frameElement.ownerDocument vollständig manipulieren. Nur Same-Origin-Inhalte einbetten, denen man vertraut.
Schreibgeschützt: Eine Zuweisung hat keine Wirkung (im Strict Mode kein Fehler, da Getter ohne Setter auf dem Prototyp – Zuweisung wird ignoriert bzw. wirft je nach Kontext).
Im Top-Level-Fenster und in Web Workern (dort gibt es kein window) nicht sinnvoll nutzbar. Von allen modernen Browsern unterstützt.

Siehe auch

Window.parent Window.top Window.frames Window.postMessage() HTMLIFrameElement.contentWindow HTMLIFrameElement VideoFrame.flip