HTMLAllCollection.namedItem() — Methode · JavaScript-Referenz

Signatur

HTMLAllCollection.prototype.namedItem(name)

Beschreibung

Die Methode namedItem() gehört zum Interface HTMLAllCollection. Dessen einzige Instanz ist document.all. Die Methode sucht im ganzen Dokument nach Elementen, deren id dem angegebenen Namen entspricht. Bei bestimmten Elementen zählt auch das name-Attribut, nämlich bei a, button, embed, form, frame, frameset, iframe, img, input, map, meta, object, select und textarea.

Der Rückgabewert hängt von der Zahl der Treffer ab. Laut HTML-Spezifikation gilt:

genau ein Treffer: das Element selbst,
mehrere Treffer: eine HTMLCollection mit allen passenden Elementen in Dokumentreihenfolge,
kein Treffer oder leerer String: null.

Die Methode gibt es nur, damit alter Code weiter funktioniert, der aus der Zeit des Internet Explorer 4 stammt. In neuem Code solltest du sie nicht verwenden. Besser geeignet sind document.getElementById(), document.getElementsByName() oder document.querySelector(). Diese Methoden liefern immer einen vorhersehbaren Typ zurück.

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string		Wert, der mit dem `id`-Attribut oder (bei den oben genannten Elementen) mit dem `name`-Attribut verglichen wird. Groß- und Kleinschreibung werden unterschieden. Andere Werte werden in einen String umgewandelt.

Rückgabewert

Typ

Element | HTMLCollection | null

Beschreibung

Das passende Element, bei mehreren Treffern eine HTMLCollection und ohne Treffer null.

Beispiele

Element per id finden

// HTML: <div id="hinweis">Bitte speichern!</div>
const el = document.all.namedItem('hinweis');
console.log(el?.textContent);

Bitte speichern!

Mehrere Treffer über das name-Attribut

// HTML:
// <input type="radio" name="farbe" value="rot">
// <input type="radio" name="farbe" value="blau">
const treffer = document.all.namedItem('farbe');

// Rückgabetyp prüfen: einzelnes Element oder Collection?
const liste = treffer instanceof HTMLCollection
  ? [...treffer]
  : treffer ? [treffer] : [];

console.log(liste.map((el) => el.value));

["rot", "blau"]

Kein Treffer und moderner Ersatz

console.log(document.all.namedItem('gibtEsNicht')); // null
console.log(document.all.namedItem(''));            // null

// Empfohlene Alternativen mit vorhersehbarem Typ:
const einzeln = document.getElementById('hinweis');
const gruppe = document.getElementsByName('farbe'); // NodeList
console.log(einzeln !== null, gruppe.length);

null null true 2

// Wichtig · Fallstricke

Uneinheitlicher Rückgabetyp: Die Methode liefert je nach Trefferzahl ein Element, eine HTMLCollection oder null. Prüfe den Typ deshalb immer, zum Beispiel mit instanceof HTMLCollection. Manche Dokumentationen sprechen nur vom „ersten Element“. Das stimmt nicht mit der Spezifikation und dem Verhalten der Browser überein.
Legacy-Verhalten: document.all ist das einzige Objekt, das als „falsy“ gilt. typeof document.all ergibt "undefined". Eine Prüfung wie if (document.all) schlägt deshalb fehl, obwohl das Objekt vorhanden ist.
Das name-Attribut zählt nur bei bestimmten Elementen. Ein <div name="x"> wird darüber nicht gefunden.
Die Methode ist in allen Browsern verfügbar, aber veraltet. Verwende in neuem Code getElementById(), getElementsByName() oder querySelector().
Dieselbe Suche erreichst du auch mit der Klammerschreibweise document.all['name'] oder mit document.all.name.

Siehe auch

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