HTMLFrameSetElement — Schnittstelle · JavaScript-Referenz

Signatur

interface HTMLFrameSetElement extends HTMLElement

Beschreibung

HTMLFrameSetElement ist die DOM-Schnittstelle für das veraltete <frameset>-Element. Sie erbt alle Eigenschaften und Methoden von HTMLElement und ergänzt zwei eigene Eigenschaften: cols und rows. Beide spiegeln die gleichnamigen HTML-Attribute wider. Sie enthalten eine kommagetrennte Liste von Größenangaben (Pixel, Prozent oder relative Werte mit *), die festlegt, wie das Browserfenster auf die enthaltenen <frame>-Elemente aufgeteilt wird.

Außerdem bindet die Schnittstelle das Mixin WindowEventHandlers ein. Handler wie onload, onbeforeunload, onhashchange, onpopstate, onmessage, onstorage, ononline/onoffline oder onpagehide/onpageshow werden am <frameset> genauso wie beim <body> an das window-Objekt weitergereicht.

In der Praxis begegnet man der Schnittstelle fast nur noch in Altanwendungen: etwa bei alten Intranet-Seiten, Hilfesystemen oder generierter Dokumentation wie älteren Javadoc-Versionen. Enthält ein Dokument statt <body> ein <frameset>, liefert document.body das HTMLFrameSetElement. Daran lassen sich solche Seiten erkennen.

Für neue Projekte solltest du <frameset> nicht mehr verwenden. Nutze stattdessen <iframe> oder moderne Layout-Techniken wie CSS Grid und Flexbox, bei Bedarf zusammen mit Client-seitigem Routing.

Rückgabewert

Typ

HTMLFrameSetElement

Beschreibung

Instanzen bekommst du z. B. über document.createElement('frameset'), document.querySelector('frameset') oder über document.body in einem Frameset-Dokument. Eigene Eigenschaften: cols (string) und rows (string).

Beispiele

Instanz erzeugen und cols/rows setzen

const frameset = document.createElement('frameset');

console.log(frameset instanceof HTMLFrameSetElement);

// Die Eigenschaften spiegeln die HTML-Attribute wider
frameset.cols = '200,*';
frameset.rows = '50%,50%';

console.log(frameset.getAttribute('cols'));
console.log(frameset.outerHTML);

true 200,* <frameset cols="200,*" rows="50%,50%"></frameset>

Frameset-Dokument erkennen (z. B. in einer Browser-Erweiterung)

const isFramesetDocument = () =>
  document.body instanceof HTMLFrameSetElement;

if (isFramesetDocument()) {
  console.log(`Frameset-Seite mit ${window.frames.length} Frames erkannt`);
} else {
  console.log('Normales Dokument mit <body>');
}

Normales Dokument mit <body>

Navigationsspalte in einer Alt-Anwendung ein- und ausblenden

// Angenommenes Markup: <frameset cols="250,*"><frame name="nav"><frame name="main"></frameset>
const frameset = document.querySelector('frameset');
let savedCols = frameset?.cols ?? '';

const toggleNavigation = () => {
  if (!frameset) return;
  if (frameset.cols.startsWith('0,')) {
    frameset.cols = savedCols;   // wiederherstellen
  } else {
    savedCols = frameset.cols;
    frameset.cols = '0,*';       // Navigation verstecken
  }
  console.log('Aktuelle Aufteilung:', frameset.cols);
};

toggleNavigation();

Aktuelle Aufteilung: 0,*

Fenster-Events über das Frameset behandeln

const frameset = document.querySelector('frameset');

if (frameset) {
  // WindowEventHandlers: wird an window weitergeleitet
  frameset.onhashchange = () => {
    console.log('Neuer Hash:', location.hash);
  };
}

// Gleichwertig und zu bevorzugen:
window.addEventListener('hashchange', () => {
  console.log('hashchange via window:', location.hash);
});

// Wichtig · Fallstricke

Veraltet: <frameset> und <frame> sind in HTML5 nicht mehr konform. Browser stellen sie zwar weiterhin dar, aber nur, wenn das Dokument kein <body> hat. Folgt ein <frameset> auf Inhalt im Body, wird es ignoriert.
document.body ist nicht immer HTMLBodyElement: In Frameset-Dokumenten liefert es das HTMLFrameSetElement. Code, der sich auf Body-Eigenschaften verlässt, kann dort fehlschlagen.
cols und rows sind einfache Zeichenketten. Der Browser prüft sie nicht. Ungültige Werte führen still zu einer abweichenden oder gleichmäßigen Aufteilung.
Die on…-Handler am Frameset sind in Wahrheit Handler von window. Wer frameset.onload setzt, überschreibt also window.onload. Verwende besser window.addEventListener().
Auf Inhalte anderer Frames kannst du nur bei gleichem Ursprung zugreifen (Same-Origin-Policy). Nutze für die Kommunikation über Ursprungsgrenzen hinweg postMessage() und prüfe dabei immer event.origin.
Für Barrierefreiheit, SEO und mobile Geräte sind Framesets ungünstig. Moderne Alternativen sind <iframe> sowie CSS Grid und Flexbox.

Siehe auch

Window.frames HTMLFieldSetElement HTMLIFrameElement HTMLBaseElement HTMLMeterElement