Sanitizer.setDataAttributes() — Methode · JavaScript-Referenz

Signatur

Sanitizer.prototype.setDataAttributes(allow)

Beschreibung

Mit setDataAttributes() änderst du die Einstellung dataAttributes einer bestehenden Sanitizer-Instanz. Bei true bleiben alle benutzerdefinierten data-*-Attribute beim Bereinigen erhalten, zum Beispiel data-id und data-user-role. Bei false bleiben nur die data-*-Attribute erhalten, die ausdrücklich über allowAttribute() oder die Konfiguration attributes erlaubt wurden.

Die Methode ist nützlich, wenn dein Frontend-Code seinen Zustand in data-*-Attributen speichert (Stimulus, Alpine, eigene Komponenten) und du nicht jedes Attribut einzeln eintragen willst. data-*-Attribute gelten als harmlos, weil der Browser sie nie selbst ausführt. Sie werden nur zum Risiko, wenn dein eigenes Skript ihre Werte unsicher weiterverarbeitet.

Die Einstellung wirkt nur bei einer Konfiguration mit Erlaubnisliste (attributes). Nutzt der Sanitizer stattdessen eine Sperrliste (removeAttributes), bleiben data-*-Attribute ohnehin erhalten, solange du sie nicht ausdrücklich entfernst. Wird dataAttributes auf true gesetzt, entfernt der Browser außerdem einzeln eingetragene data-*-Einträge aus den Attributlisten, damit die Konfiguration keine doppelten Angaben enthält.

Die geänderte Instanz übergibst du anschließend an Element.setHTML(), ShadowRoot.setHTML() oder Document.parseHTML().

Parameter

Name	Typ	Default	Beschreibung
$allow Pflicht	boolean		`true`: alle `data-`-Attribute zulassen. `false`: nur ausdrücklich erlaubte `data-`-Attribute behalten.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn sich die Konfiguration dadurch geändert hat. false, wenn sie unverändert blieb, etwa weil der Wert schon gesetzt war oder keine Erlaubnisliste für Attribute besteht. Ältere Entwürfe und Umsetzungen geben stattdessen undefined zurück.

Beispiele

Alle data-*-Attribute bei einer Erlaubnisliste zulassen

const sanitizer = new Sanitizer({
  elements: ['div', 'p', 'button'],
  attributes: ['class']
});

sanitizer.setDataAttributes(true);

const container = document.querySelector('#ausgabe');
container.setHTML(
  '<button class="btn" data-action="speichern" data-id="42" onclick="alert(1)">OK</button>',
  { sanitizer }
);

console.log(container.innerHTML);

data-*-Attribute wieder einschränken und nur eines gezielt erlauben

const sanitizer = new Sanitizer({
  elements: ['span'],
  attributes: ['class'],
  dataAttributes: true
});

// Pauschale Freigabe zurücknehmen
sanitizer.setDataAttributes(false);
// Nur data-tooltip erlauben
sanitizer.allowAttribute('data-tooltip');

const el = document.createElement('div');
el.setHTML(
  '<span data-tooltip="Hinweis" data-tracking="abc">Text</span>',
  { sanitizer }
);
console.log(el.innerHTML);

Rückgabewert und Konfiguration prüfen

const sanitizer = new Sanitizer({ elements: ['p'], attributes: ['data-x'] });

console.log(sanitizer.setDataAttributes(true));  // ändert die Konfiguration
console.log(sanitizer.setDataAttributes(true));  // bereits gesetzt

const config = sanitizer.get();
console.log(config.dataAttributes);
console.log(config.attributes); // data-x wurde als überflüssig entfernt

true false true []

// Wichtig · Fallstricke

Experimentelle API: Die HTML Sanitizer API ist noch nicht in allen Browsern verfügbar und hat sich mehrfach geändert. Frühere Versionen hatten eine ganz andere Schnittstelle, zum Beispiel sanitizeFor(). Prüfe vorher, ob die Methode existiert: 'Sanitizer' in window && 'setDataAttributes' in Sanitizer.prototype. Als Ausweichlösung eignet sich etwa DOMPurify.
Nur bei einer Erlaubnisliste wirksam: Nutzt der Sanitizer removeAttributes, hat der Aufruf keine Wirkung und gibt false zurück.
Sicherheit: data-*-Attribute sind für den Browser harmlos. Liest dein eigenes Skript ihre Werte aber aus und übergibt sie ungeprüft an innerHTML, eval(), new Function() oder eine URL, entsteht trotzdem eine XSS-Lücke. Frameworks, die Attributwerte als Code ausführen, verdienen hier besondere Vorsicht.
Unsichere Methoden: setHTMLUnsafe() und parseHTMLUnsafe() entfernen keine Ereignis-Attribute wie onclick, außer du rufst vorher removeUnsafe() auf. Verwende für nicht vertrauenswürdige Eingaben die sicheren Varianten.
Die Einstellung verändert die Instanz direkt. Wird ein Sanitizer an mehreren Stellen gemeinsam genutzt, wirkt die Änderung überall.

Siehe auch

Sanitizer Sanitizer.get() Sanitizer.removeAttribute() Sanitizer.allowAttribute() Sanitizer.setComments()