DOMImplementation.createDocumentType() — Methode · JavaScript-Referenz

Signatur

DOMImplementation.prototype.createDocumentType(qualifiedName, publicId, systemId)

Beschreibung

createDocumentType() wird über document.implementation aufgerufen und liefert einen neuen, noch nicht eingefügten DocumentType-Knoten. Er steht für die Doctype-Deklaration am Anfang eines Dokuments, etwa <!DOCTYPE html> oder eine XHTML- bzw. SVG-DTD mit öffentlichem und System-Bezeichner.

Typischerweise übergibt man das Ergebnis als dritten Parameter an DOMImplementation.createDocument(). So entsteht ein XML-Dokument, das seinen Doctype von Anfang an hat. Alternativ lässt sich der Knoten mit Node.insertBefore() oder ParentNode.prepend() in ein bestehendes Dokument einfügen, das noch keinen Doctype hat. Die Methode replaceChild() ersetzt einen vorhandenen Doctype.

Gebraucht wird die Methode vor allem beim Erzeugen von XML oder XHTML im Programm, beim Serialisieren mit XMLSerializer (dort taucht die Doctype-Zeile in der Ausgabe auf) und in Testumgebungen. Für normale HTML-Dokumente ist createHTMLDocument() meist bequemer, denn sie legt den HTML5-Doctype selbst an.

Parameter

Name	Typ	Beschreibung
$qualifiedName Pflicht	string	Qualifizierter Name des Doctypes, z. B. `"html"` oder `"svg:svg"`. Er muss ein gültiger XML-Name sein, sonst wird eine Ausnahme geworfen.
$publicId Pflicht	string	Öffentlicher Bezeichner (PUBLIC), z. B. `"-//W3C//DTD XHTML 1.0 Strict//EN"`. Ohne Bezeichner einen Leerstring übergeben.
$systemId Pflicht	string	System-Bezeichner, meist die URL der DTD, z. B. `"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"`. Ohne Bezeichner einen Leerstring übergeben.

Rückgabewert

Typ

DocumentType

Beschreibung

Ein neuer DocumentType-Knoten mit den Eigenschaften name, publicId und systemId. Sein ownerDocument ist das Dokument der verwendeten DOMImplementation, einen Elternknoten hat er noch nicht.

Beispiele

XHTML-Dokument mit Doctype erzeugen und serialisieren

const doctype = document.implementation.createDocumentType(
  'html',
  '-//W3C//DTD XHTML 1.0 Strict//EN',
  'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'
);

const xhtmlDoc = document.implementation.createDocument(
  'http://www.w3.org/1999/xhtml',
  'html',
  doctype
);

console.log(xhtmlDoc.doctype.publicId);
console.log(new XMLSerializer().serializeToString(xhtmlDoc));

-//W3C//DTD XHTML 1.0 Strict//EN <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"/>

HTML5-Doctype ohne Bezeichner

const dt = document.implementation.createDocumentType('html', '', '');
console.log(dt.nodeType === Node.DOCUMENT_TYPE_NODE, dt.name);
console.log(new XMLSerializer().serializeToString(dt));

true html <!DOCTYPE html>

Fehlenden Doctype in ein XML-Dokument nachträglich einfügen

const xml = new DOMParser().parseFromString(
  '<svg xmlns="http://www.w3.org/2000/svg"/>',
  'image/svg+xml'
);
console.log(xml.doctype); // null

const svgDoctype = xml.implementation.createDocumentType(
  'svg',
  '-//W3C//DTD SVG 1.1//EN',
  'http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd'
);
// Doctype muss vor dem Wurzelelement stehen
xml.insertBefore(svgDoctype, xml.documentElement);
console.log(xml.doctype.name);

null svg

Ungültigen Namen abfangen

try {
  document.implementation.createDocumentType('1ungültig', '', '');
} catch (err) {
  console.log(err.name);
}

InvalidCharacterError

// Wichtig · Fallstricke

Alle drei Parameter sind Pflicht. Leere Bezeichner übergibt man als ''. Wer Argumente weglässt, bekommt je nach Browser einen TypeError oder "undefined" als Zeichenkette.
Ein ungültiger qualifiedName löst einen DOMException vom Typ InvalidCharacterError aus, ein fehlerhaft aufgebauter qualifizierter Name (z. B. "a:b:c") je nach Implementierung NamespaceError.
Ein Dokument darf höchstens einen Doctype haben, und dieser muss vor dem Wurzelelement stehen. Sonst wirft insertBefore()/appendChild() einen HierarchyRequestError.
Ein nachträglich eingefügter Doctype ändert den Darstellungsmodus (Quirks- oder Standardmodus) eines bereits geladenen Dokuments nicht. Der Modus wird nur beim Parsen festgelegt.
Interne DTD-Teilmengen und Entitätsdeklarationen lassen sich nicht anlegen. Die alten Eigenschaften entities, notations und internalSubset wurden aus dem DOM-Standard entfernt.
Unterstützt wird die Methode in allen aktuellen Browsern. In Node.js gibt es sie nur über DOM-Implementierungen wie jsdom.

Siehe auch

DOMImplementation DOMImplementation.createDocument() DOMImplementation.createHTMLDocument() DocumentType Document.doctype Node.insertBefore() XMLSerializer