Document.getElementsByTagName() — Methode · JavaScript-Referenz

Signatur

document.getElementsByTagName(name)

Beschreibung

Die Methode getElementsByTagName() der Schnittstelle Document durchsucht das gesamte Dokument einschließlich des Wurzelelements (<html>). Sie liefert alle Elemente mit dem angegebenen Tag-Namen als HTMLCollection zurück, und zwar in Dokumentreihenfolge (Tiefensuche, Pre-Order).

Die Sammlung ist live: Fügt man später passende Elemente ins DOM ein oder entfernt welche, ändert sich die Sammlung automatisch mit. Man muss die Methode also nicht erneut aufrufen. Das ist praktisch, wenn man z. B. die Anzahl aller Absätze fortlaufend beobachten will. Beim Iterieren und gleichzeitigen Verändern des DOM ist das aber eine typische Fehlerquelle.

Mit dem Sonderwert "*" bekommt man alle Elemente des Dokuments. In HTML-Dokumenten wird der Tag-Name bei HTML-Elementen ohne Beachtung der Groß-/Kleinschreibung verglichen. Bei SVG- oder MathML-Elementen muss die Schreibweise dagegen exakt stimmen (z. B. "linearGradient").

Will man nur innerhalb eines bestimmten Teilbaums suchen, gibt es die gleichnamige Methode Element.prototype.getElementsByTagName(). Für komplexere Auswahlen oder eine statische Momentaufnahme ist querySelectorAll() oft die bessere Wahl.

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string		Qualifizierter Tag-Name, z. B. `"p"`, `"img"` oder `"svg:rect"`. Der Sonderwert `"*"` steht für alle Elemente. In HTML-Dokumenten wird die Groß-/Kleinschreibung bei HTML-Elementen nicht beachtet.

Rückgabewert

Typ

HTMLCollection

Beschreibung

Eine live HTMLCollection mit allen passenden Elementen in Dokumentreihenfolge. Gibt es keinen Treffer, ist die Sammlung leer (length === 0). Es wird nie null zurückgegeben.

Beispiele

Alle Absätze zählen und markieren

const absaetze = document.getElementsByTagName('p');
console.log(`Anzahl Absätze: ${absaetze.length}`);

// HTMLCollection ist kein Array, lässt sich aber mit for...of durchlaufen
for (const p of absaetze) {
  p.classList.add('text-block');
}

Anzahl Absätze: 3

Live-Verhalten beobachten

const bilder = document.getElementsByTagName('img');
console.log('Vorher:', bilder.length);

const img = document.createElement('img');
img.src = '/logo.png';
img.alt = 'Logo';
document.body.append(img);

// Kein erneuter Aufruf nötig: die Sammlung hat sich schon aktualisiert
console.log('Nachher:', bilder.length);

Vorher: 2 Nachher: 3

Elemente sicher entfernen (Array-Kopie statt Live-Sammlung)

// Falsch wäre: for (let i = 0; i < scripts.length; i++) scripts[i].remove();
// Dabei wird jedes zweite Element übersprungen, weil die Sammlung beim Entfernen schrumpft.
const iframes = Array.from(document.getElementsByTagName('iframe'));
iframes.forEach((frame) => frame.remove());

console.log(document.getElementsByTagName('iframe').length);

Alle Elemente mit "*" und Array-Methoden

const alle = [...document.getElementsByTagName('*')];
const tagStatistik = alle.reduce((acc, el) => {
  const tag = el.localName;
  acc[tag] = (acc[tag] ?? 0) + 1;
  return acc;
}, {});

console.log(tagStatistik);

{ html: 1, head: 1, title: 1, body: 1, div: 4, p: 3, ... }

// Wichtig · Fallstricke

Live-Sammlung beim Verändern: Entfernt oder verschiebt man Elemente, während man per Index über die Sammlung läuft, werden Einträge übersprungen. Vorher mit Array.from() oder Spread-Syntax in ein statisches Array kopieren oder rückwärts iterieren.
Keine Array-Methoden: HTMLCollection hat kein forEach, map oder filter. Zum Durchlaufen gehen for...of, Array.from() oder [...collection].
Groß-/Kleinschreibung: In HTML-Dokumenten passt "DIV" auf <div>. SVG-Elemente wie <foreignObject> muss man aber exakt schreiben. In XML/XHTML-Dokumenten wird die Schreibweise immer beachtet. Für Namensräume gibt es getElementsByTagNameNS().
Leistung: Der Aufruf selbst ist sehr schnell, weil Browser die Sammlung zwischenspeichern und erst beim Zugriff auswerten. Der Zugriff auf length in einer Schleife kann bei einem DOM, das sich ständig ändert, jedoch teuer werden.
Kompatibilität: Wird seit DOM Level 1 von allen Browsern unterstützt. In sehr alten Versionen (vor IE9 / ältere WebKit-Versionen) wurde teilweise eine NodeList statt einer HTMLCollection zurückgegeben.

Siehe auch

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