Element.setAttributeNS() — Methode · JavaScript-Referenz

Signatur

Element.prototype.setAttributeNS(namespace, qualifiedName, value)

Beschreibung

setAttributeNS() legt ein Attribut in einem bestimmten XML-Namensraum an oder ändert seinen Wert. Anders als setAttribute() gehört das Attribut dann eindeutig zu einer Namensraum-URI. Das ist bei XML-basierten Dokumenten wichtig, etwa bei SVG, MathML, XHTML oder eigenen XML-Formaten.

Gebraucht wird die Methode vor allem für Attribute mit Präfix: xlink:href (Namensraum http://www.w3.org/1999/xlink), xml:lang (http://www.w3.org/XML/1998/namespace) oder xmlns:*-Deklarationen (http://www.w3.org/2000/xmlns/). Für normale SVG-Attribute wie width, fill oder viewBox gibt man als Namensraum null an. Diese Attribute haben keinen Namensraum, auch wenn das Element selbst im SVG-Namensraum liegt.

Gibt es schon ein Attribut mit derselben Namensraum-URI und demselben lokalen Namen, wird nur sein Wert überschrieben. Das Präfix kann sich dabei ändern. Gibt es keins, wird ein neues Attribut angelegt. Der Wert wird immer in einen String umgewandelt.

Parameter

Name	Typ	Beschreibung
$namespace Pflicht	string \| null	Namensraum-URI des Attributs, z. B. `"http://www.w3.org/1999/xlink"`. Ein leerer String zählt wie `null` (kein Namensraum).
$qualifiedName Pflicht	string	Qualifizierter Name, optional mit Präfix, z. B. `"xlink:href"` oder `"lang"`. Der Teil hinter dem Doppelpunkt ist der lokale Name.
$value Pflicht	string	Neuer Wert des Attributs. Andere Typen werden in einen String umgewandelt.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert.

Beispiele

SVG-Element mit xlink:href auf ein Symbol verweisen lassen

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

const svg = document.createElementNS(SVG_NS, 'svg');
svg.setAttributeNS(null, 'width', '24');
svg.setAttributeNS(null, 'height', '24');

const use = document.createElementNS(SVG_NS, 'use');
// Ältere Variante für ältere Browser und Werkzeuge
use.setAttributeNS(XLINK_NS, 'xlink:href', '#icon-star');
// Moderne Variante (SVG 2) ohne Namensraum
use.setAttributeNS(null, 'href', '#icon-star');

svg.append(use);
document.body.append(svg);
console.log(use.getAttributeNS(XLINK_NS, 'href'));

#icon-star

Sprachangabe mit xml:lang in einem XML-Dokument

const XML_NS = 'http://www.w3.org/XML/1998/namespace';
const doc = new DOMParser().parseFromString('<notiz><text>Hallo</text></notiz>', 'application/xml');

const text = doc.querySelector('text');
text.setAttributeNS(XML_NS, 'xml:lang', 'de');

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

<notiz><text xml:lang="de">Hallo</text></notiz>

Bestehendes Attribut überschreiben und auslesen

const NS = 'https://example.com/meta';
const el = document.createElementNS('https://example.com/doc', 'eintrag');

el.setAttributeNS(NS, 'm:status', 'entwurf');
el.setAttributeNS(NS, 'm:status', 'veröffentlicht'); // gleicher lokaler Name, wird überschrieben

console.log(el.attributes.length);
console.log(el.getAttributeNS(NS, 'status'));
console.log(el.getAttributeNode('m:status').namespaceURI);

1 veröffentlicht https://example.com/meta

// Wichtig · Fallstricke

Häufiger Fehler: Normale SVG-Attribute wie fill oder viewBox mit dem SVG-Namensraum zu setzen. Das Attribut landet dann in einem falschen Namensraum und wird nicht angewendet. Richtig ist null als Namensraum.
Ist qualifiedName ungültig, wirft die Methode einen InvalidCharacterError. Ein NamespaceError kommt, wenn Präfix und Namensraum nicht zusammenpassen. Beispiele: ein Präfix ohne Namensraum, xml: mit einer anderen URI als dem XML-Namensraum, oder xmlns ohne http://www.w3.org/2000/xmlns/.
Der Vergleich geht über Namensraum-URI und lokalen Namen, nicht über das Präfix. Zum Auslesen nimmt man darum getAttributeNS(ns, 'href') ohne Präfix.
xlink:href gilt in SVG 2 als veraltet. Moderne Browser verstehen href ohne Namensraum. Für ältere Umgebungen setzt man beide.
Sicherheit: Werte für href bzw. xlink:href aus Benutzereingaben sollte man prüfen. Sonst können javascript:-URLs in SVG-Links XSS ermöglichen.
Browser-Kompatibilität: Die Methode wird von allen modernen Browsern seit langem unterstützt.

Siehe auch

Element.getAttributeNS() Element.removeAttributeNS() Element.hasAttributeNS() Element.setAttribute() Document.createElementNS() Element.setAttributeNodeNS() PushMessageData.bytes()