HTMLCollection.length — Eigenschaft · JavaScript-Referenz

Signatur

get HTMLCollection.length

Beschreibung

Die schreibgeschützte Eigenschaft length gibt als nicht-negative Ganzzahl an, wie viele Elemente eine HTMLCollection enthält. Solche Sammlungen liefern z. B. document.getElementsByTagName(), document.getElementsByClassName(), element.children, document.forms oder document.images.

Weil eine HTMLCollection live ist, ändert sich length automatisch, sobald passende Elemente ins DOM eingefügt oder daraus entfernt werden. Das ist praktisch, wenn man den aktuellen Zustand abfragen will, etwa „Gibt es noch offene Einträge in der Liste?“, ohne die Sammlung neu anzufordern.

Typischerweise nutzt man length für klassische for-Schleifen mit Index-Zugriff (collection[i] bzw. collection.item(i)), für Existenzprüfungen (length > 0) und zum Zählen von Elementen. Die Eigenschaft ist rein lesend; eine Zuweisung hat keine Wirkung und wirft im Strict Mode einen TypeError.

Rückgabewert

Typ

number

Beschreibung

Nicht-negative Ganzzahl (unsigned long) mit der aktuellen Anzahl der Elemente in der Sammlung. 0, wenn die Sammlung leer ist.

Beispiele

Anzahl der Absätze zählen

const paragraphs = document.getElementsByTagName('p');
console.log(`Die Seite enthält ${paragraphs.length} Absätze.`);

if (paragraphs.length === 0) {
  console.log('Keine Absätze gefunden.');
}

Die Seite enthält 3 Absätze.

Klassische Schleife über Formularfelder

const inputs = document.forms[0].getElementsByTagName('input');

for (let i = 0; i < inputs.length; i++) {
  inputs[i].classList.add('geprueft');
}
console.log(`${inputs.length} Felder markiert.`);

4 Felder markiert.

Live-Verhalten: length aktualisiert sich selbst

const list = document.createElement('ul');
document.body.append(list);
const items = list.children; // live HTMLCollection

console.log(items.length); // 0

for (const text of ['Äpfel', 'Birnen']) {
  const li = document.createElement('li');
  li.textContent = text;
  list.append(li);
}
console.log(items.length); // 2

list.firstElementChild.remove();
console.log(items.length); // 1

0 2 1

Fallstrick: Elemente in einer Schleife entfernen

const hints = document.getElementsByClassName('hinweis');

// FALSCH: jedes Entfernen verkürzt length und verschiebt die Indizes
// for (let i = 0; i < hints.length; i++) hints[i].remove();

// RICHTIG: von hinten nach vorn iterieren …
for (let i = hints.length - 1; i >= 0; i--) {
  hints[i].remove();
}
// … oder: while (hints.length) hints[0].remove();
console.log(hints.length);

// Wichtig · Fallstricke

Live-Sammlung: Wenn du in einer Schleife Elemente entfernst oder die Klasse bzw. den Tag änderst, nach dem gefiltert wird, ändert sich length während der Schleife. Dann rückwärts iterieren oder vorher mit Array.from(collection) eine statische Kopie anlegen.
Performance: Bei sehr großen Dokumenten kann es sich lohnen, length vor der Schleife in einer Variablen zu speichern, sofern sich die Sammlung dabei nicht ändert.
Nur lesend: Anders als bei Arrays lässt sich eine Sammlung nicht durch collection.length = 0 leeren. Die Zuweisung wird ignoriert bzw. wirft im Strict Mode einen TypeError.
Kein Array: HTMLCollection hat kein forEach, map usw. Wandle sie mit Array.from() oder dem Spread-Operator [...collection] in ein Array um. for...of funktioniert direkt.
Im Gegensatz dazu liefert querySelectorAll() eine statische NodeList, deren length sich nicht ändert.
Kompatibilität: wird seit jeher von allen Browsern unterstützt.

Siehe auch

Element.children Array.from() HTMLAllCollection.length HTMLOptionsCollection.length HTMLFormElement.length