Document.parseHTMLUnsafe() — Methode · JavaScript-Referenz

Signatur

Document.parseHTMLUnsafe(input, options)

Beschreibung

Document.parseHTMLUnsafe() ist eine statische Methode. Sie nimmt einen HTML-String entgegen und liefert daraus ein vollständiges, eigenständiges Document. Das Dokument wird nicht angezeigt, und <script>-Elemente darin werden beim Parsen nicht ausgeführt. So lässt sich HTML-Markup untersuchen, umbauen oder Teile davon übernehmen, ohne dass das aktuelle Dokument betroffen ist.

Im Vergleich zu new DOMParser().parseFromString(html, "text/html") gibt es zwei Vorteile: Die Methode ist ein einzelner, kurzer Aufruf, und sie verarbeitet deklaratives Shadow DOM. <template shadowrootmode="open"> wird also direkt in echte Shadow Roots umgewandelt. DOMParser ignoriert solche Templates.

Das Unsafe im Namen ist ernst gemeint. Ohne Option wird nichts bereinigt. Auch mit der Option sanitizer gilt nur die übergebene Konfiguration. Die XSS-sicheren Standardregeln werden nicht zusätzlich erzwungen, anders als bei der sicheren Variante Document.parseHTML(). Wenn das Ergebnis aus nicht vertrauenswürdigen Quellen stammt und in die Seite übernommen wird, sollte man die sichere Variante verwenden oder einen passenden Sanitizer übergeben.

Wenn Trusted Types per CSP erzwungen werden, erwartet die Methode ein TrustedHTML-Objekt statt eines einfachen Strings.

Parameter

Name	Typ	Default	Beschreibung
$input Pflicht	string \| TrustedHTML		Das zu parsende HTML. Unter erzwungenen Trusted Types muss ein `TrustedHTML`-Objekt übergeben werden, sonst wird ein `TypeError` ausgelöst.
$options	object	{}	Optionales Konfigurationsobjekt.
$options.sanitizer	Sanitizer \| SanitizerConfig \| "default"	(keine Bereinigung)	Legt fest, welche Elemente und Attribute erlaubt oder entfernt werden. Möglich sind eine `Sanitizer`-Instanz, ein Konfigurationsobjekt (z. B. `{ elements: [...] }`) oder `"default"` für die Standardkonfiguration. Experimentell und noch nicht in allen Browsern verfügbar.

Rückgabewert

Typ

Document

Beschreibung

Ein neues, nicht angezeigtes Document mit dem geparsten Inhalt. Bei Bedarf wurde das Markup um <html>, <head> und <body> ergänzt.

Beispiele

HTML-String parsen und Inhalte auslesen

const html = `
  <article>
    <h2>Neue Version 2.0</h2>
    <p>Jetzt mit <a href="/changelog">Changelog</a>.</p>
  </article>`;

const doc = Document.parseHTMLUnsafe(html);

console.log(doc.querySelector('h2').textContent);
console.log(doc.querySelectorAll('a').length);
console.log(doc.body.firstElementChild.tagName);

Neue Version 2.0 1 ARTICLE

Deklaratives Shadow DOM verarbeiten

const html = `
  <user-card>
    <template shadowrootmode="open">
      <style>p { color: teal; }</style>
      <p><slot></slot></p>
    </template>
    Anna Beispiel
  </user-card>`;

const doc = Document.parseHTMLUnsafe(html);
const card = doc.querySelector('user-card');

// Shadow Root wurde direkt angelegt (bei DOMParser wäre sie null)
console.log(card.shadowRoot !== null);
console.log(card.shadowRoot.querySelector('slot') !== null);

true true

Mit Sanitizer-Konfiguration filtern

const userInput = '<p onclick="alert(1)">Hallo <b>Welt</b><img src=x></p>';

// Nur p und b erlauben, alles andere entfernen
const doc = Document.parseHTMLUnsafe(userInput, {
  sanitizer: { elements: ['p', 'b'], attributes: [] }
});

console.log(doc.body.innerHTML);

<p>Hallo <b>Welt</b></p>

Nutzung unter erzwungenen Trusted Types

// Voraussetzung: CSP "require-trusted-types-for 'script'"
const policy = trustedTypes.createPolicy('templates', {
  createHTML: (s) => s // hier eigene Prüfung/Bereinigung einbauen!
});

const trusted = policy.createHTML('<section><h1>Dashboard</h1></section>');
const doc = Document.parseHTMLUnsafe(trusted);

// Knoten ins aktuelle Dokument übernehmen
document.body.append(document.importNode(doc.querySelector('section'), true));

// Wichtig · Fallstricke

Sicherheit: Ohne Option sanitizer wird nichts bereinigt. Event-Handler-Attribute wie onclick, javascript:-URLs und <script> bleiben im Dokument erhalten. Beim Parsen wird zwar nichts ausgeführt. Übernimmt man die Knoten aber in das aktuelle Dokument, entsteht eine XSS-Lücke. Für Benutzereingaben sollte man Document.parseHTML() verwenden, die sichere Variante mit erzwungener XSS-Bereinigung.
Auch mit einem Sanitizer ist die Methode nicht automatisch sicher. Eine großzügige Konfiguration, etwa eine, die script erlaubt, wird genau so angewendet.
Unter der CSP-Direktive require-trusted-types-for 'script' führt ein einfacher String zu einem TypeError.
Relative URLs im geparsten Dokument werden gegen about:blank aufgelöst, nicht gegen die URL der Seite.
Knoten aus dem neuen Dokument übernimmt man mit document.importNode() oder document.adoptNode(). append() übernimmt sie ebenfalls automatisch.
Kompatibilität: Die Methode selbst gibt es in Chrome/Edge ab 124, Firefox ab 124 und Safari ab 17.4. Die Option sanitizer gehört zur Sanitizer API, ist experimentell und wird noch nicht überall unterstützt. Deshalb vorher prüfen, etwa mit 'parseHTMLUnsafe' in Document, und bei Bedarf auf DOMParser ausweichen.

Siehe auch

Document.parseHTML() DOMParser.prototype.parseFromString() Element.prototype.setHTMLUnsafe() Element.prototype.setHTML() Sanitizer TrustedHTML Document.prototype.importNode()