Element.getElementsByTagName() — Methode · JavaScript-Referenz

Signatur

Element.prototype.getElementsByTagName(tagName)

Beschreibung

Element.getElementsByTagName() durchsucht den gesamten Teilbaum unterhalb des Elements, auf dem die Methode aufgerufen wird. Das Element selbst gehört nicht dazu. Gefundene Elemente kommen in Dokumentreihenfolge (Tiefensuche) zurück. Mit dem Sonderwert "*" erhält man alle Nachfahren-Elemente.

Der Rückgabewert ist eine dynamische HTMLCollection: Sie aktualisiert sich von selbst, wenn Elemente in den Teilbaum eingefügt oder daraus entfernt werden. Das ist nützlich, wenn man eine Sammlung einmal holt und später immer den aktuellen Stand braucht. Beim Umbau des DOM während einer Schleife kann es aber zu überraschendem Verhalten führen.

In HTML-Dokumenten wird der Tag-Name für HTML-Elemente ohne Rücksicht auf Groß- und Kleinschreibung verglichen, denn er wird intern in Kleinbuchstaben umgewandelt. Für Elemente in anderen Namensräumen (z. B. SVG-Elemente wie linearGradient) wird die Schreibweise dagegen beachtet. Für einfache Abfragen nach Tag-Namen ist die Methode schnell und schlank. Für komplexere Kriterien ist querySelectorAll() meist die bessere Wahl.

Parameter

Name	Typ	Default	Beschreibung
$tagName Pflicht	string		Qualifizierter Name der gesuchten Elemente, z. B. `"p"`, `"li"` oder `"svg:rect"`. Der Sonderwert `"*"` passt auf alle Elemente. In HTML-Dokumenten wird bei HTML-Elementen nicht zwischen Groß- und Kleinschreibung unterschieden.

Rückgabewert

Typ

HTMLCollection

Beschreibung

Eine dynamische HTMLCollection mit allen passenden Nachfahren-Elementen in Dokumentreihenfolge. Gibt es keine Treffer, ist die Sammlung leer (length === 0). Die Methode gibt nie null zurück.

Beispiele

Alle Absätze in einem Artikel zählen und markieren

// HTML: <article id="beitrag"><p>Eins</p><p>Zwei</p><div><p>Drei</p></div></article>
const artikel = document.getElementById('beitrag');
const absaetze = artikel.getElementsByTagName('p');

console.log(`Anzahl Absätze: ${absaetze.length}`);

// HTMLCollection per for...of durchlaufen
for (const p of absaetze) {
  p.classList.add('lesbar');
}

Anzahl Absätze: 3

Dynamisches Verhalten der Sammlung

const liste = document.createElement('ul');
const eintraege = liste.getElementsByTagName('li');

console.log(eintraege.length); // noch leer

['Äpfel', 'Birnen'].forEach((text) => {
  const li = document.createElement('li');
  li.textContent = text;
  liste.append(li);
});

// Die Sammlung wurde automatisch aktualisiert
console.log(eintraege.length);

0 2

Sicher entfernen: erst in ein statisches Array kopieren

// Alle Bilder in einer Tabelle entfernen
const tabelle = document.querySelector('table');

// Falsch wäre: for (let i = 0; i < imgs.length; i++) imgs[i].remove();
// Dabei wird jedes zweite Element übersprungen, weil die Sammlung schrumpft.
const bilder = [...tabelle.getElementsByTagName('img')];
bilder.forEach((img) => img.remove());

console.log(tabelle.getElementsByTagName('img').length);

Alle Nachfahren mit "*" und Array-Methoden auswerten

const nav = document.querySelector('nav');
const alle = Array.from(nav.getElementsByTagName('*'));

const tagNamen = [...new Set(alle.map((el) => el.tagName.toLowerCase()))];
console.log(tagNamen);

["ul", "li", "a"]

// Wichtig · Fallstricke

Dynamische Sammlung: Wer beim Durchlaufen per Index Elemente entfernt oder einfügt, verändert die Sammlung gleichzeitig. Dann werden Elemente übersprungen, oder es entstehen Endlosschleifen. Vorher mit Array.from() oder dem Spread-Operator in ein Array kopieren, oder rückwärts durchlaufen.
Keine Array-Methoden: HTMLCollection kennt kein forEach(), map() oder filter(). for...of funktioniert in modernen Browsern, für die Array-Methoden braucht man Array.from().
Nur Nachfahren: Das Element, auf dem die Methode aufgerufen wird, ist nie selbst im Ergebnis, auch wenn sein Tag-Name passt.
Groß-/Kleinschreibung: In HTML-Dokumenten passen "DIV" und "div" beide auf HTML-Elemente. Bei SVG- und MathML-Elementen oder in XML-/XHTML-Dokumenten wird die Schreibweise beachtet. Für Namensräume gibt es getElementsByTagNameNS().
Performance: Die Methode ist meist schneller als querySelectorAll(), weil die Sammlung erst bei Zugriff ausgewertet und vom Browser zwischengespeichert wird. Wiederholter Zugriff auf length nach DOM-Änderungen kann aber eine Neuauswertung auslösen.
Kompatibilität: Wird von allen Browsern unterstützt, auch von sehr alten. In älteren Versionen (vor 2014) gab manche Engine eine NodeList statt einer HTMLCollection zurück.

Siehe auch

Document.getElementsByTagName() Element.getElementsByTagNameNS() Element.getElementsByClassName() Element.querySelectorAll() HTMLCollection Element.tagName