Sanitizer.allowElement() — Methode · JavaScript-Referenz

Signatur

Sanitizer.prototype.allowElement(element)

Beschreibung

Die Methode allowElement() ändert die Konfiguration einer bestehenden Sanitizer-Instanz so, dass ein bestimmtes Element beim Bereinigen nicht entfernt wird. Damit lässt sich eine Konfiguration schrittweise aufbauen, statt sie komplett im Konstruktor als Objekt anzugeben – praktisch etwa, wenn je nach Kontext (Kommentar, Profiltext, Redaktionsbereich) unterschiedlich viel Markup zugelassen werden soll.

Das Element kann als einfacher Name ("p") oder als Objekt übergeben werden. In der Objektform lassen sich zusätzlich ein Namensraum (z. B. für SVG oder MathML) sowie elementspezifische Attributlisten angeben: attributes erlaubt Attribute nur auf diesem Element, removeAttributes entfernt sie gezielt von diesem Element.

Die Methode passt sich der Art der Konfiguration an: Bei einer Positivliste (elements) wird das Element hinzugefügt; bei einer Negativliste (removeElements) wird es aus der Entfernungsliste gestrichen. Außerdem wird es aus replaceWithChildrenElements entfernt, falls es dort stand. Der konfigurierte Sanitizer wird anschließend an Element.setHTML(), ShadowRoot.setHTML(), Document.parseHTML() oder die entsprechenden …Unsafe()-Varianten übergeben.

Parameter

Name	Typ	Default	Beschreibung
$element Pflicht	string \| { name: string, namespace?: string \| null, attributes?: Array<string \| object>, removeAttributes?: Array<string \| object> }		Name des zu erlaubenden Elements oder ein Objekt mit `name`, optionalem `namespace` (Standard: `"http://www.w3.org/1999/xhtml"`) sowie optionalen elementspezifischen Listen `attributes` bzw. `removeAttributes`.

Beispiele

Minimale Positivliste für Benutzerkommentare aufbauen

// Leere Positivliste: zunächst ist kein Element erlaubt
const sanitizer = new Sanitizer({ elements: [] });

sanitizer.allowElement('p');
sanitizer.allowElement('strong');
sanitizer.allowElement('em');

const kommentar = document.querySelector('#kommentar');
kommentar.setHTML(
  '<p>Hallo <strong>Welt</strong> <img src=x onerror=alert(1)></p>',
  { sanitizer }
);

console.log(kommentar.innerHTML);

<p>Hallo <strong>Welt</strong> </p>

Links mit elementspezifischen Attributen erlauben

const sanitizer = new Sanitizer({ elements: ['p'] });

// href und title nur auf <a> zulassen
sanitizer.allowElement({
  name: 'a',
  attributes: ['href', 'title']
});

const ziel = document.querySelector('#ausgabe');
ziel.setHTML(
  '<p><a href="https://example.com" title="Beispiel" style="color:red">Link</a></p>',
  { sanitizer }
);

console.log(ziel.innerHTML);

Rückgabewert und Negativliste

// Negativliste: alles erlaubt außer den aufgeführten Elementen
const sanitizer = new Sanitizer({ removeElements: ['video', 'audio'] });

console.log(sanitizer.allowElement('video')); // aus removeElements entfernt
console.log(sanitizer.allowElement('video')); // keine Änderung mehr
console.log(sanitizer.get().removeElements);

true false [{ name: "audio", namespace: "http://www.w3.org/1999/xhtml" }]

SVG-Element mit Namensraum und Feature-Detection

if ('Sanitizer' in window) {
  const sanitizer = new Sanitizer({ elements: [] });
  sanitizer.allowElement({ name: 'svg', namespace: 'http://www.w3.org/2000/svg' });
  sanitizer.allowElement({
    name: 'circle',
    namespace: 'http://www.w3.org/2000/svg',
    attributes: ['cx', 'cy', 'r', 'fill']
  });

  document.querySelector('#icon').setHTML(
    '<svg><circle cx="10" cy="10" r="5" fill="red" onclick="alert(1)"/></svg>',
    { sanitizer }
  );
} else {
  console.warn('Sanitizer API nicht verfügbar – Fallback (z. B. DOMPurify) verwenden');
}

// Wichtig · Fallstricke

Sichere Methoden bleiben sicher: setHTML() und Document.parseHTML() entfernen XSS-gefährliche Elemente und Attribute (z. B. <script>, <iframe>, on*-Handler) immer – auch wenn sie per allowElement() erlaubt wurden. Nur setHTMLUnsafe() bzw. Document.parseHTMLUnsafe() respektieren eine solche Freigabe. Wer dort allowElement('script') aufruft, öffnet bewusst eine XSS-Lücke.
Namensraum beachten: Ein String wird immer als HTML-Element interpretiert. Für SVG- oder MathML-Elemente muss die Objektform mit namespace verwendet werden.
Kinder brauchen eigene Freigabe: Wird z. B. ul erlaubt, aber nicht li, werden die Listeneinträge trotzdem entfernt.
Globale vs. elementspezifische Attribute: attributes im Element-Objekt gilt nur für dieses Element; global erlaubte Attribute (allowAttribute()) gelten zusätzlich.
Kompatibilität: Die API ist experimentell und die Spezifikation hat sich mehrfach geändert (die frühere Chrome-Variante mit sanitize()/sanitizeFor() ist entfernt). Die Unterstützung ist auf wenige, aktuelle Browserversionen beschränkt – per 'Sanitizer' in window prüfen und einen Fallback wie DOMPurify vorsehen. Serverseitige Bereinigung bleibt trotzdem empfehlenswert.

Siehe auch

Sanitizer Sanitizer.get() Sanitizer.removeElement() Sanitizer.allowAttribute() Sanitizer.setComments()