Signatur
Beschreibung
Das Interface Sanitizer gehört zur HTML Sanitizer API. Ein Sanitizer bereinigt HTML nicht selbst. Er ist eine wiederverwendbare Konfiguration, die Sie an Methoden wie Element.setHTML(), ShadowRoot.setHTML(), Document.parseHTML() oder deren „Unsafe“-Varianten übergeben. Die Konfiguration bestimmt, welche Elemente und Attribute erlaubt sind, welche entfernt werden und welche Elemente durch ihren Inhalt ersetzt werden. Außerdem legt sie fest, ob Kommentare und data-*-Attribute erhalten bleiben.
Sie erzeugen eine Instanz mit new Sanitizer(). Ohne Argument oder mit "default" erhalten Sie die eingebaute, sichere Standardkonfiguration. Alternativ übergeben Sie ein SanitizerConfig-Objekt. Danach können Sie die Konfiguration mit Methoden wie allowElement(), removeElement(), replaceElementWithChildren(), allowAttribute(), removeAttribute(), setComments(), setDataAttributes() und removeUnsafe() anpassen. get() gibt die aktuelle Konfiguration als normales Objekt zurück.
Der Sanitizer eignet sich überall, wo Sie HTML aus nicht vertrauenswürdigen Quellen anzeigen: Kommentare von Nutzern, Markdown-Vorschauen, WYSIWYG-Editoren oder HTML-Fragmente aus Drittanbieter-APIs. Die Bereinigung verwendet den HTML-Parser des Browsers selbst. Dadurch fallen Probleme weg, die entstehen, wenn Bibliothek und Browser HTML unterschiedlich parsen (Stichwort mXSS, „mutation XSS“).
Wichtig: Die sicheren Methoden (setHTML(), parseHTML()) entfernen immer XSS-gefährliche Inhalte wie <script> oder on*-Event-Handler, egal wie der Sanitizer konfiguriert ist. Die Methoden setHTMLUnsafe() und Document.parseHTMLUnsafe() wenden dagegen nur Ihre Konfiguration an. Dort müssen Sie für Sicherheit selbst sorgen, zum Beispiel mit removeUnsafe().
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $configuration | SanitizerConfig | "default" | "default" | Konfiguration für den Konstruktor. Entweder "default" für die sichere Standardkonfiguration oder ein Objekt mit den Schlüsseln elements, removeElements, replaceWithChildrenElements, attributes, removeAttributes, comments (boolean) und dataAttributes (boolean). Innerhalb eines Objekts sollten Sie entweder mit Erlaubnislisten (elements/attributes) oder mit Sperrlisten (removeElements/removeAttributes) arbeiten, nicht mit beidem. |
Rückgabewert
Sanitizer-Instanz. Sie übergeben sie als Option { sanitizer } an setHTML(), setHTMLUnsafe(), parseHTML() oder parseHTMLUnsafe(). Ist die Konfiguration ungültig, zum Beispiel widersprüchlich, wirft der Konstruktor einen TypeError.Beispiele
Nutzer-HTML mit Standard-Sanitizer einfügen
const kommentar = '<p>Hallo <b>Welt</b></p><img src=x onerror="alert(1)"><script>alert(2)</script>';
const ziel = document.querySelector('#kommentar');
// setHTML() bereinigt immer sicher, auch ohne eigenen Sanitizer
ziel.setHTML(kommentar);
console.log(ziel.innerHTML);Eigene Erlaubnisliste per Konstruktor
// Nur einfache Textformatierung und Links erlauben
const sanitizer = new Sanitizer({
elements: ['p', 'b', 'i', 'em', 'strong', 'a', 'br'],
attributes: ['href', 'title'],
comments: false
});
const html = '<h1>Titel</h1><p class="x">Siehe <a href="https://example.com" target="_blank">Link</a><!-- Notiz --></p>';
const box = document.querySelector('#vorschau');
box.setHTML(html, { sanitizer });
console.log(box.innerHTML);Konfiguration mit Methoden anpassen und auslesen
const sanitizer = new Sanitizer(); // Standardkonfiguration
sanitizer.removeElement('img'); // Bilder komplett entfernen
sanitizer.replaceElementWithChildren('span'); // <span> auflösen, Inhalt behalten
sanitizer.setDataAttributes(false); // keine data-*-Attribute
sanitizer.setComments(false);
const el = document.createElement('div');
el.setHTML('<span data-id="1">Text</span><img src="a.png">', { sanitizer });
console.log(el.innerHTML);
// Aktuelle Konfiguration als normales Objekt
const config = sanitizer.get();
console.log(config.comments, config.dataAttributes);Feature-Erkennung mit Fallback
const renderSicher = (element, html) => {
if ('Sanitizer' in window && 'setHTML' in Element.prototype) {
element.setHTML(html, { sanitizer: new Sanitizer() });
} else {
// Fallback: nur Text einfügen (oder z. B. DOMPurify verwenden)
element.textContent = html;
}
};
renderSicher(document.querySelector('#ausgabe'), '<em>Hi</em><script>boom()</script>');