DocumentFragment — Schnittstelle · JavaScript-Referenz

Signatur

interface DocumentFragment extends Node

Beschreibung

DocumentFragment ist ein minimales Dokumentobjekt ohne Elternknoten. Es gehört nicht zum aktiven DOM-Baum. Deshalb lösen Änderungen daran weder Reflow noch Repaint aus. Damit eignet es sich gut, um viele Knoten erst außerhalb des sichtbaren Dokuments aufzubauen und dann in einem einzigen Schritt einzufügen.

Wenn ein Fragment mit appendChild(), append(), insertBefore() oder replaceChildren() eingefügt wird, landet nicht das Fragment selbst im DOM, sondern nur seine Kindknoten. Das Fragment ist danach leer und kann erneut verwendet werden.

Ein Fragment erzeugen Sie mit new DocumentFragment() oder document.createDocumentFragment(). Außerdem begegnet es Ihnen an diesen Stellen:

HTMLTemplateElement.content – der Inhalt eines <template>-Elements
Range.prototype.extractContents() und cloneContents()
Range.prototype.createContextualFragment()
ShadowRoot, das von DocumentFragment erbt

Neben den geerbten Node-Mitgliedern bietet es die ParentNode-API: children, firstElementChild, lastElementChild, childElementCount, append(), prepend(), replaceChildren(), querySelector(), querySelectorAll() und getElementById().

Parameter

Name	Typ	Default	Beschreibung
$(Konstruktor) new DocumentFragment()	—		Der Konstruktor nimmt keine Argumente an. Er erzeugt ein leeres Fragment, dessen `ownerDocument` das aktuelle `document` ist.

Rückgabewert

Typ

DocumentFragment

Beschreibung

Ein leeres DocumentFragment mit nodeType === 11 (Node.DOCUMENT_FRAGMENT_NODE) und nodeName === "#document-fragment".

Beispiele

Liste performant in einem Schritt aufbauen

const produkte = ['Apfel', 'Birne', 'Kirsche'];
const liste = document.querySelector('#produktliste');

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

console.log(fragment.childNodes.length);
liste.append(fragment); // nur ein DOM-Einfügevorgang
console.log(fragment.childNodes.length); // Fragment ist jetzt leer

3 0

Template-Inhalt klonen und befüllen

// HTML: <template id="karte"><article><h2></h2><p></p></article></template>
const tpl = document.querySelector('#karte');

const renderKarte = ({ titel, text }) => {
  const frag = tpl.content.cloneNode(true); // DocumentFragment
  frag.querySelector('h2').textContent = titel;
  frag.querySelector('p').textContent = text;
  return frag;
};

document.body.append(
  renderKarte({ titel: 'Hallo', text: 'Erste Karte' }),
  renderKarte({ titel: 'Welt', text: 'Zweite Karte' })
);
console.log(tpl.content instanceof DocumentFragment);

true

Fragment aus HTML-String über Range erzeugen

const range = document.createRange();
range.selectNode(document.body);

// Achtung: nur vertrauenswürdiges HTML verwenden!
const frag = range.createContextualFragment('<p class="hinweis">Gespeichert</p><p>OK</p>');
console.log(frag.childElementCount, frag.firstElementChild.className);

document.querySelector('#status').replaceChildren(frag);

2 hinweis

Fragment-Knoten erkennen

const frag = document.createDocumentFragment();
console.log(frag.nodeType === Node.DOCUMENT_FRAGMENT_NODE);
console.log(frag.nodeName, frag.parentNode);

true #document-fragment null

// Wichtig · Fallstricke

Das Fragment wird beim Einfügen geleert: Nach append(fragment) ist es leer. Eine Referenz darauf bringt also nichts, wenn Sie den Inhalt noch einmal einfügen wollen. Verwenden Sie dafür vorher fragment.cloneNode(true).
Kein innerHTML: DocumentFragment hat keine innerHTML-Eigenschaft. HTML-Strings parsen Sie mit einem <template> oder mit Range.createContextualFragment().
Sicherheit (XSS): createContextualFragment() führt enthaltene <script>-Elemente beim Einfügen aus. Das unterscheidet es von innerHTML. Nicht vertrauenswürdige Eingaben müssen Sie vorher bereinigen (z. B. mit DOMPurify oder der Sanitizer-API). Eine strenge CSP und Trusted Types schützen zusätzlich.
Performance: Moderne Engines fassen DOM-Änderungen ohnehin gebündelt zusammen. Den größten Vorteil bringt ein Fragment bei vielen Einzelknoten. element.append(...nodes) leistet oft Ähnliches.
Stile und Ereignisse: Knoten in einem Fragment werden nicht gerendert. getBoundingClientRect() oder berechnete Stile liefern dort also keine sinnvollen Werte. Ereignis-Listener an den Kindknoten bleiben beim Einfügen erhalten.
Kompatibilität: document.createDocumentFragment() funktioniert in allen Browsern. Der Konstruktor new DocumentFragment() fehlt in sehr alten Browsern wie dem Internet Explorer.

Siehe auch

Node Element.append() DocumentTimeline DocumentType Document