L'interfaceHTMLCollection 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.

UneHTMLCollection 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 utilisantArray.from) pour itérer si vous ajoutez, déplacez ou supprimez des nœuds.

Cette interface est appeléeHTMLCollection pour des raisons historiques (avant DOM4, les collections implémentant cette interface pouvaient uniquement êtres constituées d'élements HTML).

Cette interface était unetentative 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 lestableaux 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 éviterHTMLCollection. Vous ne créez pas vous-même d'objetsHTMLCollection, mais vous les obtenez via des API commeDocument.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'index basé sur zéro donné dans la liste. Retournenull si l'index est hors de portée.

Une alternative à l'accès parcollection[i] (qui retourneundefined sii est 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 parname. 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. Retournenull si aucun nœud n'existe pour le nom donné.

Une alternative à l'accès parcollection[name] (qui retourneundefined siname n'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 sonid soit"myForm" :

var elem1, elem2;// document.forms est une HTMLCollectionelem1 = 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

Compatibilité des navigateurs

Voir aussi

• L'interfaceNodeList
• Les interfacesHTMLFormControlsCollection,HTMLOptionsCollection