HTMLBodyElement — Schnittstelle · JavaScript-Referenz

Signatur

interface HTMLBodyElement extends HTMLElement

Beschreibung

Das Interface HTMLBodyElement beschreibt das <body>-Element eines Dokuments. Normalerweise greift man darüber auf document.body zu. Es erbt alle Eigenschaften und Methoden von HTMLElement, Element, Node und EventTarget. Dazu gehören classList, dataset, style, append() und addEventListener().

Zusätzlich hat es eigene Eigenschaften, die aus der Zeit vor CSS stammen und heute als veraltet gelten:

aLink, link, vLink: Farben für aktive, normale und besuchte Links
bgColor: Hintergrundfarbe
background: URL eines Hintergrundbilds
text: Textfarbe

Diese Eigenschaften spiegeln die gleichnamigen HTML-Attribute. In neuem Code nutzt man stattdessen CSS.

Außerdem setzt HTMLBodyElement das Mixin WindowEventHandlers um. Eigenschaften wie onhashchange, onpopstate, onbeforeunload, ononline, onoffline, onstorage oder onmessage auf document.body sind nur Weiterleitungen auf das window-Objekt. Das gilt auch für die Attribute im HTML, etwa <body onload="…">.

In der Praxis nutzt man das Interface vor allem, um globale Zustände über Klassen zu steuern, Modale oder Overlays anzuhängen, das Scrollen zu sperren oder Ereignisse zentral abzufangen (Event-Delegation).

Rückgabewert

Typ

HTMLBodyElement

Beschreibung

Instanzen bekommt man über document.body oder document.querySelector('body'). Einen eigenen Konstruktor gibt es nicht: new HTMLBodyElement() löst einen TypeError aus.

Beispiele

Instanz ermitteln und Typ prüfen

const body = document.body;

console.log(body instanceof HTMLBodyElement); // true
console.log(body.tagName);                    // "BODY"

// Ein neues body-Element über createElement erzeugen (statt Konstruktor)
const neuerBody = document.createElement('body');
console.log(neuerBody.constructor.name);

true BODY HTMLBodyElement

Dark Mode und Scroll-Sperre über Klassen steuern

const body = document.body;

const setzeDarkMode = (aktiv) => {
  body.classList.toggle('dark', aktiv);
  body.dataset.theme = aktiv ? 'dark' : 'light';
};

const oeffneModal = () => {
  body.style.overflow = 'hidden'; // Hintergrund nicht mehr scrollbar
  const modal = document.createElement('dialog');
  modal.textContent = 'Hallo!';
  body.append(modal);
  modal.showModal();
  modal.addEventListener('close', () => {
    body.style.overflow = '';
    modal.remove();
  });
};

setzeDarkMode(window.matchMedia('(prefers-color-scheme: dark)').matches);
console.log(body.dataset.theme);

"dark" oder "light" (je nach Systemeinstellung)

Event-Delegation am body

// Ein einziger Listener für alle Buttons mit data-action, auch für später eingefügte
document.body.addEventListener('click', (event) => {
  const button = event.target.closest('[data-action]');
  if (!button) return;
  console.log(`Aktion: ${button.dataset.action}`);
});

const btn = document.createElement('button');
btn.dataset.action = 'speichern';
btn.textContent = 'Speichern';
document.body.append(btn);
btn.click();

Aktion: speichern

Weitergeleitete Window-Handler und veraltete Attribute

// onhashchange am body wird an window weitergeleitet
document.body.onhashchange = () => console.log('Neuer Hash:', location.hash);
console.log(window.onhashchange === document.body.onhashchange); // true

// Veraltet: bgColor spiegelt das Attribut bgcolor
document.body.bgColor = '#ffeecc';
console.log(document.body.getAttribute('bgcolor'));

// Moderne Alternative
document.body.removeAttribute('bgcolor');
document.body.style.backgroundColor = '#ffeecc';

true #ffeecc

// Wichtig · Fallstricke

document.body kann null sein, zum Beispiel wenn ein Skript im <head> ohne defer läuft. Am besten defer, type="module" oder das Ereignis DOMContentLoaded nutzen.
Bei Framesets liefert document.body ein HTMLFrameSetElement, kein HTMLBodyElement.
Veraltete Eigenschaften: aLink, bgColor, background, link, text und vLink funktionieren zwar noch in allen Browsern, sind aber veraltet. Stattdessen CSS verwenden, etwa body { background-color } oder a:visited.
Handler-Konflikte: document.body.onload = … und window.onload = … teilen sich denselben Speicherplatz. Der zuletzt gesetzte Handler überschreibt den anderen. Mit addEventListener passiert das nicht.
Sicherheit: document.body.innerHTML = nutzereingabe öffnet XSS-Lücken. Besser textContent, append() oder eine Bereinigung (z. B. DOMPurify) verwenden.
Scrollposition: Im Standardmodus liefert document.body.scrollTop meist 0. Die Seitenposition steckt in document.documentElement.scrollTop bzw. window.scrollY.
Das Interface wird in allen modernen Browsern unterstützt.

Siehe auch

Document.body Window HTMLModElement HTMLBRElement HTMLBaseElement