Window.frames — Eigenschaft · JavaScript-Referenz

Signatur

get Window.frames

Beschreibung

window.frames ist eine schreibgeschützte Eigenschaft, die dasselbe Objekt wie window zurückgibt. Es gilt also window.frames === window. Das Fensterobjekt verhält sich dabei wie eine Liste: Über einen numerischen Index (frames[0], frames[1] …) erreichst du das WindowProxy-Objekt jedes direkten Unter-Frames. frames.length ist dasselbe wie window.length und gibt die Anzahl dieser Frames an.

Gezählt werden nur direkte Kinder, also <iframe>-, <frame>-, <object>- und <embed>-Elemente mit eigenem Browsing-Kontext, in der Reihenfolge, in der sie im Dokument stehen. Verschachtelte Frames erreichst du über frames[0].frames[0]. Du kannst Frames auch über ihren name-Wert ansprechen, z. B. frames["vorschau"].

Nützlich ist die Eigenschaft vor allem, wenn du Nachrichten an eingebettete Fenster schicken willst (postMessage), alle Frames durchlaufen möchtest oder bei gleichem Ursprung (same-origin) direkt auf das Dokument eines Frames zugreifen willst. Du bekommst hier Fensterobjekte zurück, keine DOM-Elemente. Das zugehörige <iframe>-Element findest du über document.querySelectorAll("iframe") bzw. aus Sicht des Frames über window.frameElement.

Rückgabewert

Typ

WindowProxy

Beschreibung

Das aktuelle Fensterobjekt selbst (window.frames === window). Mit einem Index oder Namen darauf zugreifen liefert das WindowProxy des jeweiligen Unter-Frames oder undefined, wenn es keinen passenden Frame gibt.

Beispiele

Alle direkten Frames durchlaufen

// Seite mit zwei <iframe>-Elementen
console.log(window.frames === window); // gleiches Objekt
console.log(`Anzahl Frames: ${frames.length}`);

for (let i = 0; i < frames.length; i++) {
  const frameWin = frames[i];
  try {
    // Funktioniert nur, wenn der Frame denselben Ursprung hat
    console.log(i, frameWin.location.href);
  } catch (err) {
    console.log(i, 'Fremder Ursprung – kein Zugriff');
  }
}

true Anzahl Frames: 2 0 https://example.com/widget.html 1 Fremder Ursprung – kein Zugriff

Nachricht an alle eingebetteten Frames senden

// Theme-Wechsel an alle Widgets weitergeben
const broadcastTheme = (theme) => {
  Array.from({ length: frames.length }, (_, i) => frames[i])
    .forEach((win) => win.postMessage({ type: 'theme', theme }, 'https://widgets.example.com'));
};

broadcastTheme('dark');

Frame über name ansprechen und Frame-Element finden

// <iframe name="vorschau" src="/preview.html"></iframe>
const iframe = document.querySelector('iframe[name="vorschau"]');

iframe.addEventListener('load', () => {
  const vorschau = frames['vorschau'];
  console.log(vorschau === iframe.contentWindow);
  // Same-origin: direkter DOM-Zugriff möglich
  console.log(vorschau.document.title);
});

true Vorschau

// Wichtig · Fallstricke

Kein echtes Array: frames hat weder forEach noch map. Array.from(frames) klappt nicht zuverlässig, weil window nicht iterierbar ist. Benutze eine Zählschleife mit frames.length oder Array.from({ length: frames.length }, (_, i) => frames[i]).
Same-Origin-Policy: Bei Frames mit fremdem Ursprung wirft der Zugriff auf document, location.href usw. einen SecurityError. Nur wenige Dinge wie postMessage(), location neu setzen oder close() sind erlaubt. Gib bei postMessage immer einen konkreten Ziel-Ursprung statt "*" an und prüfe beim Empfangen event.origin.
Ladezeitpunkt: Ein Frame taucht in frames erst auf, wenn er im DOM hängt. Sein Inhalt ist aber vielleicht noch nicht geladen. Warte deshalb auf das load-Event des <iframe>.
Die Reihenfolge folgt der Dokumentreihenfolge. Wenn du Frames per DOM-Manipulation einfügst oder entfernst, verschieben sich die Indizes.
Das Attribut sandbox kann den Zugriff auch bei gleichem Ursprung einschränken (ohne allow-same-origin gilt der Frame als fremder Ursprung).
Die Eigenschaft wird von allen Browsern unterstützt. <frame>/<frameset> sind in HTML5 veraltet, heute nutzt man <iframe>.

Siehe auch

Window.length Window.parent Window.top Window.frameElement HTMLIFrameElement.contentWindow Window.postMessage() TextTrackCue.id