Sanitizer.allowAttribute() — Methode · JavaScript-Referenz

Signatur

Sanitizer.prototype.allowAttribute(attribute)

Beschreibung

Mit allowAttribute() änderst du die Konfiguration eines vorhandenen Sanitizer-Objekts: Ein Attribut wird für alle Elemente erlaubt. Die Methode ist das Gegenstück zu removeAttribute(). Du brauchst sie, wenn du einen Sanitizer Schritt für Schritt aufbaust, statt die ganze Konfiguration auf einmal an den Konstruktor zu übergeben.

Was genau passiert, hängt von der Art der Konfiguration ab:

Nutzt der Sanitizer eine Positivliste (attributes), wird das Attribut dort eingetragen.
Nutzt er eine Sperrliste (removeAttributes), wird das Attribut dort gestrichen.

In beiden Fällen bereinigt der Browser die Konfiguration so, dass sie widerspruchsfrei bleibt. Einträge pro Element, die dasselbe Attribut entfernen, werden dabei angepasst.

Den fertigen Sanitizer übergibst du an Element.setHTML(), ShadowRoot.setHTML() oder Document.parseHTML(). Den aktuellen Stand der Konfiguration kannst du jederzeit mit Sanitizer.prototype.get() auslesen.

Parameter

Name	Typ	Default	Beschreibung
$attribute Pflicht	string \| { name: string, namespace?: string \| null }		Das Attribut, das erlaubt werden soll. Ein String wie `"title"` steht für ein Attribut ohne Namensraum. Mit einem Objekt aus `name` und `namespace` gibst du Attribute mit Namensraum an, z. B. `xlink:href` in SVG.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn sich die Konfiguration geändert hat. false, wenn das Attribut schon erlaubt war. (Ältere Entwürfe der Spezifikation gaben undefined zurück.)

Beispiele

Positivliste Schritt für Schritt erweitern

// Erlaubt nur Absätze und Links, zunächst ohne Attribute
const sanitizer = new Sanitizer({
  elements: ['p', 'a'],
  attributes: []
});

// Attribute global erlauben
sanitizer.allowAttribute('href');
sanitizer.allowAttribute('title');

const userHtml = '<p title="Hinweis" class="x">Mehr unter <a href="https://example.com" id="l">hier</a></p>';
document.querySelector('#kommentar').setHTML(userHtml, { sanitizer });

console.log(document.querySelector('#kommentar').innerHTML);

<p title="Hinweis">Mehr unter <a href="https://example.com">hier</a></p>

Rückgabewert und Konfiguration prüfen

const sanitizer = new Sanitizer({ attributes: ['lang'] });

console.log(sanitizer.allowAttribute('dir'));  // neu hinzugefügt
console.log(sanitizer.allowAttribute('dir'));  // war schon erlaubt

const names = sanitizer.get().attributes.map((a) => a.name);
console.log(names);

true false ["dir", "lang"]

Attribut mit Namensraum (SVG xlink:href) freigeben

if ('Sanitizer' in window && 'allowAttribute' in Sanitizer.prototype) {
  const sanitizer = new Sanitizer();
  sanitizer.allowAttribute({
    name: 'href',
    namespace: 'http://www.w3.org/1999/xlink'
  });

  const svg = '<svg><use xlink:href="#icon-home"></use></svg>';
  document.querySelector('#icons').setHTML(svg, { sanitizer });
} else {
  console.warn('Sanitizer API wird nicht unterstützt – bitte Fallback wie DOMPurify verwenden.');
}

Attribut aus einer Sperrliste wieder freigeben

// Sperrliste: 'style' und 'class' werden entfernt
const sanitizer = new Sanitizer({ removeAttributes: ['style', 'class'] });

// 'class' soll doch erhalten bleiben
sanitizer.allowAttribute('class');

console.log(sanitizer.get().removeAttributes.map((a) => a.name));

["style"]

// Wichtig · Fallstricke

Kein Freifahrtschein für gefährliche Attribute: Die sicheren Methoden setHTML() und Document.parseHTML() entfernen Event-Handler wie onclick und javascript:-URLs immer, auch wenn du sie mit allowAttribute() erlaubst. Nur setHTMLUnsafe() und Document.parseHTMLUnsafe() halten sich wörtlich an die Konfiguration. Diese Methoden nur mit vertrauenswürdigen Eingaben nutzen, sonst drohen XSS-Lücken.
Global statt pro Element: Das Attribut gilt für alle erlaubten Elemente. Soll es nur auf bestimmten Elementen erlaubt sein, verwende allowElement({ name: 'a', attributes: ['href'] }).
data-*-Attribute steuerst du am einfachsten gesammelt mit setDataAttributes(true), statt jedes einzeln freizugeben.
Wirkt nur auf erlaubte Elemente: Ist ein Element nicht erlaubt, wird es samt seiner Attribute entfernt.
Kompatibilität: Die Sanitizer API ist experimentell und die Spezifikation ändert sich noch. Die frühere Variante mit sanitize() und allowAttributes ist veraltet. Prüfe vor der Nutzung, ob die API vorhanden ist ('Sanitizer' in window), und halte einen Fallback wie DOMPurify bereit.

Siehe auch

Sanitizer Sanitizer.get() Sanitizer.removeAttribute() Sanitizer.allowElement() Sanitizer.setDataAttributes()