Element.getElementsByTagNameNS() — Methode · JavaScript-Referenz

Signatur

Element.prototype.getElementsByTagNameNS(namespaceURI, localName)

Beschreibung

getElementsByTagNameNS() sucht im Teilbaum unterhalb eines Elements alle Nachfahren, deren Namensraum-URI und lokaler Name passen. Das Element selbst wird nicht mitgezählt. Die Treffer stehen in Dokumentreihenfolge, also in der Reihenfolge einer Tiefensuche.

Die Methode ist die namensraumbewusste Variante von getElementsByTagName(). Man braucht sie vor allem bei XML-Dokumenten mit mehreren Namensräumen (z. B. Atom-Feeds, SOAP, XHTML) sowie bei eingebettetem SVG und MathML in HTML. Dort kann derselbe lokale Name wie a oder title sowohl ein HTML-Element als auch ein SVG-Element bezeichnen.

Wichtig: Verglichen wird der lokale Name ohne Präfix, also entry statt atom:entry. Das Präfix im Quelltext spielt keine Rolle, entscheidend ist allein die Namensraum-URI. Für beide Parameter kann man den Platzhalter "*" angeben.

Die zurückgegebene Sammlung ist live. Sie ändert sich also automatisch, wenn Elemente zum DOM hinzukommen oder daraus entfernt werden.

Parameter

Name	Typ	Default	Beschreibung
$namespaceURI 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 der Elemente ohne Präfix, z. B. `"circle"`. `"*"` passt auf alle Elemente. Groß- und Kleinschreibung wird unterschieden.

Rückgabewert

Typ

HTMLCollection

Beschreibung

Eine live aktualisierte HTMLCollection mit den passenden Nachfahren-Elementen in Dokumentreihenfolge. Gibt es keine Treffer, ist die Sammlung leer (length === 0).

Beispiele

SVG-Elemente in einem HTML-Container finden

// HTML: <div id="chart"><svg><circle r="5"/><circle r="8"/><rect/></svg></div>
const SVG_NS = 'http://www.w3.org/2000/svg';
const chart = document.getElementById('chart');

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

for (const c of circles) {
  c.setAttribute('fill', 'tomato');
}

2

Atom-Feed mit DOMParser auswerten

const xml = `<feed xmlns="http://www.w3.org/2005/Atom" xmlns:media="http://search.yahoo.com/mrss/">
  <entry><title>Erster Beitrag</title><media:thumbnail url="a.jpg"/></entry>
  <entry><title>Zweiter Beitrag</title><media:thumbnail url="b.jpg"/></entry>
</feed>`;

const doc = new DOMParser().parseFromString(xml, 'application/xml');
const ATOM = 'http://www.w3.org/2005/Atom';
const MEDIA = 'http://search.yahoo.com/mrss/';

const entries = [...doc.documentElement.getElementsByTagNameNS(ATOM, 'entry')];
const items = entries.map((entry) => ({
  title: entry.getElementsByTagNameNS(ATOM, 'title')[0].textContent,
  thumb: entry.getElementsByTagNameNS(MEDIA, 'thumbnail')[0]?.getAttribute('url')
}));
console.log(items);

[ { title: 'Erster Beitrag', thumb: 'a.jpg' }, { title: 'Zweiter Beitrag', thumb: 'b.jpg' } ]

Live-Verhalten und Platzhalter

const SVG_NS = 'http://www.w3.org/2000/svg';
const svg = document.createElementNS(SVG_NS, 'svg');
document.body.append(svg);

// Alle Elemente im SVG-Namensraum unterhalb von <body>
const allSvg = document.body.getElementsByTagNameNS(SVG_NS, '*');
console.log(allSvg.length); // 1 (das <svg> selbst)

svg.append(document.createElementNS(SVG_NS, 'line'));
console.log(allSvg.length); // automatisch aktualisiert

1 2

// Wichtig · Fallstricke

Live-Sammlung: Entfernt man in einer Schleife Elemente aus der Sammlung, verschieben sich die Indizes. Deshalb vorher mit [...coll] oder Array.from() in ein Array kopieren.
Lokaler Name statt qualifiziertem Namen: getElementsByTagNameNS(ns, 'atom:entry') findet nichts. Richtig ist 'entry'.
HTML-Elemente gehören in HTML-Dokumenten zum Namensraum http://www.w3.org/1999/xhtml, nicht zu null. Anders als bei getElementsByTagName() wird der Name nicht automatisch in Kleinbuchstaben umgewandelt.
Das Element, auf dem man die Methode aufruft, ist nie selbst ein Treffer. Durchsucht werden nur seine Nachfahren.
Leistung: Die Methode ist schnell und wird intern oft zwischengespeichert. Für komplexe Filter ist querySelectorAll() flexibler, kann aber Namensräume nur über CSS-@namespace ansprechen, was in querySelectorAll() nicht verfügbar ist.
Kompatibilität: Wird in allen modernen Browsern unterstützt. In sehr alten Browsern gab die Methode eine NodeList statt einer HTMLCollection zurück.

Siehe auch

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