Document.append() — Methode · JavaScript-Referenz

Signatur

Document.prototype.append(...nodes)

Beschreibung

Document.append() stammt aus dem Mixin ParentNode und hängt beliebig viele Node-Objekte oder Zeichenketten in der angegebenen Reihenfolge ans Ende der Kindliste des Dokuments an. Zeichenketten werden intern in Text-Knoten umgewandelt.

Anders als bei Element.append() gelten auf Dokumentebene strenge Regeln für die Struktur: Ein Document darf höchstens ein Element (das documentElement) und höchstens einen DocumentType enthalten. Der Doctype muss vor dem Element stehen. Text-Knoten sind als direkte Kinder gar nicht erlaubt. Erlaubt sind außerdem Comment- und ProcessingInstruction-Knoten.

Deshalb nutzt man die Methode vor allem bei Dokumenten, die man selbst erzeugt, etwa mit new Document() oder document.implementation.createDocument(). Dort hängt man Wurzelelement, Doctype, Kommentare oder Verarbeitungsanweisungen in einem Aufruf an. Beim normalen HTML-Dokument im Browser gibt es schon ein <html>-Element, sodass ein weiteres Element einen Fehler auslöst.

Werden mehrere Knoten übergeben, fasst der Browser sie intern zu einem DocumentFragment zusammen und fügt sie in einem Schritt ein. Scheitert die Prüfung der Struktur, wird kein Knoten eingefügt.

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 und sind auf Dokumentebene nicht erlaubt (Folge: `HierarchyRequestError`).

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Anders als Node.appendChild() wird der eingefügte Knoten nicht zurückgegeben.

Beispiele

Wurzelelement in ein neues XML-Dokument einfügen

const doc = new Document();
const root = doc.createElement('library');
root.append(doc.createElement('book'));

doc.append(root);

console.log(doc.documentElement.nodeName);
console.log(new XMLSerializer().serializeToString(doc));

library <library><book/></library>

Mehrere Knoten in einem Aufruf: Verarbeitungsanweisung, Kommentar, Wurzel

const doc = document.implementation.createDocument(null, '');

const pi = doc.createProcessingInstruction(
  'xml-stylesheet',
  'href="style.xsl" type="text/xsl"'
);
const comment = doc.createComment(' Export vom 2024-05-01 ');
const root = doc.createElement('export');

doc.append(pi, comment, root);

console.log(doc.childNodes.length);
console.log(new XMLSerializer().serializeToString(doc));

3 <?xml-stylesheet href="style.xsl" type="text/xsl"?><export/>

HTML-Dokument mit Doctype von Grund auf aufbauen

const doc = document.implementation.createHTMLDocument('');
// Vorhandene Kinder (Doctype + <html>) entfernen
doc.replaceChildren();

const doctype = doc.implementation.createDocumentType('html', '', '');
const html = doc.createElement('html');
html.append(doc.createElement('head'), doc.createElement('body'));

// Reihenfolge wichtig: Doctype vor dem Element
doc.append(doctype, html);

console.log(doc.doctype.name, doc.documentElement.children.length);

html 2

Typische Fehler abfangen

const tryAppend = (label, ...nodes) => {
  try {
    document.append(...nodes);
  } catch (err) {
    console.log(`${label}: ${err.name}`);
  }
};

// Das aktuelle Dokument hat bereits ein <html>-Element
tryAppend('Zweites Element', document.createElement('div'));
// Text ist als Dokument-Kind nicht erlaubt
tryAppend('Zeichenkette', 'Hallo');

Zweites Element: HierarchyRequestError Zeichenkette: HierarchyRequestError

// Wichtig · Fallstricke

HierarchyRequestError: Diesen Fehler gibt es, wenn schon ein documentElement vorhanden ist und ein weiteres Element angehängt werden soll. Ebenso bei Zeichenketten bzw. Text-Knoten, bei einem zweiten Doctype oder wenn der Doctype hinter dem Element landen würde. Die Prüfung gilt für alle Argumente zusammen: Schlägt sie fehl, wird nichts eingefügt.
Für Inhalte im sichtbaren Bereich ist fast immer document.body.append() gemeint und nicht document.append().
Ein Knoten, der schon woanders im Baum hängt, wird verschoben und nicht kopiert. Knoten aus einem anderen Dokument werden automatisch übernommen (adoptiert). Bei Bedarf vorher mit cloneNode(true) kopieren.
Zeichenketten werden immer als reiner Text behandelt und nie als HTML ausgewertet. Die Methode birgt also kein XSS-Risiko wie innerHTML, auf Dokumentebene sind Zeichenketten aber ohnehin verboten.
Browser-Kompatibilität: wird von allen modernen Browsern unterstützt, nicht vom Internet Explorer. Als Ersatz dient dort appendChild() (nur ein Knoten pro Aufruf).

Siehe auch

Document.prepend() Document.replaceChildren() Element.append() Node.appendChild() DOMImplementation.createDocument() Document.documentElement DocumentFragment