NamedNodeMap.setNamedItem() — Methode · JavaScript-Referenz

Signatur

NamedNodeMap.prototype.setNamedItem(attr)

Beschreibung

Die Methode setNamedItem() fügt ein Attr-Knotenobjekt in eine NamedNodeMap ein – typischerweise in element.attributes. Existiert bereits ein Attribut mit demselben qualifizierten Namen, wird es ersetzt und das alte Attr-Objekt zurückgegeben. Andernfalls ist der Rückgabewert null.

Da element.attributes live mit dem Element verbunden ist, wirkt sich der Aufruf sofort auf das Element aus: Das Attribut erscheint im DOM, CSS-Selektoren greifen, und MutationObserver melden die Änderung. Die Methode entspricht funktional Element.prototype.setAttributeNode().

Nützlich ist setNamedItem() vor allem, wenn man mit Attr-Objekten arbeitet, etwa um ein Attribut von einem Element auf ein anderes zu übertragen oder ein mit document.createAttribute() erzeugtes Attribut einzuhängen. Für den Alltag ist element.setAttribute(name, value) meist einfacher und besser lesbar.

Parameter

Name	Typ	Default	Beschreibung
$attr Pflicht	Attr		Das einzufügende Attributobjekt, z. B. erzeugt mit `document.createAttribute()` oder aus einer anderen Map entfernt. Maßgeblich für das Ersetzen ist sein `name`.

Rückgabewert

Typ

Attr | null

Beschreibung

Das ersetzte Attr-Objekt, falls schon ein Attribut mit gleichem Namen vorhanden war, sonst null.

Beispiele

Neues Attribut erzeugen und einfügen

const button = document.createElement('button');
const attr = document.createAttribute('aria-label');
attr.value = 'Menü öffnen';

const replaced = button.attributes.setNamedItem(attr);
console.log(replaced);
console.log(button.outerHTML);

null <button aria-label="Menü öffnen"></button>

Vorhandenes Attribut ersetzen

const input = document.createElement('input');
input.setAttribute('type', 'text');

const typeAttr = document.createAttribute('type');
typeAttr.value = 'email';

const old = input.attributes.setNamedItem(typeAttr);
console.log(old.value);           // altes Attr-Objekt
console.log(input.getAttribute('type'));

text email

Attribut von einem Element auf ein anderes verschieben

const source = document.createElement('div');
source.setAttribute('data-id', '42');
const target = document.createElement('section');

// Erst aus der Quelle entfernen, sonst InUseAttributeError
const attr = source.attributes.removeNamedItem('data-id');
target.attributes.setNamedItem(attr);

console.log(source.hasAttribute('data-id'), target.dataset.id);

false 42

// Wichtig · Fallstricke

InUseAttributeError: Gehört das Attr bereits zu einem anderen Element (attr.ownerElement ist gesetzt), wirft der Aufruf eine DOMException vom Typ InUseAttributeError. Entferne das Attribut vorher oder klone es mit attr.cloneNode().
Das Einfügen desselben Attr in dasselbe Element ist dagegen erlaubt und gibt das Attribut selbst zurück.
Bei Attributen mit Namespace (z. B. xlink:href in SVG) ist setNamedItemNS() die präzisere Wahl.
In HTML-Dokumenten werden Attributnamen, die mit document.createAttribute() erzeugt wurden, in Kleinbuchstaben umgewandelt.
Sicherheit: Werte von Ereignis-Attributen wie onclick oder von href mit javascript:-URLs werden ausgeführt – niemals ungeprüfte Benutzereingaben so setzen (XSS).
Die Methode wird von allen Browsern unterstützt; in modernem Code ist setAttribute() meist vorzuziehen.

Siehe auch

Attr NamedNodeMap.getNamedItem() NamedNodeMap.setNamedItemNS() NamedNodeMap.getNamedItemNS() NamedNodeMap.removeNamedItem()