HTMLDocument — Schnittstelle · JavaScript-Referenz

Signatur

interface HTMLDocument extends Document

Beschreibung

HTMLDocument war früher ein eigenes Interface für HTML-Dokumente. Es enthielt HTML-spezifische Mitglieder wie body, forms, cookie oder write(). Der heutige HTML-Standard hat all diese Mitglieder direkt in das Document-Interface verschoben. Übrig geblieben ist nur ein Name, damit ältere Skripte nicht brechen.

Laut Spezifikation hat jedes Window-Objekt eine beschreibbare, konfigurierbare und nicht aufzählbare Eigenschaft HTMLDocument. Ihr Wert ist das Document-Interface-Objekt selbst. In der Praxis setzen die Browser das unterschiedlich um: Chromium und Firefox führen HTMLDocument weiterhin als eigene Unterklasse von Document. Das normale document einer HTML-Seite ist dort also eine Instanz von HTMLDocument.

Einsatzgebiet: Den Namen HTMLDocument findet man vor allem in älterem Code, zum Beispiel bei Typprüfungen (instanceof HTMLDocument), in Polyfills oder bei Erweiterungen des Prototyps. Für neuen Code gilt: Nutze immer Document. Diese Prüfung funktioniert für HTML- und XML-Dokumente gleich und in allen Browsern.

Rückgabewert

Typ

Function (Interface-Objekt)

Beschreibung

window.HTMLDocument liefert ein Interface-Objekt. Laut Standard ist das Document selbst, in vielen Browsern eine eigene Unterklasse von Document. Es lässt sich nicht direkt instanziieren: new HTMLDocument() wirft einen TypeError.

Beispiele

Ist das aktuelle Dokument ein HTML-Dokument?

// Im Browser, auf einer normalen HTML-Seite
console.log(document instanceof HTMLDocument);
console.log(document instanceof Document);

// Empfohlen für neuen Code:
const istDokument = (obj) => obj instanceof Document;
console.log(istDokument(document));

true true true

Neues HTML-Dokument erzeugen statt Konstruktor aufrufen

// new HTMLDocument() ist nicht erlaubt – dafür gibt es createHTMLDocument()
try {
  new HTMLDocument();
} catch (err) {
  console.log(err.name);
}

const doc = document.implementation.createHTMLDocument('Vorschau');
doc.body.innerHTML = '<p>Hallo Welt</p>';

console.log(doc.title);
console.log(doc instanceof Document);
console.log(doc.querySelector('p').textContent);

TypeError Vorschau true Hallo Welt

Verhalten bei XML-Dokumenten prüfen (browserabhängig)

const xml = new DOMParser().parseFromString('<daten><x>1</x></daten>', 'application/xml');

console.log(xml instanceof Document);      // immer true
console.log(xml instanceof XMLDocument);   // true
// Hängt vom Browser ab: true, wenn HTMLDocument === Document (Standard),
// false, wenn HTMLDocument eine eigene Unterklasse ist (z. B. Chromium)
console.log(xml instanceof HTMLDocument);

// Den Namen HTMLDocument erkennen, ohne sich auf ein Ergebnis festzulegen
console.log('Alias gemäß Standard:', window.HTMLDocument === Document);

true true false (Chromium/Firefox) bzw. true (standardkonform) Alias gemäß Standard: false (Chromium/Firefox)

// Wichtig · Fallstricke

Unterschiede zwischen Browsern: Der Standard legt window.HTMLDocument === Document fest. Chromium und Firefox führen HTMLDocument aber noch als eigene Unterklasse. Deshalb liefert instanceof HTMLDocument für XML-Dokumente (z. B. aus DOMParser mit application/xml) je nach Browser ein anderes Ergebnis. Für verlässliche Prüfungen instanceof Document verwenden.
Kein Konstruktor: new HTMLDocument() wirft einen TypeError. Neue Dokumente erzeugst du mit document.implementation.createHTMLDocument(), new Document() oder DOMParser.
Prototyp erweitern: Eigene Methoden an HTMLDocument.prototype sind nicht in jedem Browser für jedes Dokument sichtbar. Vermeide das grundsätzlich.
TypeScript: In lib.dom.d.ts ist HTMLDocument nur ein leeres Interface, das von Document erbt. Als Typ reicht Document.
Node.js: Node.js hat kein HTMLDocument. Bibliotheken wie jsdom stellen eines bereit.

Siehe auch

Document Window.document instanceof XMLDocument HTMLElement