Element.setAttributeNodeNS() — Methode · JavaScript-Referenz

Signatur

Element.prototype.setAttributeNodeNS(attributeNode)

Beschreibung

setAttributeNodeNS() hängt einen zuvor erzeugten Attr-Knoten an ein Element an. Ob schon ein Attribut vorhanden ist, prüft die Methode anhand der Kombination aus Namensraum-URI (namespaceURI) und lokalem Namen (localName), nicht anhand des qualifizierten Namens mit Präfix. Gibt es bereits ein passendes Attribut, wird es ersetzt und als Rückgabewert geliefert.

Die Methode ist vor allem bei XML-basierten Dokumenten wichtig, etwa bei SVG mit xlink:href, MathML oder eigenen XML-Formaten, die mit DOMParser oder XMLHttpRequest geladen werden. Den passenden Knoten erzeugt man meist mit document.createAttributeNS(namespaceURI, qualifiedName).

Im normalen HTML-Alltag braucht man die Methode fast nie. setAttributeNS() erledigt dasselbe direkt mit Zeichenketten und ist kürzer und besser lesbar. Sinnvoll ist setAttributeNodeNS() vor allem dann, wenn man mit Attr-Objekten arbeitet, z. B. wenn man Attribute von einem Element auf ein anderes verschieben oder klonen will.

Technisch verhalten sich setAttributeNode() und setAttributeNodeNS() laut aktuellem DOM-Standard gleich: Beide suchen nach Namensraum und lokalem Namen. Der Name mit NS macht nur deutlicher, was gemeint ist.

Parameter

Name	Typ	Default	Beschreibung
$attributeNode Pflicht	Attr		Der hinzuzufügende Attributknoten, meist erzeugt mit `document.createAttributeNS()`. Er darf zu keinem anderen Element gehören.

Rückgabewert

Typ

Attr | null

Beschreibung

Den ersetzten Attr-Knoten, wenn schon ein Attribut mit gleichem Namensraum und lokalem Namen vorhanden war, sonst null. Wird genau derselbe Knoten erneut gesetzt, gibt die Methode diesen Knoten selbst zurück.

Beispiele

SVG-Element mit xlink:href versehen

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-stern';

const replaced = use.setAttributeNodeNS(href);
console.log(replaced);
console.log(use.getAttributeNS(XLINK_NS, 'href'));

null #icon-stern

Vorhandenes Attribut ersetzen – der alte Knoten wird zurückgegeben

const NS = 'urn:example:meta';
const doc = new DOMParser().parseFromString(
  '<buch xmlns:m="urn:example:meta" m:status="entwurf"/>',
  'application/xml'
);
const buch = doc.documentElement;

// Anderes Präfix, aber gleicher Namensraum + localName → wird ersetzt
const neu = doc.createAttributeNS(NS, 'meta:status');
neu.value = 'veröffentlicht';

const alt = buch.setAttributeNodeNS(neu);
console.log(alt.value);
console.log(buch.getAttributeNS(NS, 'status'));
console.log(new XMLSerializer().serializeToString(buch));

entwurf veröffentlicht <buch xmlns:m="urn:example:meta" xmlns:meta="urn:example:meta" meta:status="veröffentlicht"/>

Attribut von einem Element auf ein anderes verschieben

const XLINK_NS = 'http://www.w3.org/1999/xlink';
const [quelle, ziel] = document.querySelectorAll('svg use');

const attr = quelle.getAttributeNodeNS(XLINK_NS, 'href');
if (attr) {
  // Zuerst entfernen, sonst InUseAttributeError
  quelle.removeAttributeNode(attr);
  ziel.setAttributeNodeNS(attr);
  console.log(attr.ownerElement === ziel);
}

true

// Wichtig · Fallstricke

InUseAttributeError: Gehört der Attr-Knoten schon zu einem anderen Element, wirft die Methode eine DOMException mit dem Namen InUseAttributeError. Entferne ihn vorher mit removeAttributeNode() oder kopiere ihn mit attr.cloneNode().
Präfix ist egal: Ob schon ein Attribut vorhanden ist, hängt nur von namespaceURI und localName ab. Ein anderes Präfix verhindert das Ersetzen nicht.
Einfacher geht es meist mit setAttributeNS(ns, name, value). Das spart das Erzeugen eines eigenen Knotens.
xlink:href ist in SVG 2 veraltet. Moderne Browser verstehen auch ein einfaches href ohne Namensraum.
Sicherheit: Werte wie href oder xlink:href mit javascript:-URLs können Skripte ausführen (XSS). Nicht vertrauenswürdige Eingaben vorher prüfen.
Kompatibilität: Wird von allen modernen Browsern seit Langem unterstützt. Alte Browser (z. B. IE) haben das Ersetzen teilweise nicht einheitlich gehandhabt.

Siehe auch

Element.setAttributeNode() Element.setAttributeNS() Element.getAttributeNodeNS() Element.removeAttributeNode() Document.createAttributeNS() Attr new TextFormatUpdateEvent()