HOWTO · JavaScript
Obtenir un élément par nom en JavaScript
Apprenez à obtenir un élément par son nom en JavaScript.
Sur cette page
Pour sélectionner chaque élément dont l’attribut HTML name correspond à une valeur, utilisez document.getElementsByName() ou document.querySelectorAll() avec un sélecteur d’attribut CSS. La première méthode est conçue pour rechercher les attributs name correspondants ; la seconde est utile lorsque la sélection doit aussi respecter d’autres conditions CSS. Les deux renvoient un NodeList : vérifiez sa longueur avant d’utiliser le premier élément et parcourez-le lorsque vous avez besoin de toutes les correspondances.
Obtenir des éléments par nom avec getElementsByName()
document.getElementsByName(name) recherche dans le document les éléments dont l’attribut name est égal à la chaîne fournie. La méthode renvoie un NodeList, même lorsqu’aucun élément ne correspond ; dans ce cas, sa longueur vaut 0, et non null. Cette collection est dynamique : son contenu peut refléter les changements ultérieurs apportés aux éléments correspondants du document.
Par exemple, ce code HTML contient deux champs portant le même nom :
Le code et les libellés ou sorties affichés dans cette section restent en anglais.
<label><input type="checkbox" name="interest" value="music" checked> Music</label>
<label><input type="checkbox" name="interest" value="reading"> Reading</label>
Voici un exemple JavaScript autonome qui montre comment traiter le résultat. Le petit substitut de document permet d’exécuter l’exemple hors d’un navigateur ; sur une page, utilisez l’objet document intégré avec le même appel de méthode. Le code et les libellés ou sorties affichés dans les exemples restent en anglais, car les blocs sont conservés à l’identique.
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
La première valeur est lue dans le premier champ correspondant, qu’il soit coché ou non ; la boucle affiche uniquement les valeurs des champs cochés. Dans un navigateur, document.getElementsByName("interest") renvoie les éléments correspondants, et la même vérification de longueur et la même méthode de parcours s’appliquent. Cette méthode est pratique lorsque l’attribut name suffit à définir la sélection.
Sélectionner des éléments par nom avec querySelectorAll()
document.querySelectorAll(selectors) accepte un sélecteur CSS et renvoie un NodeList statique contenant tous les éléments correspondants. Pour sélectionner des éléments par nom, utilisez un sélecteur d’attribut tel que input[name="interest"] : la condition sur la balise limite le résultat aux éléments input, tandis que celle sur l’attribut correspond au nom indiqué. Au besoin, un sélecteur peut combiner d’autres conditions CSS ou plusieurs options séparées par des virgules.
Dans un navigateur, sélectionnez tous les champs correspondants avec document.querySelectorAll('input[name="interest"]'), puis traitez le NodeList obtenu en vérifiant sa longueur ou en le parcourant. Utilisez [name="interest"] seul pour rechercher ce nom sur n’importe quel élément ; ajoutez input devant pour exclure les champs d’autres types. Dans un sélecteur, les guillemets délimitent la valeur d’un attribut ; ils n’échappent ni les guillemets ni les barres obliques inverses qu’elle pourrait contenir. N’insérez pas directement des valeurs dynamiques arbitraires dans ce sélecteur. Si vous construisez un sélecteur à partir d’une valeur, échappez-la correctement pour le contexte d’une chaîne CSS. Si la valeur provient d’une saisie et que vous ne disposez pas déjà d’une fonction d’échappement adaptée, évitez de construire un sélecteur : appelez document.getElementsByName(value), puis filtrez en JavaScript les éléments obtenus selon leur balise ou d’autres propriétés.
L’exemple d’exécution ci-dessous représente les deux champs présentés plus haut, car il ne dispose pas d’un DOM de navigateur. Sur une page, utilisez le même appel de sélecteur avec l’objet document intégré. Exécutez cet exemple ; son code et sa sortie restent en anglais, conformément à la conservation à l’identique des blocs :
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
Cette sélection trouve les deux champs selon leur balise et leur nom, indique leur nombre et affiche leurs valeurs. La vérification de longueur permet aussi d’accéder au premier élément sans risque lorsqu’aucun champ ne correspond.
Cette méthode renvoie un NodeList statique. Si le sélecteur ne trouve aucun élément, la collection est vide. Le sélecteur doit respecter la syntaxe CSS ; un sélecteur mal formé provoque une SyntaxError. Consultez la documentation de querySelectorAll() pour en savoir plus sur les sélecteurs.
Traiter et comparer les résultats
Les deux méthodes renvoient des collections, et non un élément unique ou null. Vérifiez length avant de lire le premier élément et parcourez la collection lorsque plusieurs correspondances vous intéressent. querySelectorAll() renvoie un instantané statique : les changements ultérieurs du document ne mettent pas cette collection à jour. getElementsByName() renvoie une collection dynamique, qui peut évoluer avec le document.
Choisissez getElementsByName() lorsque l’attribut name constitue à lui seul le critère de sélection. Choisissez querySelectorAll() lorsqu’un sélecteur CSS décrit plus clairement la sélection, par exemple pour limiter la recherche aux champs input ou ajouter une condition sur un autre attribut. Si vous n’avez besoin que d’un seul élément correspondant, querySelector() renvoie la première correspondance ou null ; cette méthode ne renvoie pas de collection. Pour en savoir plus sur la syntaxe et le comportement des sélecteurs, consultez la documentation de querySelectorAll().