Document — Schnittstelle · JavaScript-Referenz

Signatur

interface Document extends Node

Beschreibung

Die Schnittstelle Document steht für ein vollständiges Dokument, das im Browser geladen ist, und bildet die Wurzel des DOM-Baums. Im Browser steht die aktuelle Seite über das globale Objekt document (window.document) zur Verfügung. Document erbt von Node und damit indirekt von EventTarget. Daher lassen sich Ereignisse wie DOMContentLoaded oder visibilitychange direkt am Dokument abonnieren.

Document bietet die zentralen Werkzeuge für die DOM-Arbeit:

Elemente finden: querySelector(), querySelectorAll(), getElementById(), getElementsByClassName()
Knoten erzeugen: createElement(), createTextNode(), createDocumentFragment(), importNode()
Metadaten und Zustand: title, URL, readyState, visibilityState, cookie, referrer, characterSet
Strukturelle Einstiege: documentElement (das <html>-Element), head, body, forms, images, links
Fokus und Vollbild: activeElement, hasFocus(), fullscreenElement, exitFullscreen()

Mit new Document() kann man ein eigenes, leeres Dokument erzeugen. In der Praxis sind aber document.implementation.createHTMLDocument() und DOMParser üblicher, wenn man ein zusätzliches Dokument braucht, zum Beispiel um HTML-Zeichenketten zu verarbeiten, ohne sie in der aktuellen Seite auszuführen. Spezialisierte Varianten sind HTMLDocument (heute nur noch ein Alias) und XMLDocument.

Parameter

Name	Typ	Default	Beschreibung
$(Konstruktor) new Document()	—		Der Konstruktor nimmt keine Argumente an. Er erzeugt ein leeres Dokument ohne `documentElement`, das nicht an ein Browserfenster gebunden ist.

Rückgabewert

Typ

Document

Beschreibung

Das globale document bzw. new Document() liefert eine Document-Instanz, über die man auf den DOM-Baum zugreift und ihn verändert.

Beispiele

Auf DOMContentLoaded warten und Elemente abfragen

const init = () => {
  const heading = document.querySelector('h1');
  const buttons = document.querySelectorAll('button.primary');
  console.log(`Titel: ${document.title}`);
  console.log(`Überschrift: ${heading?.textContent ?? '(keine)'}`);
  console.log(`Primär-Buttons: ${buttons.length}`);
};

if (document.readyState === 'loading') {
  document.addEventListener('DOMContentLoaded', init);
} else {
  init(); // DOM ist bereits geparst
}

Titel: Meine Seite Überschrift: Willkommen Primär-Buttons: 2

Liste effizient mit DocumentFragment aufbauen

const produkte = ['Tastatur', 'Maus', 'Monitor'];
const fragment = document.createDocumentFragment();

for (const name of produkte) {
  const li = document.createElement('li');
  li.textContent = name; // sicher: kein HTML-Parsing
  fragment.append(li);
}

const ul = document.createElement('ul');
ul.append(fragment);
document.body.append(ul);
console.log(ul.children.length);

3

Separates Dokument erzeugen und HTML sicher auswerten

// Eigenes Dokument per Konstruktor
const leer = new Document();
console.log(leer.documentElement); // null

// HTML-String parsen, ohne Skripte in der Seite auszuführen
const parser = new DOMParser();
const doc = parser.parseFromString(
  '<article><h2>News</h2><p>Hallo Welt</p></article>',
  'text/html'
);
console.log(doc instanceof Document);
console.log(doc.querySelector('h2').textContent);

null true News

Auf Sichtbarkeitswechsel des Tabs reagieren

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

const onVisibility = () => {
  if (document.visibilityState === 'hidden') {
    video?.pause();
    console.log('Tab verborgen – Video pausiert');
  }
};

document.addEventListener('visibilitychange', onVisibility);
// Später wieder entfernen:
// document.removeEventListener('visibilitychange', onVisibility);

Tab verborgen – Video pausiert

// Wichtig · Fallstricke

Zeitpunkt: Skripte im <head> ohne defer oder type="module" laufen, bevor document.body existiert. querySelector() gibt dann null zurück. Nutze defer oder warte auf DOMContentLoaded.
Lebende und statische Sammlungen: getElementsByClassName() und getElementsByTagName() liefern eine lebende HTMLCollection, die sich mit dem DOM ändert. querySelectorAll() liefert dagegen eine statische NodeList.
Sicherheit (XSS): document.write() und die Zuweisung von Nutzereingaben an innerHTML öffnen Tür für Cross-Site-Scripting. Verwende stattdessen textContent, createElement() oder die Trusted-Types-API. document.write() ist außerdem veraltet und blockiert das Parsen. Nach dem Laden der Seite aufgerufen, löscht es sogar das ganze Dokument.
Cookies: document.cookie ist eine Zeichenkette ohne Struktur und zeigt keine HttpOnly-Cookies. Für neuen Code bietet sich die asynchrone cookieStore-API an, die noch nicht überall unterstützt wird.
Kompatibilität: Die Schnittstelle selbst wird von allen Browsern unterstützt. Neuere Mitglieder wie document.startViewTransition() oder document.hasStorageAccess() gibt es noch nicht überall. Prüfe sie vor der Nutzung per Feature-Detection ('startViewTransition' in document).
Umgebung: In Web Workern und in Node.js gibt es kein document. Unter Node.js braucht man Bibliotheken wie jsdom.

Siehe auch

Node Element Window DOMParser Comment