Element.setHTMLUnsafe() — Methode · JavaScript-Referenz

Signatur

Element.prototype.setHTMLUnsafe(input, options)

Beschreibung

setHTMLUnsafe() parst den übergebenen HTML-String zuerst in ein DocumentFragment. Danach ersetzt die Methode damit den gesamten bisherigen Inhalt des Elements. Das funktioniert ähnlich wie das Setzen von innerHTML, es gibt aber einen wichtigen Unterschied: deklaratives Shadow DOM wird ausgewertet. Aus <template shadowrootmode="open"> im Markup entsteht also wirklich ein Shadow Root. Bei innerHTML bleibt so ein Template nur ein normales <template>-Element.

Wie der Name sagt, ist die Methode unsicher. Wenn Sie keinen Sanitizer angeben, wird das Markup ungefiltert übernommen. Event-Handler-Attribute wie onerror, javascript:-URLs usw. bleiben also erhalten. Mit der Option sanitizer können Sie eine Konfiguration mitgeben, die unerwünschte Elemente und Attribute entfernt. Anders als bei setHTML() werden als gefährlich bekannte Konstrukte aber nicht zusätzlich automatisch entfernt: Es gilt nur das, was Ihre Konfiguration erlaubt oder verbietet.

Verwenden Sie setHTMLUnsafe(), wenn Sie vertrauenswürdiges Markup einfügen wollen, zum Beispiel serverseitig gerenderte Komponenten mit deklarativem Shadow DOM oder eigene Vorlagen. Bei Nutzereingaben und fremden Daten ist setHTML() die bessere Wahl, ebenso wie Textzuweisung per textContent.

Parameter

Name	Typ	Default	Beschreibung
$input Pflicht	string \| TrustedHTML		Der zu parsende HTML-Code. Wenn Trusted Types erzwungen werden (CSP `require-trusted-types-for 'script'`), muss hier ein `TrustedHTML`-Objekt übergeben werden.
$options	object	{}	Optionales Konfigurationsobjekt.
$options.sanitizer	Sanitizer \| SanitizerConfig \| "default"	(kein Sanitizer)	Legt fest, welche Elemente und Attribute erlaubt sind. Möglich sind eine `Sanitizer`-Instanz, ein Konfigurationsobjekt wie `{ elements: [...] }` oder `{ removeElements: [...] }`, oder der String `"default"` für die sichere Standardkonfiguration. Ohne Angabe wird nichts gefiltert.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined). Die Kindknoten des Elements werden direkt ersetzt.

Beispiele

Vertrauenswürdiges Markup einfügen

const container = document.querySelector('#info');

// Eigene, statische Vorlage: keine Nutzereingaben enthalten
container.setHTMLUnsafe(`
  <h2>Willkommen</h2>
  <p>Ihr Konto ist <strong>aktiv</strong>.</p>
`);

console.log(container.children.length);

2

Deklaratives Shadow DOM verarbeiten

const host = document.createElement('div');
document.body.append(host);

host.setHTMLUnsafe(`
  <div id="karte">
    <template shadowrootmode="open">
      <style>p { color: rebeccapurple; }</style>
      <p><slot></slot></p>
    </template>
    Hallo aus dem Light DOM
  </div>
`);

const karte = host.querySelector('#karte');
console.log(karte.shadowRoot !== null); // mit innerHTML wäre das false
console.log(karte.shadowRoot.querySelector('p') instanceof HTMLParagraphElement);

true true

Mit Sanitizer-Konfiguration filtern (mit Feature-Erkennung)

const box = document.querySelector('#vorschau');
const html = '<p>Text <b>fett</b> <img src="x" onerror="alert(1)"></p>';

if ('Sanitizer' in window) {
  // Nur <p> und <b> zulassen, alles andere wird entfernt
  box.setHTMLUnsafe(html, { sanitizer: { elements: ['p', 'b'] } });
} else {
  // Fallback ohne Sanitizer-API: nur als Text anzeigen
  box.textContent = html;
}

console.log(box.innerHTML);

Mit Trusted Types verwenden

// Nötig, wenn die CSP Trusted Types erzwingt
const policy = window.trustedTypes?.createPolicy('vorlagen', {
  createHTML: (s) => s // hier nur geprüfte, eigene Vorlagen durchlassen!
});

const markup = '<ul><li>Eins</li><li>Zwei</li></ul>';
const el = document.querySelector('#liste');
el.setHTMLUnsafe(policy ? policy.createHTML(markup) : markup);

console.log(el.querySelectorAll('li').length);

2

// Wichtig · Fallstricke

Sicherheit (XSS): Wenn kein Sanitizer angegeben ist, werden Attribute wie onerror/onload und javascript:-URLs unverändert übernommen. Übergeben Sie deshalb niemals ungeprüfte Nutzereingaben, URL-Parameter oder Antworten von Drittanbieter-APIs. Nehmen Sie dafür setHTML(), das gefährliche Inhalte immer entfernt.

Auch mit sanitizer ist das Ergebnis nur so sicher wie Ihre Konfiguration. Wenn Sie zum Beispiel script oder on*-Attribute ausdrücklich erlauben, bleiben sie erhalten.
Eingefügte <script>-Elemente werden wie bei innerHTML nicht ausgeführt. Inline-Event-Handler dagegen schon.
Wenn Trusted Types über CSP erzwungen werden, löst ein normaler String einen TypeError aus. Übergeben Sie dann ein TrustedHTML-Objekt.
Der gesamte bisherige Inhalt wird ersetzt. Event-Listener auf den alten Kindelementen gehen dabei verloren.

Kompatibilität: Die Methode selbst funktioniert seit 2024 in allen aktuellen Browsern. Die Option sanitizer und die Sanitizer-API sind noch neu und nicht überall verfügbar. Prüfen Sie deshalb vorher, ob sie unterstützt werden, zum Beispiel mit 'Sanitizer' in window. Das Gegenstück auf Dokumentebene ist Document.parseHTMLUnsafe(), und für Shadow Roots gibt es ShadowRoot.setHTMLUnsafe().

Siehe auch

Element.setHTML() Element.innerHTML Element.getHTML() ShadowRoot.setHTMLUnsafe() Document.parseHTMLUnsafe() Sanitizer TrustedHTML