HTMLFormControlsCollection — Schnittstelle · JavaScript-Referenz

Signatur

interface HTMLFormControlsCollection extends HTMLCollection

Beschreibung

HTMLFormControlsCollection ist die Sammlung, die du über form.elements bekommst. Sie enthält alle auflistbaren Steuerelemente eines Formulars: <button>, <fieldset>, <input> (mit Ausnahme von type="image"), <object>, <output>, <select>, <textarea> sowie formularzugehörige Custom Elements. Dazu zählen auch Elemente außerhalb des <form>, die über das Attribut form="id" mit dem Formular verknüpft sind.

Das Interface erbt von HTMLCollection, hat also length und item(index). Es überschreibt aber namedItem(name): Haben mehrere Steuerelemente denselben name oder dieselbe id (typisch bei Radiobuttons), bekommst du eine RadioNodeList statt eines einzelnen Elements zurück. Über RadioNodeList.value liest du dann ganz einfach den ausgewählten Radiowert aus.

Die Sammlung ist live: Fügst du dem Formular Felder hinzu oder entfernst welche, ändert sich die Sammlung sofort. Die Reihenfolge entspricht der Dokumentreihenfolge. Neben namedItem() gehen auch die Kurzschreibweisen elements.email und elements["email"]. Das ist nützlich, wenn du in Submit-Handlern gezielt auf einzelne Felder zugreifen willst, ohne querySelector zu verwenden.

Parameter

Name	Typ	Default	Beschreibung
$index	number		Für `item(index)` bzw. `elements[index]`: nullbasierte Position des Steuerelements in Dokumentreihenfolge.
$name	string		Für `namedItem(name)` bzw. `elements[name]`: Wert des `name`- oder `id`-Attributs des gesuchten Steuerelements.

Rückgabewert

Typ

HTMLFormControlsCollection

Beschreibung

Wird von HTMLFormElement.elements geliefert. namedItem() gibt ein Element, eine RadioNodeList (bei mehreren Treffern) oder null zurück. item() gibt ein Element oder null zurück.

Beispiele

Sammlung erhalten und Felder per Name auslesen

// <form id="login"><input name="user" value="anna"><input name="pass" type="password" value="geheim"><button>Los</button></form>
const form = document.getElementById('login');
const controls = form.elements; // HTMLFormControlsCollection

console.log(controls.length);
console.log(controls.user.value);
console.log(controls.namedItem('pass').type);
console.log(controls.item(2).tagName);

3 anna password BUTTON

Radiogruppe über RadioNodeList auswerten

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

console.log(gruppe instanceof RadioNodeList);
console.log(gruppe.value); // Wert des ausgewählten Radiobuttons

gruppe.value = 'rot'; // wählt den Radiobutton mit value="rot" aus
console.log(elements[0].checked);

true blau true

Alle Felder beim Absenden prüfen und sperren

const form = document.querySelector('form');

form.addEventListener('submit', async (event) => {
  event.preventDefault();
  // Sammlung ist nicht direkt ein Array -> in Array umwandeln
  const felder = Array.from(form.elements).filter((el) => el.name);

  const leer = felder.filter((el) => 'value' in el && el.value.trim() === '');
  if (leer.length) {
    console.warn('Leere Felder:', leer.map((el) => el.name));
    leer[0].focus();
    return;
  }

  felder.forEach((el) => (el.disabled = true));
  try {
    await fetch(form.action, { method: 'POST', body: new FormData(form) });
  } finally {
    felder.forEach((el) => (el.disabled = false));
  }
});

// Wichtig · Fallstricke

Live-Sammlung: Entfernst du beim Durchlaufen mit einer Index-Schleife Elemente, verschieben sich die Indizes. Mach vorher mit Array.from() oder [...form.elements] eine Kopie.
Kein Array: Methoden wie map und filter gibt es nicht. for...of funktioniert aber, weil die Sammlung iterierbar ist.
Nicht enthalten: <input type="image"> sowie <label>, <option> und <legend>. <fieldset> ist enthalten, obwohl es keinen Wert hat.
Namenskonflikte: Heißt ein Feld z. B. length oder item, gewinnt beim Punktzugriff die eingebaute Eigenschaft. Verwende in dem Fall namedItem(). Ähnliche Konflikte gibt es direkt auf dem <form>-Element, etwa bei Feldern namens submit oder action.
Rückgabetyp prüfen: namedItem() kann je nach Anzahl der Treffer ein Element oder eine RadioNodeList liefern. Prüf das bei dynamischen Formularen mit instanceof.
Kompatibilität: Wird von allen modernen Browsern unterstützt. RadioNodeList.value fehlt in sehr alten Browsern wie dem Internet Explorer.

Siehe auch

HTMLOptionsCollection HTMLAllCollection HTMLCollection AbortController HTMLFontElement