Document.createAttributeNS() — Methode · JavaScript-Referenz

Signatur

Document.prototype.createAttributeNS(namespaceURI, qualifiedName)

Beschreibung

document.createAttributeNS() erzeugt einen eigenständigen Attr-Knoten, der zu einem bestimmten XML-Namespace gehört. Der Knoten hängt zunächst an keinem Element. Erst mit Element.setAttributeNodeNS() wird er einem Element hinzugefügt. Der Wert wird über die Eigenschaft value gesetzt.

Nützlich ist die Methode vor allem bei Dokumenten mit Namespaces, also bei SVG, MathML, XLink oder eigenen XML-Formaten. Anders als createAttribute() werden hier namespaceURI, prefix und localName des Attributs korrekt gesetzt. Das ist wichtig, wenn das Dokument später serialisiert oder mit Namespace-bewussten Methoden wie getAttributeNS() ausgewertet wird.

In der Praxis führt Element.setAttributeNS() meist schneller zum Ziel, weil es Knoten und Wert in einem Schritt setzt. createAttributeNS() lohnt sich, wenn man den Attributknoten vorbereiten, zwischen Elementen verschieben oder als Objekt weiterreichen möchte.

Parameter

Name	Typ	Default	Beschreibung
$namespaceURI Pflicht	string \| null		Namespace-URI des Attributs, z. B. `"http://www.w3.org/1999/xlink"`. Mit `null` oder `""` gehört das Attribut zu keinem Namespace.
$qualifiedName Pflicht	string		Qualifizierter Name, optional mit Präfix, z. B. `"xlink:href"` oder `"data-id"`. Groß- und Kleinschreibung bleibt erhalten.

Rückgabewert

Typ

Attr

Beschreibung

Ein neuer Attr-Knoten mit gesetztem namespaceURI, prefix und localName. Sein value ist ein leerer String, und ownerElement ist null.

Beispiele

XLink-Attribut für ein SVG-Element erzeugen

const SVG_NS = 'http://www.w3.org/2000/svg';
const XLINK_NS = 'http://www.w3.org/1999/xlink';

const use = document.createElementNS(SVG_NS, 'use');
const href = document.createAttributeNS(XLINK_NS, 'xlink:href');
href.value = '#icon-star';

use.setAttributeNodeNS(href);

console.log(href.prefix, href.localName, href.namespaceURI);
console.log(use.getAttributeNS(XLINK_NS, 'href'));

xlink href http://www.w3.org/1999/xlink #icon-star

Eigenes Namespace-Attribut in einem XML-Dokument

const NS = 'https://example.com/ns/app';
const xmlDoc = document.implementation.createDocument(null, 'config', null);

const attr = xmlDoc.createAttributeNS(NS, 'app:version');
attr.value = '2.1';
xmlDoc.documentElement.setAttributeNodeNS(attr);

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

Attributknoten ohne Namespace und Fehlerbehandlung

const div = document.createElement('div');
const attr = document.createAttributeNS(null, 'data-state');
attr.value = 'aktiv';
div.setAttributeNodeNS(attr);
console.log(div.outerHTML);

try {
  // Präfix ohne Namespace ist unzulässig
  document.createAttributeNS(null, 'foo:bar');
} catch (err) {
  console.log(err.name);
}

<div data-state="aktiv"></div> NamespaceError

// Wichtig · Fallstricke

Ausnahmen: Ist qualifiedName kein gültiger XML-Name, wirft die Methode einen InvalidCharacterError. Einen NamespaceError gibt es, wenn ein Präfix ohne Namespace angegeben wird, wenn xml nicht mit http://www.w3.org/XML/1998/namespace verwendet wird oder wenn xmlns bzw. das Präfix xmlns: nicht mit http://www.w3.org/2000/xmlns/ verwendet wird (und umgekehrt).
Der Attributknoten muss mit setAttributeNodeNS() hinzugefügt werden. Hängt er schon an einem anderen Element, wirft die Methode einen InUseAttributeError.
Für normale HTML-Attribute reicht setAttribute(). Wer setAttributeNS() nutzt, braucht keinen separaten Attr-Knoten.
Moderne Browser unterstützen in SVG 2 auch ein einfaches href ohne XLink-Namespace. xlink:href braucht man meist nur noch für ältere Umgebungen.
Die Methode wird von allen modernen Browsern unterstützt. In Node.js steht sie nur über DOM-Implementierungen wie jsdom zur Verfügung.

Siehe auch

Document.createAttribute() Document.createElementNS() Element.setAttributeNodeNS() Element.setAttributeNS() Element.getAttributeNS() Attr ProcessingInstruction.removeAttribute()