new DocumentFragment() — Methode · JavaScript-Referenz

Signatur

new DocumentFragment()

Beschreibung

Mit new DocumentFragment() legst du ein leeres Dokumentfragment an. Das ist ein minimaler Knoten ohne eigenes Elternelement, der nicht Teil des aktiven DOM-Baums ist. Du kannst Elemente, Textknoten und andere Knoten hineinhängen, ohne dass der Browser dabei Layout oder Rendering neu berechnet.

Der Hauptnutzen ist das gesammelte Einfügen: Du baust viele Knoten erst im Fragment auf und hängst dann das Fragment mit appendChild(), append() oder insertBefore() ein. Dabei landet nicht das Fragment selbst im DOM, sondern nur seine Kinder. Das Fragment ist danach leer und lässt sich wiederverwenden.

Der Konstruktor macht dasselbe wie document.createDocumentFragment(). Das neue Fragment gehört zum globalen document des aktuellen Fensters (ownerDocument). Brauchst du ein Fragment für ein anderes Dokument, etwa aus einem iframe, dann rufst du dort createDocumentFragment() auf.

Rückgabewert

Typ

DocumentFragment

Beschreibung

Ein neues, leeres DocumentFragment. Sein ownerDocument ist das globale document, childNodes.length ist 0.

Beispiele

Leeres Fragment erzeugen und prüfen

const fragment = new DocumentFragment();

console.log(fragment.nodeType === Node.DOCUMENT_FRAGMENT_NODE);
console.log(fragment.nodeName);
console.log(fragment.childNodes.length);
console.log(fragment.ownerDocument === document);

true #document-fragment 0 true

Lange Liste in einem Schritt ins DOM einfügen

const fruits = ['Apfel', 'Birne', 'Kirsche', 'Mango'];
const list = document.querySelector('#fruit-list');

const fragment = new DocumentFragment();
for (const fruit of fruits) {
  const li = document.createElement('li');
  li.textContent = fruit;
  fragment.append(li);
}

// Nur ein Eingriff in den aktiven DOM-Baum
list.append(fragment);

console.log(list.children.length);
console.log(fragment.childNodes.length); // Fragment ist jetzt leer

4 0

Daten laden und als Tabellenzeilen darstellen

const renderUsers = async () => {
  const response = await fetch('https://jsonplaceholder.typicode.com/users');
  const users = await response.json();

  const fragment = new DocumentFragment();
  users.forEach(({ name, email }) => {
    const row = document.createElement('tr');
    const nameCell = document.createElement('td');
    const mailCell = document.createElement('td');
    nameCell.textContent = name;   // textContent schützt vor XSS
    mailCell.textContent = email;
    row.append(nameCell, mailCell);
    fragment.append(row);
  });

  document.querySelector('#users tbody').replaceChildren(fragment);
  console.log(`${users.length} Zeilen gerendert`);
};

renderUsers();

10 Zeilen gerendert

Fragment klonen, um Inhalte mehrfach einzufügen

const badge = new DocumentFragment();
const span = document.createElement('span');
span.className = 'badge';
span.textContent = 'Neu';
badge.append(span);

// Ohne Klon würde der Inhalt nur beim ersten Einfügen ankommen
document.querySelectorAll('.product').forEach((el) => {
  el.append(badge.cloneNode(true));
});

console.log(document.querySelectorAll('.badge').length);

Anzahl der .product-Elemente, z. B. 3

// Wichtig · Fallstricke

Fragment wird geleert: Beim Einfügen ins DOM wandern die Kinder aus dem Fragment heraus. Wenn du denselben Inhalt mehrmals einfügen willst, nimm fragment.cloneNode(true).
Verweise zeigen ins Leere: Eine Variable, die auf das Fragment zeigt, hat nach dem Einfügen keinen Bezug mehr zu den eingefügten Knoten. Willst du die Knoten später noch ansprechen, speichere Verweise auf die Kind-Elemente selbst.
Performance: Moderne Browser fassen DOM-Änderungen ohnehin zusammen. Der Geschwindigkeitsvorteil zeigt sich daher vor allem, wenn du zwischendurch Layout-Werte liest (z. B. offsetHeight) oder sehr viele Knoten einfügst. Eine Alternative ist element.append(...nodes) mit mehreren Argumenten.
Kein innerHTML: DocumentFragment hat keine Eigenschaft innerHTML. Um HTML-Text zu parsen, nimm ein <template>-Element (template.content ist ein Fragment) oder Range.prototype.createContextualFragment(). Beide sind bei nicht vertrauenswürdigen Eingaben anfällig für XSS, also Daten vorher bereinigen oder textContent verwenden.
Selektoren: querySelector(), querySelectorAll() und getElementById() funktionieren auch auf dem Fragment, bevor es eingefügt wird.
Kompatibilität: Der Konstruktor fehlt im Internet Explorer und in Edge-Versionen vor 17. Für sehr alte Umgebungen nimm document.createDocumentFragment(), das überall unterstützt wird.

Siehe auch

DocumentFragment Document.createDocumentFragment() HTMLTemplateElement.content Node.appendChild() Element.append() Element.replaceChildren() Node.cloneNode() Range.createContextualFragment()