Element nach Name in JavaScript abrufen

Um alle Elemente auszuwählen, deren HTML-Attribut name einem Wert entspricht, verwenden Sie document.getElementsByName() oder document.querySelectorAll() mit einem CSS-Attributselektor. Die erste Methode ist speziell für den Abgleich von name-Attributen vorgesehen; die zweite eignet sich, wenn die Auswahl weitere CSS-Bedingungen enthalten soll. Beide liefern eine NodeList. Prüfen Sie daher deren Länge, bevor Sie auf das erste Element zugreifen, und durchlaufen Sie sie, wenn Sie alle Treffer benötigen.

Elemente nach Name mit getElementsByName() abrufen

document.getElementsByName(name) sucht im Dokument nach Elementen, deren name-Attribut dem übergebenen String entspricht. Die Methode gibt eine NodeList zurück, auch wenn es keine Treffer gibt. In diesem Fall ist ihre Länge 0, nicht null. Die zurückgegebene Sammlung ist live: Ihr Inhalt kann sich ändern, wenn sich passende Elemente im Dokument ändern.

Das folgende HTML enthält beispielsweise zwei Steuerelemente mit demselben Namen:

Der Code und die angezeigten Bezeichnungen oder Ausgaben in diesem Abschnitt bleiben auf Englisch.

<label><input type="checkbox" name="interest" value="music" checked> Music</label>
<label><input type="checkbox" name="interest" value="reading"> Reading</label>

Hier sehen Sie ein eigenständiges JavaScript-Beispiel für den Umgang mit dem Ergebnis. Der kleine Ersatz für document macht das Beispiel auch außerhalb eines Browsers ausführbar. Auf einer Webseite verwenden Sie denselben Methodenaufruf mit dem eingebauten document-Objekt. Der Code und die darin enthaltenen Bezeichnungen und Textausgaben, darunter „No matches“, bleiben auf Englisch.

const controls = [
  { name: "interest", value: "music", checked: true },
  { name: "interest", value: "reading", checked: false },
];
const document = {
  getElementsByName(name) {
    return controls.filter((control) => control.name === name);
  },
};

const interests = document.getElementsByName("interest");
const firstInterest = interests.length > 0 ? interests[0].value : "No matches";
console.log(firstInterest);

for (const interest of interests) {
  if (interest.checked) {
    console.log(interest.value);
  }
}

music
music

Der erste Wert wird aus dem ersten passenden Steuerelement gelesen, unabhängig davon, ob es ausgewählt ist. Die Schleife gibt nur ausgewählte Werte aus. Im Browser liefert document.getElementsByName("interest") die passenden Elemente; dieselbe Längenprüfung und Schleife funktionieren dort ebenfalls. Die Methode ist praktisch, wenn allein das name-Attribut über die Auswahl entscheidet.

Elemente nach Name mit querySelectorAll() auswählen

document.querySelectorAll(selectors) akzeptiert einen CSS-Selektor und gibt eine statische NodeList mit allen passenden Elementen zurück. Um Elemente nach ihrem Namen auszuwählen, verwenden Sie einen Attributselektor wie input[name="interest"]: Die Tag-Bedingung beschränkt das Ergebnis auf Eingabeelemente, während die Attributbedingung den Namen abgleicht. Bei Bedarf kann ein Selektor weitere CSS-Bedingungen oder durch Kommas getrennte Alternativen kombinieren.

Wählen Sie im Browser alle passenden Eingabeelemente mit document.querySelectorAll('input[name="interest"]') aus und lesen Sie die resultierende NodeList anschließend mit einer Längenprüfung oder einer Schleife aus. Mit [name="interest"] allein finden Sie Elemente jeden Typs mit diesem Namen; setzen Sie input davor, wenn andere Steuerelementtypen ausgeschlossen werden sollen. In einem Selektor grenzen Anführungszeichen einen Attributwert ein; sie maskieren keine darin enthaltenen Anführungszeichen oder Backslashes. Fügen Sie beliebige dynamische Werte daher nicht ungeprüft in diesen Selektor ein. Wenn Sie einen Selektor aus einem Wert erstellen, maskieren Sie den Wert mit einer geeigneten CSS-String-Escaping-Routine für den CSS-String-Kontext. Stammt der Wert aus einer Eingabe und steht Ihnen keine solche Routine zur Verfügung, bauen Sie keinen Selektor daraus: Rufen Sie document.getElementsByName(value) auf und filtern Sie die zurückgegebenen Elemente in JavaScript nach Tag oder anderen Eigenschaften.

Das folgende Laufzeitbeispiel bildet die beiden oben gezeigten Eingabeelemente nach, da es kein Browser-DOM enthält. Auf einer Webseite verwenden Sie denselben Selektoraufruf mit dem eingebauten document-Objekt. Führen Sie dieses Beispiel aus. Der Code sowie die darin enthaltenen Bezeichnungen und Textausgaben bleiben auf Englisch; auch die angezeigten Werte „music“ und „reading“ werden unverändert ausgegeben.

const inputs = [
  { tagName: "INPUT", name: "interest", value: "music" },
  { tagName: "INPUT", name: "interest", value: "reading" },
];
const document = {
  querySelectorAll(selector) {
    if (selector !== 'input[name="interest"]') return [];
    return inputs.filter(
      (input) => input.tagName === "INPUT" && input.name === "interest",
    );
  },
};

const interests = document.querySelectorAll('input[name="interest"]');
if (interests.length === 0) {
  console.log("No matching inputs.");
} else {
  console.log(`Matches: ${interests.length}`);
  for (const input of interests) {
    console.log(input.value);
  }
}

Matches: 2
music
reading

Damit werden beide Eingabeelemente anhand von Tag und Name ausgewählt, ihre Anzahl ausgegeben und ihre Werte angezeigt. Dank der Längenprüfung ist auch der Zugriff auf das erste Element sicher, wenn kein Eingabeelement passt.

Diese Methode gibt eine statische NodeList zurück. Passt kein Element auf den Selektor, ist die Sammlung leer. Der Selektor muss gültiges CSS sein; ein fehlerhafter Selektor löst einen SyntaxError aus. Weitere Einzelheiten zu Selektoren finden Sie in der Dokumentation zu querySelectorAll().

Ergebnisse behandeln und vergleichen

Beide Methoden liefern Sammlungen statt eines einzelnen Elements oder null. Prüfen Sie length, bevor Sie auf das erste Element zugreifen, und verwenden Sie eine Schleife, wenn mehrere Treffer relevant sind. querySelectorAll() liefert eine statische Momentaufnahme: Spätere Änderungen am Dokument aktualisieren diese Sammlung nicht. getElementsByName() liefert eine Live-Sammlung, die sich mit Änderungen am Dokument verändern kann.

Verwenden Sie getElementsByName(), wenn das name-Attribut das einzige Auswahlkriterium ist. Verwenden Sie querySelectorAll(), wenn sich die Auswahl mit einem CSS-Selektor klarer ausdrücken lässt, etwa indem Sie den Namensabgleich auf Eingabeelemente beschränken oder eine weitere Attributbedingung hinzufügen. Wenn Sie nur ein passendes Element benötigen, liefert querySelector() den ersten Treffer oder null; die Methode gibt keine Sammlung zurück. Weitere Informationen zur Selektorsyntax und zum Verhalten finden Sie in der Dokumentation zu querySelectorAll().