CharacterData.replaceWith() — Methode · JavaScript-Referenz

Signatur

CharacterData.prototype.replaceWith(...nodes)

Beschreibung

Die Methode replaceWith() gehört zum Mixin ChildNode und steht daher auf allen CharacterData-Knoten zur Verfügung, also auf Text, Comment, CDATASection und ProcessingInstruction. Sie entfernt den aktuellen Knoten aus seinem Elternknoten und setzt an genau dieser Stelle die übergebenen Knoten bzw. Zeichenketten ein, und zwar in der angegebenen Reihenfolge.

Übergebene Zeichenketten werden automatisch in Text-Knoten umgewandelt. HTML-Code wird dabei also nicht interpretiert. Deshalb eignet sich die Methode gut, um Nutzereingaben sicher einzufügen. Werden mehrere Argumente übergeben, fasst der Browser sie intern zu einem DocumentFragment zusammen und fügt sie in einem Schritt ein.

Typische Einsatzfälle sind das Hervorheben von Suchbegriffen in einem Textknoten (den Text aufteilen und Teile in  einpacken), das Ersetzen von Platzhalter-Kommentaren wie  durch echte Inhalte oder das Umwandeln von reinem Text in Links. Im Vergleich zum älteren parent.replaceChild(neu, alt) braucht man keine Referenz auf den Elternknoten und kann direkt mehrere Knoten übergeben.

Hat der Knoten keinen Elternknoten, passiert nichts und es wird kein Fehler ausgelöst. Knoten, die bereits an anderer Stelle im DOM hängen, werden verschoben und nicht kopiert.

Parameter

Name	Typ	Default	Beschreibung
$...nodes	(Node \| string)[]		Beliebig viele `Node`-Objekte oder Zeichenketten, die den aktuellen Knoten ersetzen. Zeichenketten werden als `Text`-Knoten eingefügt. Ohne Argumente wird der Knoten nur entfernt, genau wie mit `remove()`.

Beispiele

Textknoten durch Text und Element ersetzen

const p = document.createElement('p');
p.textContent = 'Hallo Welt';
const text = p.firstChild; // Text-Knoten

const strong = document.createElement('strong');
strong.textContent = 'Welt';

text.replaceWith('Hallo ', strong, '!');
console.log(p.outerHTML);

Hallo Welt!

Suchbegriff in einem Textknoten hervorheben

const highlight = (textNode, term) => {
  const parts = textNode.data.split(term);
  if (parts.length < 2) return;
  const nodes = parts.flatMap((part, i) => {
    if (i === 0) return [part];
    const mark = document.createElement('mark');
    mark.textContent = term;
    return [mark, part];
  });
  textNode.replaceWith(...nodes);
};

const div = document.createElement('div');
div.textContent = 'JavaScript macht Spaß, JavaScript ist überall.';
highlight(div.firstChild, 'JavaScript');
console.log(div.innerHTML);

JavaScript macht Spaß, JavaScript ist überall.

Platzhalter-Kommentar durch Inhalt ersetzen

const list = document.createElement('ul');
list.innerHTML = '<li>Erster</li><!-- items --><li>Letzter</li>';

const placeholder = [...list.childNodes]
  .find((n) => n.nodeType === Node.COMMENT_NODE && n.data.trim() === 'items');

const items = ['Zweiter', 'Dritter'].map((label) => {
  const li = document.createElement('li');
  li.textContent = label;
  return li;
});

placeholder.replaceWith(...items);
console.log(list.children.length);

4

Zeichenketten werden nicht als HTML interpretiert

const span = document.createElement('span');
span.textContent = 'alt';

const userInput = '<img src=x onerror=alert(1)>';
span.firstChild.replaceWith(userInput);

console.log(span.innerHTML);
console.log(span.children.length);

<img src=x onerror=alert(1)> 0

// Wichtig · Fallstricke

Kein Elternknoten: Ist der Knoten nicht eingehängt (parentNode === null), bewirkt der Aufruf nichts. Es wird kein Fehler ausgelöst.
Verschieben statt Kopieren: Übergebene Knoten, die schon im DOM stehen, werden an ihrer alten Stelle entfernt. Wer eine Kopie braucht, muss vorher cloneNode(true) aufrufen.
Referenz bleibt bestehen: Die Variable zeigt danach auf einen abgekoppelten Knoten. Weitere Aufrufe wie textNode.after() haben dann keine Wirkung mehr.
Fehler: Ein HierarchyRequestError (DOMException) tritt auf, wenn ein Knoten an eine unzulässige Stelle käme, zum Beispiel ein Vorfahre des Elternknotens oder ein zweites Element direkt unter document.
Sicherheit: Zeichenketten werden als reiner Text eingefügt. Das macht die Methode im Unterschied zu innerHTML oder insertAdjacentHTML sicher gegen XSS.
Kompatibilität: Wird von allen modernen Browsern unterstützt (Chrome 54+, Firefox 49+, Safari 10+, Edge 17+), aber nicht vom Internet Explorer. Dort bleibt nur parentNode.replaceChild().
Direkt aufeinanderfolgende Textknoten werden nicht automatisch zusammengeführt. Dafür gibt es parent.normalize().

Siehe auch

Node.normalize() Text CharacterData.replaceData() CharacterData.deleteData() CharacterData.remove()