Document.createElementNS() — Methode · JavaScript-Referenz

Signatur

Document.prototype.createElementNS(namespaceURI, qualifiedName, options)

Beschreibung

createElementNS() erzeugt ein Element, das einem bestimmten XML-Namensraum zugeordnet ist. Das ist vor allem dann wichtig, wenn Sie per JavaScript SVG- oder MathML-Elemente in ein HTML-Dokument einfügen wollen. Ein mit document.createElement("circle") erzeugtes Element landet im HTML-Namensraum. Es ist dann nur ein HTMLUnknownElement und wird nicht gezeichnet. Erst mit dem SVG-Namensraum http://www.w3.org/2000/svg entsteht ein echtes SVGCircleElement.

Der qualifizierte Name kann ein Präfix enthalten, z. B. "xlink:href" oder "svg:rect". Das Präfix landet in element.prefix, der Teil nach dem Doppelpunkt in element.localName. Der Browser prüft die Kombination aus Namensraum und Präfix. Wer etwa das Präfix xml mit einem falschen Namensraum verwendet, bekommt einen Fehler.

Wichtige Namensräume:

HTML: http://www.w3.org/1999/xhtml
SVG: http://www.w3.org/2000/svg
MathML: http://www.w3.org/1998/Math/MathML
XLink (für Attribute): http://www.w3.org/1999/xlink

Über den optionalen dritten Parameter lässt sich, wie bei createElement(), ein angepasstes eingebautes Element (Custom Element) mit is anlegen. Das funktioniert nur im HTML-Namensraum.

Parameter

Name	Typ	Default	Beschreibung
$namespaceURI Pflicht	string \| null		Namensraum-URI des neuen Elements, z. B. `"http://www.w3.org/2000/svg"`. Mit `null` oder `""` entsteht ein Element ohne Namensraum.
$qualifiedName Pflicht	string		Qualifizierter Name, optional mit Präfix (`"prefix:localName"`). Groß- und Kleinschreibung bleibt erhalten, `"foreignObject"` ist also nicht dasselbe wie `"foreignobject"`.
$options	{ is?: string } \| string	undefined	Optionales Objekt mit der Eigenschaft `is`: der Tag-Name eines zuvor mit `customElements.define()` registrierten angepassten eingebauten Elements.

Rückgabewert

Typ

Element

Beschreibung

Das neu erzeugte Element, z. B. SVGSVGElement, SVGCircleElement, MathMLElement oder HTMLElement. Es ist noch nicht ins Dokument eingehängt.

Beispiele

SVG-Grafik dynamisch erzeugen

const SVG_NS = "http://www.w3.org/2000/svg";

const svg = document.createElementNS(SVG_NS, "svg");
svg.setAttribute("width", "120");
svg.setAttribute("height", "120");
svg.setAttribute("viewBox", "0 0 120 120");

const circle = document.createElementNS(SVG_NS, "circle");
circle.setAttribute("cx", "60");
circle.setAttribute("cy", "60");
circle.setAttribute("r", "50");
circle.setAttribute("fill", "tomato");

svg.append(circle);
document.body.append(svg);

console.log(circle instanceof SVGCircleElement);

true

Unterschied zu createElement()

const falsch = document.createElement("circle");
const richtig = document.createElementNS("http://www.w3.org/2000/svg", "circle");

console.log(falsch.namespaceURI);
console.log(falsch.constructor.name);
console.log(richtig.namespaceURI);
console.log(richtig.constructor.name);

http://www.w3.org/1999/xhtml HTMLUnknownElement http://www.w3.org/2000/svg SVGCircleElement

Balkendiagramm aus Daten erzeugen

const SVG_NS = "http://www.w3.org/2000/svg";
const daten = [40, 75, 20, 90];

const svg = document.createElementNS(SVG_NS, "svg");
svg.setAttribute("viewBox", `0 0 ${daten.length * 30} 100`);

daten.forEach((wert, i) => {
  const rect = document.createElementNS(SVG_NS, "rect");
  rect.setAttribute("x", String(i * 30 + 5));
  rect.setAttribute("y", String(100 - wert));
  rect.setAttribute("width", "20");
  rect.setAttribute("height", String(wert));
  const title = document.createElementNS(SVG_NS, "title");
  title.textContent = `Wert: ${wert}`;
  rect.append(title);
  svg.append(rect);
});

document.querySelector("#chart")?.append(svg);
console.log(svg.querySelectorAll("rect").length);

4

Präfix und localName in einem XML-Dokument

const doc = document.implementation.createDocument("urn:example:shop", "shop:katalog", null);
const artikel = doc.createElementNS("urn:example:shop", "shop:artikel");
artikel.textContent = "Tastatur";
doc.documentElement.append(artikel);

console.log(artikel.prefix, artikel.localName);
console.log(new XMLSerializer().serializeToString(doc));

shop artikel <shop:katalog xmlns:shop="urn:example:shop"><shop:artikel>Tastatur</shop:artikel></shop:katalog>

// Wichtig · Fallstricke

Häufigster Fehler: SVG-Elemente mit createElement() anlegen. Sie tauchen dann im DOM auf, werden aber nicht gezeichnet. Für SVG und MathML ist immer createElementNS() nötig.
Die Namensraum-URI muss exakt stimmen. Schon ein zusätzlicher Schrägstrich am Ende oder https statt http ergibt einen anderen Namensraum.
Attribute auf SVG-Elementen setzen Sie meist mit setAttribute() ohne Namensraum. Nur Attribute mit Namensraum brauchen setAttributeNS(), etwa das veraltete xlink:href ("http://www.w3.org/1999/xlink"). Modernes SVG 2 akzeptiert schlicht href.
Ein ungültiger qualifizierter Name (z. B. "1abc" oder "a:b:c") löst einen InvalidCharacterError aus. Eine unzulässige Kombination aus Präfix und Namensraum (z. B. ein Präfix mit null als Namensraum oder xmlns ohne den XMLNS-Namensraum) löst einen NamespaceError aus.
Groß- und Kleinschreibung wird nicht angepasst: "linearGradient" muss in genau dieser Schreibweise übergeben werden.
Bei Tausenden Elementen lohnt sich ein DocumentFragment oder das Einhängen in das noch nicht angezeigte <svg>, damit das Layout nicht ständig neu berechnet wird.
Die Methode wird in allen Browsern unterstützt. Das options-Argument mit is gibt es in Safari nicht, weil Safari keine angepassten eingebauten Elemente (customized built-ins) unterstützt.

Siehe auch

Document.createElement() Element.setAttributeNS() Element.setAttribute() Document.createAttributeNS() Element.namespaceURI DOMImplementation.createDocument() SVGElement