HTMLCollection
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.
L'interface HTMLCollection est constituée d'une collection générique (à la manière d'un tableau similaire à arguments) d'éléments (dans l'ordre du document) et offre des méthodes et des propriétés pour sélectionner ces éléments dans la liste.
Une HTMLCollection dans le DOM HTML est « dynamique » ; elle est automatiquement mise à jour lorsque le document sous-jacent est modifié. Pour cette raison, il est conseillé d'en faire une copie (par exemple, en utilisant Array.from) pour itérer si vous ajoutez, déplacez ou supprimez des nœuds.
Cette interface est appelée HTMLCollection pour des raisons historiques (avant DOM4, les collections implémentant cette interface pouvaient uniquement êtres constituées d'élements HTML).
Cette interface était une tentative de créer une liste non modifiable (angl.) et continue d'être prise en charge uniquement pour ne pas casser le code qui l'utilise déjà. Les API modernes représentent les structures de liste à l'aide de types basés sur les tableaux JavaScript, ce qui rend de nombreuses méthodes de tableau disponibles, tout en imposant des sémantiques supplémentaires à leur utilisation (comme rendre leurs éléments en lecture seule).
Ces raisons historiques ne signifient pas que vous, en tant que développeur·euse, devez éviter HTMLCollection. Vous ne créez pas vous-même d'objets HTMLCollection, mais vous les obtenez via des API comme Document.getElementsByClassName(), et ces API ne sont pas obsolètes. Cependant, faites attention aux différences sémantiques avec un véritable tableau.
Propriétés
HTMLCollection.lengthLecture seule-
Retourne le nombre d'éléments de la collection.
Méthodes
HTMLCollection.item()-
Retourne le nœud spécifique à l'
indexbasé sur zéro donné dans la liste. Retournenullsi l'indexest hors de portée.Une alternative à l'accès par
collection[i](qui retourneundefinedsiiest hors limites). Ceci est surtout utile pour les implémentations DOM non JavaScript. HTMLCollection.namedItem()-
Retourne le nœud spécifique dont l'ID ou, à défaut, le nom correspond à la chaîne de caractères fournie par
name. La recherche par nom est faite seulement en dernier ressort, uniquement en HTML, et seulement si l'élément référencé supporte l'attributname. Retournenullsi aucun nœud n'existe pour le nom donné.Une alternative à l'accès par
collection[name](qui retourneundefinedsinamen'existe pas). Ceci est surtout utile pour les implémentations DOM non JavaScript.
Utilisation en JavaScript
HTMLCollection expose aussi directement ses membres comme propriétés, par nom et par index. Les ID HTML peuvent contenir : et . comme caractères valides, ce qui nécessite d'utiliser la notation entre crochets pour accèder aux propriétés. Actuellement, HTMLCollections ne reconnait pas purement les ID numériques, ce qui provoquerait des conflits avec l'accès de "array-style", bien qu'HTML le permette.
Par exemple, en supposant qu'il y ait un élément <form> (formulaire) dans le document et que son id soit "myForm" :
var elem1, elem2;
// document.forms est une HTMLCollection
elem1 = document.forms[0];
elem2 = document.forms.item(0);
alert(elem1 === elem2); // affiche : "true" (vrai)
elem1 = document.forms.myForm;
elem2 = document.forms.namedItem("myForm");
alert(elem1 === elem2); // affiche : "true"
elem1 = document.forms["named.item.with.periods"];
Spécifications
| Specification |
|---|
| DOM # interface-htmlcollection |
Compatibilité des navigateurs
Voir aussi
- L'interface
NodeList - Les interfaces
HTMLFormControlsCollection,HTMLOptionsCollection