DocumentType.before() — Methode · JavaScript-Referenz

Signatur

DocumentType.prototype.before(...nodes)

Beschreibung

before() stammt aus dem ChildNode-Mixin und steht deshalb auch an DocumentType-Knoten zur Verfügung, also an der Doctype-Deklaration (<!DOCTYPE html>), die du über document.doctype erreichst. Die Methode fügt alle übergebenen Argumente der Reihe nach direkt vor dem Doctype in dessen Elternknoten ein. Das ist praktisch immer das Document selbst.

Zeichenfolgen werden intern in Text-Knoten umgewandelt. Genau hier liegt der wichtigste Unterschied zu Element.before(): Ein Document darf laut DOM-Standard keine Textknoten und kein Element vor dem Doctype als Kind haben. Solche Einfügungen brechen mit einer HierarchyRequestError-DOMException ab. Vor dem Doctype sind nur Comment- und ProcessingInstruction-Knoten erlaubt.

In der Praxis brauchst du die Methode daher vor allem, um Kommentare (z. B. Build- oder Lizenzhinweise) oder Verarbeitungsanweisungen (z. B. <?xml-stylesheet?> in XML-Dokumenten) an den Anfang eines Dokuments zu setzen, bevor du es serialisierst. Die Methode erzeugt dabei keine unnötigen Zwischenschritte wie parentNode.insertBefore(), und du kannst mehrere Knoten in einem einzigen Aufruf einfügen.

Parameter

Name	Typ	Default	Beschreibung
$...nodes	Node \| string		Beliebig viele Knoten oder Zeichenfolgen, die in der angegebenen Reihenfolge vor dem Doctype eingefügt werden. Zeichenfolgen werden zu `Text`-Knoten. Vor einem Doctype sind aber nur `Comment` und `ProcessingInstruction` gültig. Knoten, die schon im DOM hängen, werden verschoben und nicht kopiert.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Build-Kommentar vor den Doctype setzen

const doctype = document.doctype;

if (doctype) {
  const hinweis = document.createComment(` Build: ${new Date().toISOString().slice(0, 10)} `);
  doctype.before(hinweis);
}

// Erster Kindknoten des Dokuments ist jetzt der Kommentar
console.log(document.firstChild.nodeType === Node.COMMENT_NODE);
console.log(document.firstChild.nextSibling === document.doctype);

true true

Zeichenfolgen und Elemente lösen einen Fehler aus

const doctype = document.doctype;

try {
  doctype.before('Freier Text');
} catch (err) {
  console.log(err.name); // Text-Kinder sind am Document verboten
}

try {
  doctype.before(document.createElement('div'));
} catch (err) {
  console.log(err.name); // Elemente dürfen nicht vor dem Doctype stehen
}

HierarchyRequestError HierarchyRequestError

XSLT-Verarbeitungsanweisung in ein XML-Dokument einfügen

const xmlDoc = new DOMParser().parseFromString(
  '<!DOCTYPE katalog><katalog><buch>JS</buch></katalog>',
  'application/xml'
);

const pi = xmlDoc.createProcessingInstruction(
  'xml-stylesheet',
  'href="katalog.xsl" type="text/xsl"'
);
const kommentar = xmlDoc.createComment(' automatisch erzeugt ');

// Mehrere Knoten in einem Aufruf, Reihenfolge bleibt erhalten
xmlDoc.doctype.before(pi, kommentar);

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

<?xml-stylesheet href="katalog.xsl" type="text/xsl"?><!DOCTYPE katalog><katalog><buch>JS</buch></katalog>

// Wichtig · Fallstricke

HierarchyRequestError: Das Document darf keine Textknoten als Kinder haben. Zeichenfolgen als Argument führen darum fast immer zu einem Fehler, auch reine Leerzeichen. Dasselbe gilt für Elemente, DocumentFragments mit Elementen oder Text und einen zweiten Doctype.
Kein Elternknoten: Hat der Doctype keinen parentNode (z. B. ein frischer Knoten aus document.implementation.createDocumentType()), passiert nichts und es wird kein Fehler ausgelöst.
Kein Einfluss auf den Rendermodus: Kommentare, die du nachträglich vor den Doctype einfügst, schalten ein bereits geladenes HTML-Dokument nicht in den Quirks-Modus. Nur alte Internet-Explorer-Versionen reagierten beim Parsen empfindlich auf Kommentare vor dem Doctype.
document.doctype kann null sein, wenn das Dokument keinen Doctype hat. Prüfe den Wert deshalb vor dem Aufruf.
Kompatibilität: In allen modernen Browsern verfügbar, im Internet Explorer nicht. Dort musst du auf document.insertBefore(node, document.doctype) ausweichen.

Siehe auch

Element.before() Document.doctype DocumentType.remove() DocumentType.after() DocumentType.replaceWith()