HTMLFormControlsCollection.namedItem() — Methode · JavaScript-Referenz

Signatur

HTMLFormControlsCollection.prototype.namedItem(name)

Beschreibung

Mit namedItem() holen Sie aus der Sammlung form.elements ein Steuerelement über seinen Namen. Die Methode vergleicht den übergebenen String sowohl mit dem Attribut name als auch mit dem Attribut id der Elemente. Anders als HTMLCollection.prototype.namedItem() liefert sie aber nicht einfach das erste Element, das passt.

Passt genau ein Element, bekommen Sie dieses Element zurück, zum Beispiel ein HTMLInputElement oder ein HTMLSelectElement. Passen mehrere Elemente, erhalten Sie eine RadioNodeList. Das ist typisch für eine Gruppe von Radiobuttons mit gleichem name. Über deren Eigenschaft value lesen oder setzen Sie direkt den Wert des gewählten Radiobuttons. Passt kein Element, ist der Rückgabewert null.

In der Praxis schreibt man oft kürzer form.elements.email oder form.elements["user-name"]. Beide Schreibweisen führen intern dasselbe benannte Nachschlagen aus. Der ausdrückliche Aufruf von namedItem() hat aber Vorteile: Er ist eindeutig, er kann nicht mit eingebauten Eigenschaften der Sammlung wie length oder item kollidieren, und er gibt null statt undefined zurück.

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string		Der gesuchte Wert, der mit dem Attribut `name` oder `id` eines Steuerelements verglichen wird. Groß- und Kleinschreibung spielen dabei eine Rolle. Andere Werte werden in einen String umgewandelt.

Rückgabewert

Typ

RadioNodeList | Element | null

Beschreibung

Ein einzelnes Element, wenn genau ein Steuerelement passt, eine RadioNodeList, wenn mehrere passen, oder null, wenn keines passt.

Beispiele

Einzelnes Eingabefeld über den Namen holen

// HTML: <form id="login"><input name="email" value="a@b.de"><input id="pw" type="password"></form>
const form = document.getElementById('login');
const email = form.elements.namedItem('email');
const pw = form.elements.namedItem('pw'); // Treffer über die id

console.log(email.value);
console.log(pw.type);
console.log(form.elements.namedItem('gibtsnicht'));

a@b.de password null

Radiogruppe als RadioNodeList auswerten

// HTML:
// <form id="umfrage">
//   <input type="radio" name="farbe" value="rot">
//   <input type="radio" name="farbe" value="blau" checked>
// </form>
const form = document.getElementById('umfrage');
const farbe = form.elements.namedItem('farbe');

console.log(farbe instanceof RadioNodeList);
console.log(farbe.value);

// Auswahl per Code ändern
farbe.value = 'rot';
console.log(farbe[0].checked);

true blau true

Robuster Helfer, der beide Rückgabearten behandelt

const getFieldValue = (form, name) => {
  const field = form.elements.namedItem(name);
  if (field === null) return undefined;
  // RadioNodeList oder einzelnes Element – beide besitzen .value
  return field.value;
};

const form = document.querySelector('form');
form.addEventListener('submit', (event) => {
  event.preventDefault();
  console.log('E-Mail:', getFieldValue(form, 'email'));
  console.log('Farbe:', getFieldValue(form, 'farbe'));
});

E-Mail: a@b.de Farbe: blau

// Wichtig · Fallstricke

Uneinheitliche Rückgabe: Je nachdem, wie viele Elemente passen, erhalten Sie ein Element oder eine RadioNodeList. Kommt später ein zweites Feld mit demselben Namen hinzu, etwa eine zusätzliche Checkbox, ändert sich der Typ des Rückgabewerts. Code, der z. B. .checked direkt auf dem Ergebnis abfragt, funktioniert dann nicht mehr. Prüfen Sie den Typ im Zweifel mit instanceof RadioNodeList.
Eine RadioNodeList entsteht bei jeder Mehrfach-Übereinstimmung, nicht nur bei Radiobuttons. Ihre Eigenschaft value bezieht sich aber ausschließlich auf ausgewählte Radiobuttons. Bei Checkboxen ergibt sie daher einen leeren String.
<input type=\"image\"> ist nicht Teil von form.elements und wird deshalb nie gefunden.
Elemente außerhalb des Formulars, die über das Attribut form=\"id\" zugeordnet sind, gehören zur Sammlung und werden gefunden.
Die Kurzform form.elements.length liefert immer die Eigenschaft der Sammlung, auch wenn ein Feld name=\"length\" heißt. namedItem('length') findet dagegen zuverlässig das Feld.
Die Methode wird von allen aktuellen Browsern unterstützt. Die Rückgabe einer RadioNodeList gibt es in allen modernen Browsern. Nur sehr alte Browser wie Internet Explorer lieferten eine gewöhnliche NodeList oder HTMLCollection ohne value.

Siehe auch

HTMLCollection.namedItem() HTMLAllCollection.namedItem() HTMLOptionsCollection.add() HTMLOptionsCollection.remove() HTMLAllCollection.item()