SanitizerConfig — Schnittstelle · JavaScript-Referenz

Signatur

dictionary SanitizerConfig

Beschreibung

SanitizerConfig ist ein Dictionary, also ein einfaches JavaScript-Objekt, und keine Klasse. Es beschreibt die Filterregeln der HTML Sanitizer API. Man übergibt es an new Sanitizer(config) oder direkt als Option sanitizer an Element.setHTML(), ShadowRoot.setHTML(), Document.parseHTML() sowie an die „Unsafe“-Varianten setHTMLUnsafe() und parseHTMLUnsafe(). Umgekehrt gibt Sanitizer.prototype.get() die aktuelle Konfiguration als SanitizerConfig zurück.

Die Konfiguration arbeitet entweder mit Positivlisten (elements, attributes) oder mit Sperrlisten (removeElements, removeAttributes). Bei einer Positivliste bleibt nur das Aufgeführte erhalten. Bei einer Sperrliste wird nur das Aufgeführte entfernt. Mit replaceWithChildrenElements entfernen Sie ein Element, behalten aber seinen Inhalt. Das ist nützlich, um zum Beispiel <span>- oder <font>-Hüllen loszuwerden, ohne den Text zu verlieren. comments und dataAttributes steuern, ob HTML-Kommentare und data-*-Attribute erhalten bleiben.

Elemente und Attribute geben Sie als String an ("div") oder als Objekt mit Namensraum ({ name: "svg", namespace: "http://www.w3.org/2000/svg" }). Elemente in elements können zusätzlich eigene attributes- und removeAttributes-Listen haben. So erlauben Sie etwa href nur auf <a>.

Wichtig: Die sicheren Methoden (setHTML(), parseHTML()) entfernen XSS-gefährliche Inhalte wie <script>, Event-Handler-Attribute (onclick …) oder javascript:-URLs immer, auch wenn die Konfiguration sie erlaubt. Die unsicheren Methoden wenden nur die Konfiguration an.

Parameter

Name	Typ	Beschreibung
$elements	Array<string \| {name: string, namespace?: string, attributes?: Array, removeAttributes?: Array}>	Positivliste der erlaubten Elemente. Nicht aufgeführte Elemente werden samt Inhalt entfernt. Pro Element sind eigene `attributes`/`removeAttributes` möglich. Darf nicht zusammen mit `removeElements` verwendet werden.
$removeElements	Array<string \| {name: string, namespace?: string}>	Sperrliste: Diese Elemente werden samt Inhalt entfernt, alle anderen bleiben erhalten.
$replaceWithChildrenElements	Array<string \| {name: string, namespace?: string}>	Diese Elemente werden entfernt, ihre Kindknoten bleiben aber an ihrer Stelle erhalten.
$attributes	Array<string \| {name: string, namespace?: string \| null}>	Positivliste der Attribute, die auf allen Elementen erlaubt sind. Darf nicht zusammen mit `removeAttributes` verwendet werden.
$removeAttributes	Array<string \| {name: string, namespace?: string \| null}>	Sperrliste der Attribute, die auf allen Elementen entfernt werden.
$comments	boolean	`true` behält HTML-Kommentare, `false` entfernt sie.
$dataAttributes	boolean	`true` erlaubt alle `data-*`-Attribute. Nur zusammen mit einer `attributes`-Positivliste sinnvoll bzw. zulässig.

Rückgabewert

Typ

SanitizerConfig

Beschreibung

Ein einfaches Objekt. Bekommt man es über Sanitizer.prototype.get(), enthält es die normalisierte Konfiguration mit Namensraum-Objekten statt Strings.

Beispiele

Positivliste für Kommentar-Inhalte mit setHTML()

const config = {
  elements: ["p", "b", "i", "em", "strong", "ul", "ol", "li",
    { name: "a", attributes: ["href", "title"] }],
  comments: false
};

const userInput = '<p onclick="alert(1)">Hallo <b>Welt</b> <img src=x><a href="https://example.org" target="_blank">Link</a></p>';

const box = document.querySelector("#kommentar");
box.setHTML(userInput, { sanitizer: config });

console.log(box.innerHTML);

<p>Hallo <b>Welt</b> <a href="https://example.org">Link</a></p>

Sanitizer-Instanz mit Sperrliste und replaceWithChildrenElements

const sanitizer = new Sanitizer({
  removeElements: ["iframe", "object"],
  replaceWithChildrenElements: ["span", "font"],
  removeAttributes: ["style"]
});

const doc = Document.parseHTML(
  '<div style="color:red"><font>Alt</font> <span>Text</span><iframe src="x"></iframe></div>',
  { sanitizer }
);

console.log(doc.body.innerHTML);

data-Attribute erlauben und Konfiguration auslesen

const sanitizer = new Sanitizer({
  elements: ["div", "button"],
  attributes: ["class"],
  dataAttributes: true
});

const el = document.createElement("div");
el.setHTML('<button class="btn" data-id="42" id="x">OK</button>', { sanitizer });
console.log(el.innerHTML);

// Normalisierte Konfiguration abrufen
const cfg = sanitizer.get();
console.log(cfg.dataAttributes, cfg.elements.length);

<button class="btn" data-id="42">OK</button> true 2

Feature-Erkennung mit Fallback

const safeInsert = (target, html) => {
  if ("setHTML" in Element.prototype) {
    target.setHTML(html, { sanitizer: { elements: ["p", "b", "i"] } });
  } else {
    // Fallback: nur Text einfügen (oder DOMPurify verwenden)
    target.textContent = html;
  }
};

safeInsert(document.body, "<p><b>Sicher</b><script>alert(1)</script></p>");

Siehe auch

Sanitizer AnalyserNode Animation AudioEncoder FencedFrameConfig