Document.prepend() — Methode · JavaScript-Referenz

Signatur

Document.prototype.prepend(...nodes)

Beschreibung

Document.prepend() fügt die übergebenen Knoten direkt vor dem ersten Kind des Document-Knotens ein, also noch vor <!DOCTYPE> oder dem Wurzelelement. Die Methode stammt aus dem Mixin ParentNode und verhält sich genauso wie Element.prepend(). Mehrere Argumente werden in der angegebenen Reihenfolge eingefügt, Zeichenfolgen werden automatisch in Text-Knoten umgewandelt.

Auf der Ebene des Dokuments gelten aber strenge Regeln für die Struktur: Ein Document darf höchstens ein Element-Kind (das documentElement) und höchstens einen DocumentType haben, und Textknoten sind gar nicht erlaubt. In einem normal geladenen HTML-Dokument kann man deshalb praktisch nur Kommentare (Comment) und Verarbeitungsanweisungen (ProcessingInstruction) voranstellen.

Richtig nützlich ist die Methode vor allem bei Dokumenten, die man selbst erzeugt, etwa mit document.implementation.createDocument(). Dort kann man das Wurzelelement, Verarbeitungsanweisungen wie xml-stylesheet oder Kommentare für die Serialisierung mit XMLSerializer einfügen. Bei gewöhnlichen DOM-Änderungen ruft man prepend() dagegen meist auf document.body oder einem anderen Element auf.

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 und lösen am `Document` immer einen `HierarchyRequestError` aus. Übergibt man keine Argumente, passiert nichts.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Build-Kommentar an den Anfang des Dokuments setzen

// Kommentare sind als direkte Kinder des Dokuments erlaubt
const info = document.createComment(` Build: ${new Date().toISOString().slice(0, 10)} `);
document.prepend(info);

console.log(document.firstChild.nodeType === Node.COMMENT_NODE);

true

XML-Dokument aufbauen und Stylesheet-Anweisung voranstellen

const xmlDoc = document.implementation.createDocument(null, null);

const root = xmlDoc.createElement('config');
root.setAttribute('version', '2');
xmlDoc.prepend(root);

// Verarbeitungsanweisung vor das Wurzelelement setzen
const pi = xmlDoc.createProcessingInstruction(
  'xml-stylesheet',
  'href="style.xsl" type="text/xsl"'
);
xmlDoc.prepend(pi);

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

<?xml-stylesheet href="style.xsl" type="text/xsl"?><config version="2"/>

Typischer Fehler: zweites Element oder Text einfügen

const tryPrepend = (...nodes) => {
  try {
    document.prepend(...nodes);
    console.log('OK');
  } catch (err) {
    console.log(err.name);
  }
};

// <html> existiert bereits, ein zweites Element ist nicht erlaubt
tryPrepend(document.createElement('div'));
// Textknoten sind direkt im Document verboten
tryPrepend('Hallo');

HierarchyRequestError HierarchyRequestError

// Wichtig · Fallstricke

HierarchyRequestError: Dieser Fehler wird geworfen, wenn durch das Einfügen ein zweites Element-Kind, ein zweiter Doctype oder ein Textknoten (auch aus einer Zeichenfolge) entstehen würde. Er tritt auch auf, wenn ein Doctype hinter das Wurzelelement geraten würde.
Kommentare vor dem <!DOCTYPE> sind im DOM erlaubt. Der Rendering-Modus (Quirks/Standards) wird aber schon beim Parsen festgelegt und ändert sich dadurch nicht.
Ist ein Knoten schon an anderer Stelle im Baum eingehängt, wird er verschoben und nicht kopiert. Für eine Kopie vorher cloneNode(true) verwenden.
Wer Inhalte am Seitenanfang einfügen will, meint fast immer document.body.prepend().
Browser-Unterstützung: in allen modernen Browsern vorhanden, im Internet Explorer nicht. Dort als Ersatz document.insertBefore(node, document.firstChild) verwenden.

Siehe auch

Document.append() Document.replaceChildren() Element.prepend() Node.insertBefore() Document.createComment() DOMImplementation.createDocument() new PageSwapEvent()