DocumentFragment.prepend() — Methode · JavaScript-Referenz

Signatur

DocumentFragment.prototype.prepend(...nodes)

Beschreibung

DocumentFragment.prepend() fügt einen oder mehrere Knoten bzw. Zeichenfolgen am Anfang eines Dokumentfragments ein, also vor dessen bisherigem ersten Kind. Zeichenfolgen werden automatisch in Text-Knoten umgewandelt und nicht als HTML interpretiert. Die übergebenen Argumente bleiben in ihrer Reihenfolge erhalten.

Die Methode stammt aus dem Mixin ParentNode und steht daher genauso auf Element und Document zur Verfügung. Im Vergleich zu insertBefore(node, fragment.firstChild) ist sie kürzer, nimmt mehrere Argumente gleichzeitig entgegen und akzeptiert auch reine Zeichenfolgen.

Nützlich ist prepend() vor allem dann, wenn du eine DOM-Struktur zunächst unsichtbar in einem Fragment aufbaust – etwa eine Liste, der nachträglich ein Kopfeintrag oder eine Überschrift vorangestellt werden soll – und sie anschließend mit einem einzigen Einfügevorgang ins Dokument hängst. So vermeidest du unnötige Reflows.

Wird ein Knoten übergeben, der bereits an anderer Stelle im DOM hängt, wird er dorthin verschoben, nicht kopiert.

Parameter

Name	Typ	Default	Beschreibung
$...nodes	Node \| string		Beliebig viele Knoten oder Zeichenfolgen, die vor dem ersten Kind eingefügt werden. Zeichenfolgen werden zu `Text`-Knoten. Ohne Argument passiert nichts.

Rückgabewert

Typ

void

Beschreibung

Gibt undefined zurück; ein Verketten von Aufrufen ist daher nicht möglich.

Beispiele

Element und Text an den Anfang stellen

const fragment = new DocumentFragment();
const item = document.createElement('li');
item.textContent = 'Zweiter Eintrag';
fragment.append(item);

const first = document.createElement('li');
first.textContent = 'Erster Eintrag';
fragment.prepend(first);

console.log(fragment.children.length);
console.log(fragment.firstElementChild.textContent);

2 Erster Eintrag

Mehrere Argumente in einem Aufruf

const fragment = document.createDocumentFragment();
fragment.append(document.createElement('p'));

const heading = document.createElement('h2');
heading.textContent = 'Übersicht';

// Reihenfolge der Argumente bleibt erhalten
fragment.prepend(heading, 'Stand: heute ');

console.log([...fragment.childNodes].map((n) => n.nodeName));

["H2", "#text", "P"]

Liste im Fragment aufbauen und mit Kopfzeile einfügen

const users = ['Anna', 'Ben', 'Clara'];
const fragment = new DocumentFragment();

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

const header = document.createElement('li');
header.className = 'list-header';
header.textContent = `Benutzer (${users.length})`;
fragment.prepend(header);

// Ein einziger DOM-Eingriff
const ul = document.createElement('ul');
ul.append(fragment);
document.body.append(ul);

console.log(fragment.childNodes.length); // Fragment ist danach leer

Zeichenfolgen werden nicht als HTML interpretiert

const fragment = new DocumentFragment();
fragment.prepend('<b>fett?</b>');

console.log(fragment.firstChild.nodeType === Node.TEXT_NODE);
console.log(fragment.textContent);

true <b>fett?</b>

// Wichtig · Fallstricke

Kein HTML-Parsing: Zeichenfolgen werden als Text eingefügt. Das ist sicher gegenüber XSS, für echtes Markup brauchst du aber <template> oder createContextualFragment() (dann Eingaben unbedingt bereinigen).
Verschieben statt Kopieren: Ein bereits eingehängter Knoten wird an seiner alten Stelle entfernt. Für Kopien vorher node.cloneNode(true) verwenden.
Fragment wird geleert: Beim Einfügen des Fragments ins DOM wandern alle Kinder hinüber, das Fragment ist danach leer.
Fehler: Es wird ein HierarchyRequestError (DOMException) geworfen, wenn ein Knoten nicht eingefügt werden darf, z. B. ein Vorfahre des Fragments oder ein Document.
Rückgabewert: undefined – Verkettung wie fragment.prepend(a).prepend(b) funktioniert nicht.
Kompatibilität: Unterstützt von allen modernen Browsern (Chrome 54+, Firefox 49+, Safari 10+, Edge 17+). Internet Explorer kennt die Methode nicht; dort insertBefore() nutzen.

Siehe auch

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