Document.replaceChildren() — Methode · JavaScript-Referenz

Signatur

Document.prototype.replaceChildren(...nodes)

Beschreibung

Document.replaceChildren() entfernt in einem einzigen Schritt alle direkten Kinder eines Dokuments, also z. B. <!DOCTYPE>, das Wurzelelement <html> und Kommentare auf oberster Ebene. Danach fügt sie die übergebenen Knoten in der angegebenen Reihenfolge ein. Die Methode stammt aus dem ParentNode-Mixin und gibt es genauso auf Element und DocumentFragment.

Gebraucht wird sie vor allem bei Dokumenten, die man selbst erzeugt oder verarbeitet: bei XML-Dokumenten aus DOMParser, bei Dokumenten aus document.implementation.createHTMLDocument() oder createDocument() und bei Vorlagen, deren Wurzel man komplett austauschen will. Das ist kürzer als eine Schleife mit removeChild() und anschließendem appendChild(). Außerdem prüft die Methode vorab, ob die neue Knotenmenge gültig ist.

Dabei gelten die Regeln für Kinder eines Dokuments:

höchstens ein Element, also genau ein Wurzelelement,
höchstens ein DocumentType, und der muss vor dem Element stehen,
dazu beliebig viele Comment- und ProcessingInstruction-Knoten,
keine Textknoten. Übergebene Zeichenketten werden in Textknoten umgewandelt und führen deshalb zu einem Fehler.

Verstößt die neue Menge gegen diese Regeln, wirft die Methode einen HierarchyRequestError. In diesem Fall bleibt das Dokument unverändert, weil die Prüfung vor dem Entfernen passiert.

Parameter

Name	Typ	Default	Beschreibung
$...nodes	Node \| string		Null oder mehr Knoten, die die bisherigen Kinder ersetzen. Bei einem `Document` sind nur ein Element, ein `DocumentType`, Kommentare und Verarbeitungsanweisungen erlaubt. Zeichenketten werden zwar in Textknoten umgewandelt, sind hier aber ungültig. Ohne Argumente werden alle Kinder entfernt.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Das Dokument wird direkt verändert.

Beispiele

Selbst erzeugtes Dokument vollständig leeren

const doc = document.implementation.createHTMLDocument('Entwurf');
console.log(doc.childNodes.length); // Doctype + <html>

// Ohne Argumente: alle Kinder entfernen
doc.replaceChildren();
console.log(doc.childNodes.length);
console.log(doc.documentElement);

2 0 null

Wurzelelement eines XML-Dokuments austauschen

const parser = new DOMParser();
const xml = parser.parseFromString('<config><alt/></config>', 'application/xml');

const root = xml.createElement('settings');
const theme = xml.createElement('theme');
theme.textContent = 'dark';
root.append(theme);

// Kommentar + neues Wurzelelement statt der alten Struktur
xml.replaceChildren(xml.createComment(' automatisch generiert '), root);

console.log(new XMLSerializer().serializeToString(xml));

<settings><theme>dark</theme></settings>

HTML-Dokument mit Doctype neu aufbauen

const doc = document.implementation.createHTMLDocument('Alt');

const doctype = doc.implementation.createDocumentType('html', '', '');
const html = doc.createElement('html');
html.innerHTML = '<head><title>Neu</title></head><body><p>Hallo Welt</p></body>';

// Doctype muss vor dem Wurzelelement stehen
doc.replaceChildren(doctype, html);

console.log(doc.doctype.name);
console.log(doc.title);
console.log(doc.body.textContent);

html Neu Hallo Welt

Ungültige Kinder abfangen

const doc = document.implementation.createHTMLDocument('Test');

try {
  // Zwei Wurzelelemente sind nicht erlaubt
  doc.replaceChildren(doc.createElement('a'), doc.createElement('b'));
} catch (err) {
  console.log(err.name);
}

try {
  // Zeichenketten werden zu Textknoten, die in einem Document unzulässig sind
  doc.replaceChildren('Nur Text');
} catch (err) {
  console.log(err.name);
}

// Das Dokument ist unverändert geblieben
console.log(doc.title);

HierarchyRequestError HierarchyRequestError Test

// Wichtig · Fallstricke

Vorsicht beim aktiven Dokument: document.replaceChildren() auf der gerade angezeigten Seite entfernt die gesamte Seite, einschließlich <head>, Stylesheets und Doctype. Bereits laufende Skripte laufen weiter, aber das Layout ist weg. Meist will man stattdessen document.body.replaceChildren() oder element.replaceChildren() aufrufen.
HierarchyRequestError: Die Methode wirft diesen Fehler bei mehr als einem Element, bei mehr als einem Doctype, bei einem Doctype nach dem Element und bei Textknoten bzw. Zeichenketten. Die Prüfung läuft vor jeder Änderung, deshalb bleibt ein ungültiger Aufruf ohne Wirkung.
Knoten, die schon woanders im DOM hängen, werden verschoben und nicht kopiert. Knoten aus einem anderen Dokument werden automatisch übernommen. Wer eine Kopie braucht, nutzt cloneNode(true) oder document.importNode().
Wird der Doctype ersetzt, kann das den Rendermodus (Quirks- bzw. Standardmodus) bei bereits geladenen Dokumenten nicht nachträglich ändern.
Kompatibilität: Alle aktuellen Browser unterstützen die Methode (Chrome/Edge 86, Firefox 78, Safari 14). Für ältere Umgebungen gibt es einen Ersatz: in einer Schleife removeChild() aufrufen, danach append().

Siehe auch

Element.replaceChildren() Document.append() Document.prepend() Node.removeChild() Document.documentElement DOMImplementation.createHTMLDocument() DOMParser