NamedNodeMap.setNamedItemNS() — Methode · JavaScript-Referenz

Signatur

NamedNodeMap.prototype.setNamedItemNS(attr)

Beschreibung

setNamedItemNS() fügt ein Attr-Knoten in die Attributliste eines Elements ein (meist element.attributes). Welches Attribut gemeint ist, entscheiden die Kombination aus namespaceURI und localName des übergebenen Attributs. Das Präfix spielt dafür keine Rolle. Gibt es schon ein Attribut mit genau diesem Namensraum und lokalen Namen, wird es ersetzt und das alte Attr-Objekt zurückgegeben. Andernfalls ist der Rückgabewert null.

Die Methode ist vor allem für XML-Dokumente mit Namensräumen gedacht, etwa SVG mit xlink:href, MathML oder eigene XML-Formate. Das passende Attribut erzeugt man mit document.createAttributeNS(). Man kann es aber auch einem anderen Element entnehmen, vorher klonen und dann einfügen.

Laut aktueller DOM-Spezifikation verhalten sich setNamedItem() und setNamedItemNS() gleich: Beide vergleichen über Namensraum und lokalen Namen. Im Alltag reicht meistens element.setAttributeNS(ns, name, value). Mit setNamedItemNS() arbeitet man dagegen direkt mit Attr-Objekten, zum Beispiel um ein Attribut mit Präfix und Wert von einem Knoten auf einen anderen zu übertragen.

Parameter

Name	Typ	Default	Beschreibung
$attr Pflicht	Attr		Das einzufügende Attribut. Es darf zu keinem anderen Element gehören (`attr.ownerElement` muss `null` oder das Element selbst sein).

Rückgabewert

Typ

Attr | null

Beschreibung

Das ersetzte Attribut mit demselben Namensraum und lokalen Namen oder null, wenn keines vorhanden war. Wird das Attribut durch sich selbst ersetzt, kommt dasselbe Attr-Objekt zurück.

Beispiele

Namensraum-Attribut an ein SVG-Element anhängen

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

const previous = use.attributes.setNamedItemNS(href);
console.log(previous);
console.log(use.getAttributeNS(XLINK_NS, 'href'));

null #icon-star

Vorhandenes Attribut ersetzen und altes Objekt erhalten

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

const status = doc.createAttributeNS(NS, 'm:status');
status.value = 'published';

const old = item.attributes.setNamedItemNS(status);
console.log(old.value);
console.log(item.getAttributeNS(NS, 'status'));

draft published

Attribut von einem Element auf ein anderes kopieren

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

const source = document.createElementNS(SVG_NS, 'use');
source.setAttributeNS(XLINK_NS, 'xlink:href', '#logo');
const target = document.createElementNS(SVG_NS, 'use');

const attr = source.attributes.getNamedItemNS(XLINK_NS, 'href');

try {
  // Schlägt fehl: attr gehört noch zu source
  target.attributes.setNamedItemNS(attr);
} catch (err) {
  console.log(err.name);
}

// Richtig: vorher klonen
target.attributes.setNamedItemNS(attr.cloneNode());
console.log(target.getAttributeNS(XLINK_NS, 'href'));

InUseAttributeError #logo

// Wichtig · Fallstricke

InUseAttributeError: Gehört das Attr bereits zu einem anderen Element, wird eine DOMException mit dem Namen InUseAttributeError ausgelöst. Deshalb vorher attr.cloneNode() verwenden oder das Attribut zuerst beim Ursprungselement entfernen.
Ob ein Attribut ersetzt wird, hängt nur von namespaceURI und localName ab. Ein anderes Präfix bei gleichem Namensraum ersetzt das vorhandene Attribut trotzdem.
Attribute ohne Namensraum (namespaceURI === null) funktionieren auch. In HTML-Dokumenten erzeugt createAttribute() dabei kleingeschriebene Namen.
Für einfache Fälle ist element.setAttributeNS() kürzer und besser lesbar.
Die Methode wird von allen modernen Browsern und von Node-DOM-Implementierungen wie jsdom unterstützt. Ältere Hinweise, man solle sie meiden, gelten nicht mehr.

Siehe auch

NamedNodeMap NamedNodeMap.setNamedItem() NamedNodeMap.getNamedItemNS() NamedNodeMap.removeNamedItemNS() Document.createAttributeNS() Element.setAttributeNS() Attr