HTMLFormElement : propriété elements
Baseline
Widely available
Cette fonctionnalité est bien établie et fonctionne sur de nombreux appareils et versions de navigateurs. Elle est disponible sur tous les navigateurs depuis juillet 2015.
La propriété elements de l'interface HTMLFormElement retourne un objet HTMLFormControlsCollection listant tous les contrôles de formulaire associés à l'élément HTML <form>.
Vous pouvez accéder à un contrôle particulier dans la collection retournée en utilisant soit un index, soit les attributs name ou id de l'élément.
Avant HTML5, l'objet retourné était un HTMLCollection, sur lequel s'appuie HTMLFormControlsCollection.
De manière indépendante, vous pouvez obtenir uniquement le nombre de contrôles associés en utilisant la propriété length. Vous pouvez obtenir la liste de tous les formulaires contenus dans un document donné en utilisant la propriété forms du document.
Valeur
Un HTMLFormControlsCollection contenant tous les contrôles non-image associés au formulaire ; si des contrôles sont associés ou dissociés du formulaire, cette collection se mettra à jour pour refléter le changement.
Les contrôles du formulaire dans la collection retournée sont dans le même ordre dans lequel ils apparaissent dans le document en suivant un parcours pré-ordonné, un parcours en profondeur de l'arbre. Cela s'appelle l'ordre de l'arbre.
Seuls les contrôles suivants sont retournés :
<button><fieldset><input>(à l'exception de ceux dont letypeest"image", qui sont omis pour des raisons historiques)<object><output><select><textarea>- éléments personnalisés associés aux formulaires (angl.)
Exemples
Utilisation basique de la syntaxe
Dans cet exemple, on voit comment obtenir la liste des contrôles du formulaire ainsi que la manière d'accéder à ses membres par indice et par nom ou identifiant.
<form id="my-form">
<label>
Nom d'utilisateur :
<input type="text" name="username" />
</label>
<label>
Nom complet :
<input type="text" name="full-name" />
</label>
<label>
Mot de passe :
<input type="password" name="password" />
</label>
</form>
const inputs = document.getElementById("my-form").elements;
const inputByIndex = inputs[0];
const inputByName = inputs["username"];
Contrôles de formulaire associés
Cet exemple montre comment l'objet HTMLFormControlsCollection contient les contrôles de formulaire associés au formulaire, plutôt que les contrôles imbriqués physiquement dans le <form>.
Le premier formulaire est complet, avec quatre contrôles de formulaire : un <fieldset> et trois <input>. Les éléments <legend> et <label> ne sont pas des contrôles listés. Le second formulaire est clairsemé, avec un seul contrôle imbriqué : un seul élément <object>. Tous les contrôles du formulaire complet sont associés au formulaire clairsemé via leur attribut form.
<form id="fullForm">
Ce formulaire semble complet, mais il n'a aucun contrôle de formulaire associé
<fieldset form="sparseForm">
<legend>Ceci est une légende</legend>
<label>Un contrôle de formulaire : <input form="sparseForm" /></label>
<label
>Un autre contrôle de formulaire : <input form="sparseForm"
/></label>
<label
>Encore un contrôle de formulaire : <input form="sparseForm"
/></label>
</fieldset>
</form>
<form id="sparseForm">
<object data="lone-form-control.jpg">Contrôle de formulaire isolé</object>
</form>
On utilise la propriété elements pour obtenir le HTMLFormControlsCollection de chaque formulaire.
const sparse = document.getElementById("sparseForm").elements;
const full = document.getElementById("fullForm").elements;
La collection inclut les contrôles de formulaire associés à l'élément de formulaire, c'est‑à‑dire tous les <button>, <fieldset>, <input>, <object>, <output>, <select>, <textarea> et éléments personnalisés associés aux formulaires, même si ces éléments sont imbriqués dans un autre formulaire ou non imbriqués dans un formulaire.
console.log(`formulaire clairsemé : ${sparse.length}`); // formulaire clairsemé : 5
console.log(`formulaire complet : ${full.length}`); // formulaire complet : 0
Les contrôles de la collection sont dans le même ordre que lorsqu'ils apparaissent dans le document.
console.log(`premier membre : ${sparse[0].tagName}`); // premier membre : FIELDSET
console.log(`dernier membre : ${sparse[sparse.length - 1].tagName}`); // dernier membre : OBJECT
Accéder aux contrôles du formulaire
Cet exemple obtient la liste des éléments du formulaire, puis parcourt la liste à la recherche d'éléments <input> de type "text" afin d'effectuer un certain traitement sur eux.
const inputs = document.getElementById("my-form").elements;
// Parcourt les contrôles du formulaire
for (const input of inputs) {
if (input.nodeName === "INPUT" && input.type === "text") {
// Met à jour la valeur du champ texte
input.value = input.value.toLocaleUpperCase();
}
}
Désactiver des contrôles de formulaire
const inputs = document.getElementById("my-form").elements;
// Parcourt les contrôles du formulaire
for (const input of inputs) {
// Désactive tous les contrôles du formulaire
input.setAttribute("disabled", "");
}
Spécifications
| Specification |
|---|
| HTML # dom-form-elements-dev |