new Sanitizer() — Methode · JavaScript-Referenz

Signatur

new Sanitizer(configuration)

Beschreibung

Der Konstruktor Sanitizer() erstellt eine Konfiguration für die HTML Sanitizer API. Das Objekt bereinigt selbst kein HTML, sondern wird an Methoden wie Element.setHTML(), ShadowRoot.setHTML(), Document.parseHTML() oder die „unsicheren“ Varianten setHTMLUnsafe()/Document.parseHTMLUnsafe() übergeben. Die Methoden nutzen es dann, um unerwünschte Elemente und Attribute schon beim Parsen herauszufiltern.

Du kannst entweder die eingebaute Standardkonfiguration verwenden (new Sanitizer() oder new Sanitizer("default")) oder ein eigenes SanitizerConfig-Objekt übergeben. Darin legst du entweder eine Erlaubnisliste (elements, attributes) oder eine Sperrliste (removeElements, removeAttributes) fest. Dazu kommen replaceWithChildrenElements (Element entfernen, Inhalt behalten), comments und dataAttributes.

Nach dem Erzeugen kannst du die Konfiguration über Methoden wie allowElement(), removeElement(), replaceElementWithChildren(), allowAttribute(), removeAttribute(), setComments(), setDataAttributes() und removeUnsafe() weiter anpassen. Mit get() liest du die aktuelle Konfiguration aus. Ein Sanitizer lohnt sich vor allem, wenn du dieselben Regeln mehrmals brauchst, etwa für Kommentare, Chat-Nachrichten oder Markdown-Vorschauen.

Wichtig: Die „sicheren“ Methoden (setHTML(), parseHTML()) entfernen immer XSS-gefährliche Inhalte wie <script> oder on*-Event-Handler, auch wenn deine Konfiguration sie erlaubt. Die …Unsafe()-Varianten halten sich dagegen genau an deine Konfiguration.

Parameter

Name	Typ	Default	Beschreibung
$configuration	SanitizerConfig \| "default"	"default"	Entweder der String `"default"` für die eingebaute sichere Standardkonfiguration oder ein `SanitizerConfig`-Objekt mit den Schlüsseln `elements`, `removeElements`, `replaceWithChildrenElements`, `attributes`, `removeAttributes`, `comments` (boolean) und `dataAttributes` (boolean). Elemente und Attribute kannst du als String (`"p"`) oder als Objekt mit Namensraum angeben (`{ name: "svg", namespace: "http://www.w3.org/2000/svg" }`). Pro Element sind außerdem `attributes`/`removeAttributes` möglich.

Rückgabewert

Typ

Sanitizer

Beschreibung

Ein neues Sanitizer-Objekt, das du an setHTML(), parseHTML() und Co. übergeben kannst. Bei einer ungültigen oder widersprüchlichen Konfiguration wird ein TypeError ausgelöst.

Beispiele

Standard-Sanitizer mit setHTML() verwenden

const sanitizer = new Sanitizer(); // entspricht new Sanitizer("default")
const target = document.querySelector("#kommentar");

const userInput = '<p>Hallo <b>Welt</b></p><img src=x onerror="alert(1)"><script>alert(2)</script>';
target.setHTML(userInput, { sanitizer });

console.log(target.innerHTML);

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

Strikte Erlaubnisliste für Chat-Nachrichten

const chatSanitizer = new Sanitizer({
  elements: ["p", "br", "b", "i", "code", { name: "a", attributes: ["href"] }],
  attributes: [],
  comments: false,
  dataAttributes: false
});

const renderMessage = (container, html) => {
  container.setHTML(html, { sanitizer: chatSanitizer });
};

const box = document.createElement("div");
renderMessage(box, '<p class="x">Siehe <a href="/doku" target="_blank">Doku</a><!-- geheim --><img src="a.png"></p>');
console.log(box.innerHTML);

<p>Siehe <a href="/doku">Doku</a></p>

Konfiguration nachträglich anpassen und auslesen

const sanitizer = new Sanitizer({ removeElements: ["iframe", "object"] });

sanitizer.removeElement("form");
sanitizer.replaceElementWithChildren("span");
sanitizer.removeAttribute("style");

const config = sanitizer.get();
console.log(config.removeElements.map((el) => el.name));

const doc = Document.parseHTML('<span style="color:red">Text</span><form></form>', { sanitizer });
console.log(doc.body.innerHTML);

["iframe", "object", "form"] Text

Feature-Erkennung mit Fallback

const safeInsert = (el, html) => {
  if ("Sanitizer" in window && "setHTML" in Element.prototype) {
    el.setHTML(html, { sanitizer: new Sanitizer() });
  } else {
    // Fallback: nur Text einfügen (oder DOMPurify o. Ä. verwenden)
    el.textContent = html;
  }
};

safeInsert(document.body, "<em>Hallo</em>");

// Wichtig · Fallstricke

Experimentelle API: Die Spezifikation wurde 2024 grundlegend überarbeitet. Die alten Methoden sanitize() und sanitizeFor() sowie die Optionen allowElements/blockElements/dropElements gibt es nicht mehr. Ältere Tutorials und Chrome-Versionen (105–118) benutzen noch diese veraltete Form. Prüfe die Unterstützung immer per Feature-Erkennung und halte einen Fallback bereit, etwa DOMPurify.
Erlaubnis- oder Sperrliste, nicht beides: Wenn du elements und removeElements (bzw. attributes und removeAttributes) gleichzeitig angibst oder ein Element in mehreren Listen steht, gilt die Konfiguration als ungültig und der Konstruktor löst einen TypeError aus.
Sicherheit: Nur setHTML() und Document.parseHTML() entfernen garantiert XSS-gefährliche Inhalte wie Skripte und Event-Handler-Attribute. Wenn du einen Sanitizer an setHTMLUnsafe() übergibst, wird exakt deine Konfiguration angewendet. Dann kann auch ein <script> durchkommen. In diesem Fall solltest du vorher sanitizer.removeUnsafe() aufrufen.
Ein Sanitizer ersetzt keine Content Security Policy und keine serverseitige Prüfung. Setze ihn zusätzlich ein, zum Beispiel zusammen mit Trusted Types.
Eine Sperrliste ist weniger robust als eine Erlaubnisliste, weil neue oder unbekannte Elemente automatisch durchgelassen werden. Für Nutzereingaben ist eine Erlaubnisliste die bessere Wahl.
Ein Sanitizer lässt sich wiederverwenden. Lege ihn einmal an, statt ihn bei jedem Aufruf neu zu erzeugen.

Siehe auch

new Animation() new Profiler() new Range() new Audio() new CSSRotate() new AmbientLightSensor() new CSSMathInvert()