Sanitizer.replaceElementWithChildren() — Methode · JavaScript-Referenz

Signatur

Sanitizer.prototype.replaceElementWithChildren(element)

Beschreibung

Mit replaceElementWithChildren() ändern Sie eine Sanitizer-Instanz so, dass ein bestimmtes Element beim Bereinigen aufgelöst wird: Das Element-Tag verschwindet, sein Inhalt (Text und Kindelemente) bleibt an derselben Stelle erhalten. Aus Hallo wird also einfach Hallo.

Das ist praktisch, wenn Formatierungen oder Container-Elemente aus Benutzereingaben (z. B. aus eingefügtem Text aus Word oder von Webseiten) nicht erwünscht sind, deren Text aber nicht verloren gehen soll. Im Unterschied dazu entfernt removeElement() das Element mitsamt seinem Inhalt.

Intern wird das Element in die Liste replaceWithChildrenElements der Konfiguration aufgenommen und gleichzeitig aus den Listen elements (erlaubt) und removeElements (entfernt) gestrichen. Der Sanitizer wird anschließend an Element.setHTML(), ShadowRoot.setHTML() oder Document.parseHTML() übergeben – ebenso an die „unsicheren“ Varianten wie setHTMLUnsafe().

Parameter

Name	Typ	Default	Beschreibung
$element Pflicht	string \| { name: string, namespace?: string \| null }		Das zu ersetzende Element. Entweder als Tag-Name (z. B. `"b"`) – dann gilt der HTML-Namensraum – oder als Objekt mit `name` und optionalem `namespace` (z. B. `"http://www.w3.org/2000/svg"`).

Beispiele

Fettschrift entfernen, Text behalten

const sanitizer = new Sanitizer();
sanitizer.replaceElementWithChildren("b");

const ziel = document.querySelector("#vorschau");
ziel.setHTML("<p>Hallo <b>Welt</b>!</p>", { sanitizer });

console.log(ziel.innerHTML);

Hallo Welt!

Mehrere Formatierungs-Tags bei eingefügtem Text auflösen

const sanitizer = new Sanitizer();
["span", "font", "strong", "em"].forEach((tag) =>
  sanitizer.replaceElementWithChildren(tag)
);

const editor = document.querySelector("#editor");
editor.addEventListener("paste", (event) => {
  event.preventDefault();
  const html = event.clipboardData.getData("text/html");
  editor.setHTML(html, { sanitizer });
});

Rückgabewert und Konfiguration prüfen

const sanitizer = new Sanitizer({ elements: ["p", "div"] });

console.log(sanitizer.replaceElementWithChildren("div")); // neu
console.log(sanitizer.replaceElementWithChildren("div")); // bereits gesetzt

const config = sanitizer.get();
console.log(config.replaceWithChildrenElements.map((e) => e.name));
console.log(config.elements.map((e) => e.name));

true false ["div"] ["p"]

Mit Feature-Erkennung verwenden

if ("Sanitizer" in window && "replaceElementWithChildren" in Sanitizer.prototype) {
  const sanitizer = new Sanitizer();
  sanitizer.replaceElementWithChildren({ name: "a" });
  const doc = Document.parseHTML('<p><a href="/x">Link</a>-Text</p>', { sanitizer });
  console.log(doc.body.innerHTML);
} else {
  console.warn("Sanitizer API nicht verfügbar – Fallback (z. B. DOMPurify) nutzen.");
}

Link-Text

// Wichtig · Fallstricke

Browser-Unterstützung: Die HTML Sanitizer API ist experimentell und nur in wenigen Browsern verfügbar. Frühere Chrome-Implementierungen hatten eine andere API (sanitizeFor() usw.), die wieder entfernt wurde. Prüfen Sie die Unterstützung per Feature-Erkennung und sehen Sie für den Produktivbetrieb eine Bibliothek wie DOMPurify als Fallback vor.
Sicherheit: Die sicheren Methoden (setHTML(), parseHTML()) entfernen gefährliche Elemente wie <script> immer, unabhängig von der Konfiguration. Bei setHTMLUnsafe() bzw. parseHTMLUnsafe() gilt das nicht – dort müssen Sie selbst für eine sichere Konfiguration sorgen.
Das <html>-Element kann nicht durch seine Kinder ersetzt werden; der Aufruf liefert dann false.
Ein zuvor per allowElement() erlaubtes oder per removeElement() entferntes Element wird durch den Aufruf aus diesen Listen gestrichen – die zuletzt aufgerufene Methode gewinnt.
Tag-Namen als String beziehen sich immer auf den HTML-Namensraum. Für SVG- oder MathML-Elemente das Objekt mit namespace verwenden.

Siehe auch

Sanitizer Sanitizer.get() Sanitizer.allowAttribute() Sanitizer.removeElement() Sanitizer.allowElement()