HTMLAllCollection.item() — Methode · JavaScript-Referenz

Signatur

HTMLAllCollection.prototype.item(nameOrIndex)

Beschreibung

Die Methode item() gehört zur Schnittstelle HTMLAllCollection. Diese Schnittstelle ist über die Eigenschaft document.all erreichbar. Die Sammlung enthält alle Elemente des Dokuments in Dokumentreihenfolge. Mit item() lassen sich einzelne Elemente auf zwei Arten abfragen: über ihre Position (Index) oder über ihr id- bzw. name-Attribut.

Die Methode wertet das Argument so aus:

Ist nameOrIndex ein gültiger Array-Index (z. B. 0 oder "3"), wird das Element an dieser Position zurückgegeben, sonst null.
Andernfalls sucht die Methode nach Elementen mit passender id oder mit passendem name-Attribut. Bei name zählen nur bestimmte Elemente, etwa a, button, form, iframe, img, input, select, textarea, meta, object, embed und map. Passt genau ein Element, wird dieses zurückgegeben. Passen mehrere, erhältst du eine HTMLCollection. Passt keines, ist das Ergebnis null.
Ohne Argument ist das Ergebnis null.

document.all und damit auch item() gibt es heute nur noch, damit alter Code weiterläuft. In neuem Code solltest du stattdessen document.getElementById(), document.querySelector() oder document.getElementsByName() verwenden. Die Methode ist trotzdem nützlich, wenn du alten Code verstehst oder umbaust.

Parameter

Name	Typ	Default	Beschreibung
$nameOrIndex	string \| number		Ein Index (Position in Dokumentreihenfolge, beginnend bei `0`) oder ein Wert, der mit dem `id`- bzw. `name`-Attribut der gesuchten Elemente verglichen wird. Zahlen werden intern in Zeichenketten umgewandelt.

Rückgabewert

Typ

Element | HTMLCollection | null

Beschreibung

Das gefundene Element. Passen mehrere Elemente zu einem Namen oder einer ID, eine HTMLCollection mit diesen Elementen. null, wenn nichts gefunden wurde oder kein Argument übergeben wurde.

Beispiele

Zugriff über den Index

// Das erste Element im Dokument ist immer <html>
const first = document.all.item(0);
console.log(first.tagName);

// Ein Index außerhalb des Bereichs liefert null
console.log(document.all.item(99999));

HTML null

Zugriff über id und name – einzelnes Element oder Sammlung

document.body.innerHTML = `
  <div id="hinweis">Bitte ausfüllen</div>
  <input type="radio" name="farbe" value="rot">
  <input type="radio" name="farbe" value="blau">
`;

const hinweis = document.all.item('hinweis');
console.log(hinweis.textContent);

// Mehrere Treffer: Ergebnis ist eine HTMLCollection
const farben = document.all.item('farbe');
console.log(farben instanceof HTMLCollection, farben.length);

console.log(document.all.item('gibtsnicht'));

Bitte ausfüllen true 2 null

Robuster Umgang mit dem gemischten Rückgabetyp

// Hilfsfunktion: macht aus dem Ergebnis immer ein Array
const allByName = (key) => {
  const result = document.all.item(key);
  if (result === null) return [];
  return result instanceof HTMLCollection ? [...result] : [result];
};

console.log(allByName('farbe').map((el) => el.value));

// Moderne Alternative ohne document.all
const modern = [...document.getElementsByName('farbe')].map((el) => el.value);
console.log(modern);

["rot", "blau"] ["rot", "blau"]

// Wichtig · Fallstricke

Altlast-API: document.all ist im HTML-Standard nur deshalb enthalten, damit alter Code weiterläuft. Verwende in neuem Code getElementById(), querySelector() oder getElementsByName().
Uneinheitlicher Rückgabetyp: Je nach Anzahl der Treffer kommt ein Element, eine HTMLCollection oder null zurück. Prüfe das Ergebnis immer mit instanceof, bevor du darauf zugreifst.
Falsy-Sonderfall: document.all verhält sich absichtlich wie ein falscher Wert: typeof document.all === "undefined", und if (document.all) ist falsch. Die Methode funktioniert trotzdem. Eine Prüfung wie if (document.all) { … } überspringt den Code aber.
Statt item() kann man die Sammlung auch direkt aufrufen, z. B. document.all("id") oder document.all[0]. Das Ergebnis ist dasselbe.
Das name-Attribut zählt nur bei bestimmten Elementen (siehe Beschreibung). Ein <div name="x"> wird über den Namen nicht gefunden.
Die Sammlung ist live: Wenn sich das DOM ändert, ändern sich auch die Indizes. Gespeicherte Positionen können deshalb veralten.

Siehe auch

Document.all HTMLAllCollection.namedItem() HTMLCollection.item() HTMLCollection.namedItem() HTMLSelectElement.item()