DocumentFragment.replaceChildren() — Methode · JavaScript-Referenz

Signatur

DocumentFragment.prototype.replaceChildren(...nodes)

Beschreibung

replaceChildren() entfernt zuerst alle Kindknoten des Fragments und fügt dann die übergebenen Knoten in der angegebenen Reihenfolge ein. Das Ganze passiert in einem einzigen Schritt. Zeichenketten werden automatisch in Text-Knoten umgewandelt. Sie werden also nicht als HTML ausgewertet.

Die Methode ist praktisch, wenn du ein Fragment als wiederverwendbaren Puffer nutzt, etwa beim Aufbau von Listen, Tabellenzeilen oder Vorlagen, bevor sie ins DOM eingefügt werden. Ein Aufruf ohne Argumente leert das Fragment vollständig. Das ist die moderne Alternative zu einer Schleife mit removeChild().

Übergebene Knoten, die bereits an anderer Stelle im DOM hängen, werden dorthin verschoben und nicht kopiert. Wenn du das Original behalten willst, übergib vorher eine Kopie mit cloneNode(true).

Parameter

Name	Typ	Default	Beschreibung
$...nodes	Node \| string		Beliebig viele `Node`-Objekte oder Zeichenketten, die die bisherigen Kinder ersetzen. Zeichenketten werden zu `Text`-Knoten. Ohne Argumente wird das Fragment geleert.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Fragment-Inhalt austauschen

const frag = new DocumentFragment();
frag.append(document.createElement('p'), 'Alter Text');
console.log(frag.childNodes.length);

const h2 = document.createElement('h2');
h2.textContent = 'Neue Überschrift';
frag.replaceChildren(h2, 'Neuer Text');

console.log(frag.childNodes.length);
console.log(frag.firstChild.nodeName, '|', frag.lastChild.textContent);

2 2 H2 | Neuer Text

Fragment leeren und als Puffer wiederverwenden

const buffer = new DocumentFragment();
const liste = document.createElement('ul');

const render = (eintraege) => {
  buffer.replaceChildren(); // Puffer leeren
  for (const text of eintraege) {
    const li = document.createElement('li');
    li.textContent = text;
    buffer.append(li);
  }
  liste.replaceChildren(buffer); // Fragment-Inhalt in die Liste verschieben
};

render(['Äpfel', 'Birnen']);
render(['Kirschen']);
console.log(liste.children.length, liste.textContent);

1 Kirschen

Zeichenketten werden nicht als HTML ausgewertet

const frag = new DocumentFragment();
frag.replaceChildren('<b>fett?</b>');
console.log(frag.firstChild.nodeType === Node.TEXT_NODE);
console.log(frag.firstChild.textContent);

true <b>fett?</b>

// Wichtig · Fallstricke

Verschieben statt Kopieren: Knoten, die bereits im DOM oder in einem anderen Fragment hängen, werden dort entfernt. Wenn du das Original behalten willst, übergib stattdessen node.cloneNode(true).
Ungültige Hierarchie: Übergibst du einen Knoten, der nicht eingefügt werden darf, z. B. einen Vorfahren des Ziels oder ein Document, wird ein HierarchyRequestError (DOMException) geworfen. In diesem Fall bleibt das Fragment unverändert.
Sicherheit: Zeichenketten werden als Text eingefügt und nicht als HTML ausgewertet. Die Methode ist daher, anders als innerHTML, unkritisch für XSS.
Kompatibilität: Verfügbar seit Chrome/Edge 86, Firefox 78 und Safari 14. Für ältere Browser kannst du das Fragment mit while (frag.firstChild) frag.firstChild.remove() leeren und danach append() aufrufen.
Gleichnamige Methoden gibt es auch auf Element und Document.

Siehe auch

DocumentFragment DocumentFragment.append() DocumentFragment.prepend() Element.replaceChildren() Document.replaceChildren() Node.cloneNode()