Attr.localName — Eigenschaft · JavaScript-Referenz

Signatur

Attr.localName

Beschreibung

Die Eigenschaft Attr.localName gibt den lokalen Teil des qualifizierten Namens eines Attributs zurück. Ein qualifizierter Name hat die Form präfix:lokalerName. Bei xlink:href ist xlink das Präfix (siehe Attr.prefix) und href der lokale Name.

Hat ein Attribut kein Präfix, was bei normalen HTML-Attributen wie class oder data-id die Regel ist, sind localName und name gleich. Wichtig wird der Unterschied bei XML-Dokumenten, SVG und MathML mit Namensräumen. Dort bestimmt man mit localName zusammen mit namespaceURI eindeutig, um welches Attribut es sich handelt, egal welches Präfix der Autor gewählt hat.

Die Eigenschaft ist schreibgeschützt. Zuweisungen werden ohne Fehler ignoriert, im Strict Mode lösen sie einen TypeError aus. Wer ein Attribut umbenennen will, muss es entfernen und neu anlegen, zum Beispiel mit Element.setAttributeNS().

Rückgabewert

Typ

string

Beschreibung

Der lokale Name des Attributs ohne Präfix. In HTML-Dokumenten werden Attributnamen von HTML-Elementen beim Parsen kleingeschrieben, deshalb ist auch localName dort kleingeschrieben.

Beispiele

Lokaler Name eines einfachen HTML-Attributs

const button = document.createElement('button');
button.setAttribute('data-action', 'save');

const attr = button.getAttributeNode('data-action');
console.log(attr.localName); // lokaler Name
console.log(attr.name);      // qualifizierter Name
console.log(attr.prefix);    // kein Präfix

data-action data-action null

Präfix und lokalen Namen bei SVG/XLink unterscheiden

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');
use.setAttributeNS(XLINK_NS, 'xlink:href', '#icon-star');

const attr = use.attributes[0];
console.log(attr.name);         // qualifizierter Name
console.log(attr.prefix);       // Präfix
console.log(attr.localName);    // lokaler Name
console.log(attr.namespaceURI);

xlink:href xlink href http://www.w3.org/1999/xlink

Attribute unabhängig vom Präfix auswerten

const xml = `<doc xmlns:a="urn:demo" xmlns:b="urn:demo">
  <item a:id="1"/>
  <item b:id="2"/>
</doc>`;

const doc = new DOMParser().parseFromString(xml, 'application/xml');

// Beide Präfixe verweisen auf denselben Namensraum
const ids = [...doc.querySelectorAll('item')].flatMap((el) =>
  [...el.attributes]
    .filter((a) => a.namespaceURI === 'urn:demo' && a.localName === 'id')
    .map((a) => `${a.name} → ${a.value}`)
);

console.log(ids);

["a:id → 1", "b:id → 2"]

Schreibschutz im Strict Mode

'use strict';
const el = document.createElement('div');
el.setAttribute('title', 'Hallo');
const attr = el.getAttributeNode('title');

try {
  attr.localName = 'label';
} catch (err) {
  console.log(err instanceof TypeError); // true
}
console.log(attr.localName);

true title

// Wichtig · Fallstricke

Schreibgeschützt: Zuweisungen haben keine Wirkung, im Strict Mode lösen sie einen TypeError aus. Zum Umbenennen das Attribut entfernen und mit setAttribute() bzw. setAttributeNS() neu setzen.
Groß-/Kleinschreibung: In HTML-Dokumenten werden Attributnamen von HTML-Elementen kleingeschrieben. In XML-Dokumenten und bei Elementen, die mit createElementNS() erzeugt wurden, bleibt die ursprüngliche Schreibweise erhalten (z. B. viewBox in SVG).
Setzen mit Doppelpunkt ohne Namensraum: setAttribute('xlink:href', …) legt ein Attribut ohne Namensraum an. Dessen localName ist dann xlink:href und prefix ist null. Für einen echten Namensraum setAttributeNS() verwenden.
Kompatibilität: Wird von allen modernen Browsern unterstützt. In älteren Browsern (Chrome vor 46, Firefox vor 48) war localName auf Node definiert statt auf Attr. Das Verhalten ist gleich, nur 'localName' in Attr.prototype kann dort false ergeben.

Siehe auch

Attr Attr.name Attr.prefix Attr.namespaceURI Element.localName Element.setAttributeNS() Element.getAttributeNode()