RadioNodeList — Schnittstelle · JavaScript-Referenz

Signatur

interface RadioNodeList extends NodeList

Beschreibung

RadioNodeList erbt von NodeList und fasst alle Formular-Steuerelemente eines <form> zusammen, die denselben name oder dieselbe id haben. Man bekommt sie nicht über einen Konstruktor. Sie entsteht, wenn man form.elements.namedItem(name) (oder kurz form.elements[name]) aufruft und mehr als ein Element passt. Passt genau ein Element, wird dieses Element direkt zurückgegeben und keine Liste.

Am häufigsten braucht man die Schnittstelle bei Radio-Button-Gruppen. Die Eigenschaft value liefert den value des gerade ausgewählten Radio-Buttons. Ist keiner ausgewählt, ist sie ein leerer String. Weist man value etwas zu, wird der Radio-Button mit genau diesem Wert ausgewählt. So muss man nicht selbst über die Elemente laufen und checked prüfen.

Die Liste ist live: Kommen Elemente mit dem Namen im DOM hinzu oder werden sie entfernt, ändert sich die Liste mit. Alle Methoden von NodeList stehen zur Verfügung: length, item(), forEach(), entries(), keys() und values(). Mit for…of kann man direkt über die Liste laufen.

Parameter

Name	Typ	Default	Beschreibung
$value	string	""	Eigenschaft (lesen/schreiben): Wert des ausgewählten Radio-Buttons. Beim Setzen wird der erste Radio-Button mit passendem `value` ausgewählt.
$length	number		Geerbte, schreibgeschützte Anzahl der Elemente in der Liste.
$item(index)	(index: number) => Element \| null		Geerbt: Gibt das Element an Position `index` zurück oder `null`.

Beispiele

Ausgewählten Radio-Button auslesen

// <form id="versand">
//   <input type="radio" name="art" value="standard" checked>
//   <input type="radio" name="art" value="express">
// </form>
const form = document.getElementById('versand');
const gruppe = form.elements.namedItem('art');

console.log(gruppe instanceof RadioNodeList);
console.log(gruppe.length);
console.log(gruppe.value);

true 2 standard

Auswahl per Code setzen

const gruppe = document.getElementById('versand').elements['art'];

gruppe.value = 'express';
console.log([...gruppe].find((r) => r.checked).value);

// Wert ohne passenden Radio-Button: Die Auswahl bleibt, wie sie ist
gruppe.value = 'gibt-es-nicht';
console.log(gruppe.value);

express express

Auf Änderungen reagieren und über die Liste laufen

const form = document.getElementById('versand');
const gruppe = form.elements.namedItem('art');

for (const radio of gruppe) {
  radio.addEventListener('change', () => {
    console.log(`Gewählt: ${gruppe.value}`);
  });
}

// Keine Auswahl erkennen
const istLeer = gruppe.value === '';
console.log(istLeer ? 'Bitte Versandart wählen' : 'OK');

OK

Sicher mit einem oder mehreren Elementen umgehen

const getRadioValue = (form, name) => {
  const treffer = form.elements.namedItem(name);
  if (!treffer) return null;
  // Bei genau einem Element kommt das Element selbst zurück, keine Liste
  if (treffer instanceof RadioNodeList) return treffer.value;
  return treffer.checked ? treffer.value : '';
};

console.log(getRadioValue(document.getElementById('versand'), 'art'));

standard

// Wichtig · Fallstricke

Nicht immer eine Liste: namedItem() gibt nur dann eine RadioNodeList zurück, wenn mehrere Elemente passen. Bei genau einem Treffer kommt das Element selbst zurück, bei keinem Treffer null. Prüfe den Typ, bevor du .value verwendest.
value berücksichtigt nur <input type="radio">. Checkboxen oder Textfelder mit gleichem Namen landen zwar in der Liste, ihr Wert wird von value aber ignoriert.
Hat ein ausgewählter Radio-Button kein value-Attribut, liefert value den String "on".
Die Liste ist live. Wenn du beim Durchlaufen Elemente aus dem DOM entfernst, kann sich der Index verschieben. Kopiere die Liste vorher mit [...liste].
Kompatibilität: In allen modernen Browsern verfügbar. Der Internet Explorer kennt die Schnittstelle nicht, dort muss man die checked-Eigenschaft der einzelnen Elemente selbst prüfen.

Siehe auch

HTMLFormControlsCollection HTMLFormControlsCollection.namedItem() NodeList HTMLFormElement.elements HTMLInputElement