Document.getElementsByTagNameNS() — Methode · JavaScript-Referenz

Signatur

Document.prototype.getElementsByTagNameNS(namespace, localName)

Beschreibung

getElementsByTagNameNS() durchsucht das gesamte Dokument nach Elementen, deren Namensraum-URI und lokaler Name übereinstimmen. Die Methode ist die namensraumbewusste Variante von getElementsByTagName(). Man braucht sie vor allem, wenn in einem Dokument mehrere XML-Vokabulare gemischt sind, etwa SVG und MathML in HTML oder eigene Namensräume in XML- und XHTML-Dokumenten.

Verglichen wird mit dem lokalen Namen, also ohne Präfix: Bei <svg:circle> sucht man nach "circle", nicht nach "svg:circle". Beide Argumente akzeptieren den Platzhalter "*". Damit findet man zum Beispiel alle Elemente eines Namensraums oder alle Elemente mit einem bestimmten Namen, egal in welchem Namensraum sie liegen.

Der Rückgabewert ist eine live HTMLCollection. Sie aktualisiert sich automatisch, sobald passende Elemente ins DOM eingefügt oder daraus entfernt werden. Die Reihenfolge entspricht der Dokumentreihenfolge (Tiefensuche). Soll nur ein Teilbaum durchsucht werden, gibt es die gleichnamige Methode Element.prototype.getElementsByTagNameNS().

Parameter

Name	Typ	Default	Beschreibung
$namespace Pflicht	string \| null		Namensraum-URI der gesuchten Elemente, z. B. `"http://www.w3.org/2000/svg"`. `""` passt auf alle Namensräume. `null` oder `""` steht für Elemente ohne* Namensraum.
$localName Pflicht	string		Lokaler Name des Elements ohne Präfix, z. B. `"circle"`. `"*"` passt auf alle Elemente. Die Groß-/Kleinschreibung zählt.

Rückgabewert

Typ

HTMLCollection

Beschreibung

Eine live aktualisierte HTMLCollection der passenden Elemente in Dokumentreihenfolge. Gibt es keinen Treffer, ist sie leer (length === 0), aber niemals null.

Beispiele

Alle SVG-Kreise in einer HTML-Seite finden

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

document.body.innerHTML = `
  <svg width="100" height="50">
    <circle cx="20" cy="25" r="10" />
    <circle cx="60" cy="25" r="15" />
  </svg>`;

const circles = document.getElementsByTagNameNS(SVG_NS, 'circle');
console.log(circles.length);

// HTMLCollection ist kein Array – vorher umwandeln
for (const c of Array.from(circles)) {
  c.setAttribute('fill', 'tomato');
}
console.log(circles[1].getAttribute('r'));

2 15

Eigenen Namensraum in einem XML-Dokument auslesen

const xml = `<?xml version="1.0"?>
<katalog xmlns:p="urn:shop:produkt">
  <p:artikel id="a1">Tastatur</p:artikel>
  <p:artikel id="a2">Maus</p:artikel>
  <artikel id="x">Ohne Namensraum</artikel>
</katalog>`;

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

// Lokaler Name ohne Präfix "p:"
const produkte = doc.getElementsByTagNameNS('urn:shop:produkt', 'artikel');
console.log([...produkte].map(el => el.textContent));

// Elemente ohne Namensraum: null übergeben
const ohneNs = doc.getElementsByTagNameNS(null, 'artikel');
console.log(ohneNs.length);

["Tastatur", "Maus"] 1

Platzhalter und Live-Verhalten

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

// Alle Elemente im SVG-Namensraum
const allSvg = document.getElementsByTagNameNS(SVG_NS, '*');
console.log('vorher:', allSvg.length);

const svg = document.createElementNS(SVG_NS, 'svg');
svg.appendChild(document.createElementNS(SVG_NS, 'rect'));
document.body.appendChild(svg);

// Die Collection hat sich von selbst aktualisiert
console.log('nachher:', allSvg.length);

vorher: 0 nachher: 2

// Wichtig · Fallstricke

HTML-Elemente haben einen Namensraum: In HTML-Dokumenten liegen gewöhnliche Elemente im Namensraum http://www.w3.org/1999/xhtml. getElementsByTagNameNS(null, 'div') findet sie deshalb nicht. Richtig ist getElementsByTagNameNS('http://www.w3.org/1999/xhtml', 'div').
Kein Präfix im Namen: Mit 'svg:circle' gibt es keinen Treffer. Übergeben Sie nur den lokalen Namen. Das Präfix selbst spielt keine Rolle, entscheidend ist allein die Namensraum-URI.
Groß-/Kleinschreibung: Anders als getElementsByTagName() in HTML-Dokumenten vergleicht diese Methode immer exakt. 'foreignObject' und 'foreignobject' sind also verschiedene Namen.
Live-Collection: Wenn Sie in einer Schleife über die Collection Elemente entfernen, verschieben sich die Indizes. Wandeln Sie sie vorher mit Array.from() oder dem Spread-Operator um.
Alternative: querySelectorAll() gibt eine statische NodeList zurück. Namensräume unterstützt sie in CSS-Selektoren aber nur sehr eingeschränkt (@namespace funktioniert nicht in querySelectorAll). Für eine gezielte Suche nach Namensraum ist getElementsByTagNameNS() daher die robustere Wahl.
Kompatibilität: Die Methode wird in allen modernen Browsern und in DOM-Implementierungen wie jsdom unterstützt. Sehr alte Browser gaben statt einer HTMLCollection eine NodeList zurück.

Siehe auch

Document.getElementsByTagName() Element.getElementsByTagNameNS() Document.createElementNS() Document.querySelectorAll() HTMLCollection Element.namespaceURI