DocumentFragment.append() — Methode · JavaScript-Referenz

Signatur

DocumentFragment.prototype.append(...nodes)

Beschreibung

Die Methode append() hängt eine oder mehrere Knoten bzw. Zeichenketten ans Ende eines DocumentFragment an. Zeichenketten werden automatisch in Text-Knoten umgewandelt und nicht als HTML interpretiert. Deshalb eignet sich die Methode auch für Benutzereingaben.

Ein DocumentFragment ist ein leichtgewichtiger Container, der nicht zum aktiven DOM-Baum gehört. Man baut darin viele Elemente zusammen und fügt alles mit einem einzigen Aufruf (z. B. parent.append(fragment)) ins Dokument ein. So wird das Layout nur einmal neu berechnet, statt bei jedem einzelnen Element.

Anders als Node.prototype.appendChild() nimmt append() mehrere Argumente an, erlaubt Zeichenketten und gibt undefined zurück statt des eingefügten Knotens. Knoten, die schon an einer anderen Stelle im DOM hängen, werden verschoben und nicht kopiert.

Parameter

Name	Typ	Default	Beschreibung
$...nodes	Node \| string		Beliebig viele Knoten oder Zeichenketten, die in dieser Reihenfolge angehängt werden. Zeichenketten werden zu `Text`-Knoten. Ohne Argumente passiert nichts.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Mehrere Aufrufe lassen sich daher nicht verketten.

Beispiele

Knoten und Text gemeinsam anhängen

const fragment = new DocumentFragment();
const strong = document.createElement('strong');
strong.textContent = 'Hinweis:';

// Knoten und Zeichenkette in einem Aufruf
fragment.append(strong, ' Bitte speichern Sie Ihre Änderungen.');

console.log(fragment.childNodes.length);
console.log(fragment.textContent);

2 Hinweis: Bitte speichern Sie Ihre Änderungen.

Liste performant aufbauen und einmalig einfügen

const users = ['Anna', 'Ben', 'Clara'];
const list = document.querySelector('#user-list');
const fragment = document.createDocumentFragment();

for (const name of users) {
  const li = document.createElement('li');
  li.append(name); // sicher: kein HTML-Parsing
  fragment.append(li);
}

// Nur ein Einfügen ins DOM → nur ein Reflow
list.append(fragment);
console.log(list.children.length, fragment.childNodes.length);

3 0

Spread-Syntax mit einem Array von Elementen

const labels = ['Start', 'Profil', 'Abmelden'];
const buttons = labels.map((label) => {
  const btn = document.createElement('button');
  btn.type = 'button';
  btn.textContent = label;
  return btn;
});

const fragment = new DocumentFragment();
fragment.append(...buttons);
document.querySelector('nav').append(fragment);
console.log(fragment.childElementCount);

Zeichenketten werden nicht als HTML interpretiert

const fragment = new DocumentFragment();
const userInput = '<img src=x onerror=alert(1)>';

fragment.append(userInput);

console.log(fragment.firstChild.nodeType === Node.TEXT_NODE);
console.log(fragment.querySelector('img'));

true null

// Wichtig · Fallstricke

Das Fragment wird geleert: Wenn ein DocumentFragment ins DOM eingefügt wird, wandern seine Kinder dorthin und das Fragment ist danach leer. Für eine Wiederverwendung erst mit fragment.cloneNode(true) kopieren.
Verschieben statt Kopieren: Ein Knoten, der schon im Dokument oder in einem anderen Fragment hängt, wird von dort entfernt.
Kein Rückgabewert: Anders als appendChild() gibt append() undefined zurück.
Sicherheit: Zeichenketten werden immer zu Textknoten und nicht als HTML ausgewertet. Das ist XSS-sicher, im Gegensatz zu innerHTML.
Fehler: Bei ungültigen Einfügungen wird eine HierarchyRequestError-DOMException geworfen, z. B. wenn ein Vorfahre in sich selbst eingefügt werden soll.
Kompatibilität: Wird von allen modernen Browsern unterstützt, nicht aber vom Internet Explorer. Dort bleibt nur appendChild() oder ein Polyfill.
Andere Werte wie Zahlen werden in Zeichenketten umgewandelt: append(42) erzeugt den Textknoten "42".

Siehe auch

Element.append() DocumentFragment.getElementById() DocumentFragment.prepend() DocumentFragment.moveBefore() DocumentFragment.querySelector()