Document.parseHTML() — Methode · JavaScript-Referenz

Signatur

Document.parseHTML(input, options)

Beschreibung

Document.parseHTML() ist eine statische Methode aus der HTML Sanitizer API. Sie nimmt einen HTML-String entgegen, parst ihn zu einem vollständigen, eigenständigen Document (mit <html>, <head> und <body>) und entfernt dabei alle Elemente und Attribute, die nicht erlaubt sind.

Der entscheidende Unterschied zu DOMParser.parseFromString() oder Document.parseHTMLUnsafe(): parseHTML() ist immer XSS-sicher. Selbst wenn du eine Sanitizer-Konfiguration übergibst, die gefährliche Inhalte wie <script>, <iframe> oder Ereignis-Attribute (onclick, onerror …) erlauben würde, werden diese trotzdem entfernt. Die Konfiguration kann den erlaubten Inhalt also nur weiter einschränken, niemals unsicher machen.

Typische Einsatzfälle sind das Verarbeiten von nutzergenerierten Inhalten (Kommentare, Rich-Text-Editoren, Markdown-Ausgaben), das Anzeigen von HTML aus fremden APIs oder das Vorverarbeiten von HTML-Fragmenten, bevor einzelne Knoten ins Live-DOM übernommen werden. Wenn du den Inhalt direkt in ein vorhandenes Element schreiben willst, ist Element.setHTML() meist die einfachere Wahl.

Da das Ergebnis ein vom aktuellen Dokument getrenntes Document ist, werden beim Parsen keine Skripte ausgeführt und keine Ressourcen gerendert. Knoten daraus kannst du mit document.importNode() oder append() ins sichtbare Dokument übernehmen.

Parameter

Name	Typ	Default	Beschreibung
$input Pflicht	string		Der zu parsende und zu bereinigende HTML-String.
$options	object	{}	Optionsobjekt. Enthält die Eigenschaft `sanitizer`.
$options.sanitizer	Sanitizer \| SanitizerConfig \| "default"	"default"	Legt fest, welche Elemente und Attribute erhalten bleiben: eine `Sanitizer`-Instanz, ein Konfigurationsobjekt (z. B. `{ elements: ["p", "b"] }`) oder der String `"default"` für die sichere Standardkonfiguration. XSS-gefährliche Inhalte werden in jedem Fall entfernt.

Rückgabewert

Typ

Document

Beschreibung

Ein neues, eigenständiges Document, das den geparsten und bereinigten Inhalt enthält.

Beispiele

Unsicheres HTML bereinigen

const unsicher = '<p>Hallo <b>Welt</b><script>alert(1)</script></p><img src="x.png" onerror="alert(2)">';

const doc = Document.parseHTML(unsicher);

// Skript und Ereignis-Attribut sind entfernt
console.log(doc.body.innerHTML);

<p>Hallo <b>Welt</b></p><img src="x.png">

Erlaubte Elemente per Konfiguration einschränken

const kommentar = '<h1>Titel</h1><p>Text mit <a href="https://example.com" style="color:red">Link</a> und <em>Betonung</em></p>';

const doc = Document.parseHTML(kommentar, {
  sanitizer: {
    elements: ['p', 'em', { name: 'a', attributes: ['href'] }]
  }
});

console.log(doc.body.innerHTML);

Titel<p>Text mit <a href="https://example.com">Link</a> und <em>Betonung</em></p>

Sicherheitsgarantie trotz großzügiger Konfiguration

// Auch wenn <script> und onclick ausdrücklich erlaubt werden,
// entfernt parseHTML() sie trotzdem.
const doc = Document.parseHTML(
  '<button onclick="stehleDaten()">Klick</button><script>boese()</script>',
  { sanitizer: { elements: [{ name: 'button', attributes: ['onclick'] }, 'script'] } }
);

console.log(doc.body.innerHTML);

<button>Klick</button>

Feature-Erkennung und Übernahme ins Live-DOM

const renderKommentar = (html, ziel) => {
  if (typeof Document.parseHTML !== 'function') {
    // Fallback: nur als Text anzeigen
    ziel.textContent = html;
    return;
  }
  const doc = Document.parseHTML(html);
  ziel.replaceChildren(...doc.body.childNodes);
};

renderKommentar('<p>Neuer <strong>Kommentar</strong></p>', document.querySelector('#kommentare'));

// Wichtig · Fallstricke

Kompatibilität: Die HTML Sanitizer API ist noch neu bzw. experimentell und wird nicht von allen Browsern unterstützt. Prüfe vor der Nutzung mit typeof Document.parseHTML === 'function' und sieh einen Fallback vor (z. B. textContent oder eine Bibliothek wie DOMPurify).
Statische Methode: Aufruf über Document.parseHTML(), nicht über document.parseHTML().
Sicher vs. unsicher: Document.parseHTMLUnsafe() und DOMParser entfernen gefährliche Inhalte nicht automatisch. Nutze für nicht vertrauenswürdige Eingaben immer parseHTML().
Nachträgliche Manipulation: Die Sicherheit gilt nur für das Parsen. Wenn du anschließend innerHTML aus dem Ergebnis ausliest und an anderer Stelle mit unsicheren Methoden neu einfügst oder Attribute selbst setzt, kann wieder XSS entstehen. Übernimm besser die Knoten direkt.
Kein Ersatz für CSP: Eine Content-Security-Policy und ggf. Trusted Types bleiben als zusätzliche Verteidigungsebene sinnvoll.
Nicht erlaubte Elemente werden je nach Konfiguration entweder samt Inhalt entfernt oder nur „ausgepackt“ (Kindknoten bleiben erhalten, siehe replaceWithChildrenElements).

Siehe auch

Document.parseHTMLUnsafe() Element.setHTML() ShadowRoot.setHTML() DOMParser.parseFromString() Element.innerHTML new SyncEvent()