NodeList
Baseline
Large disponibilité
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.
Les objets NodeList sont des collections de nœuds, généralement retournés par des propriétés telles que Node.childNodes et des méthodes telles que document.querySelectorAll().
Cette interface est 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 en utilisant des types basés sur les tableaux JavaScript, rendant ainsi de nombreuses méthodes de tableau disponibles, tout en imposant en même temps des sémantiques supplémentaires sur 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 NodeList. Vous ne créez pas vous-même des objets NodeList, mais vous les obtenez à partir d'API telles que Document.querySelectorAll(), et ces API ne sont pas obsolètes. Cependant, faites attention aux différences sémantiques par rapport à un véritable tableau.
Bien que NodeList ne soit pas un tableau (Array), il est possible d'itérer dessus avec forEach(). Il peut également être converti en un véritable tableau (Array) en utilisant Array.from().
Listes de nœuds dynamiques et statiques
Bien qu'ils soient tous deux considérés comme des objets NodeList, il existe 2 types de NodeList : dynamiques et statiques.
Dans la plupart des cas, le NodeList est dynamique, ce qui signifie que les modifications dans le DOM mettent automatiquement à jour la collection.
Par exemple, Node.childNodes est dynamique :
const parent = document.getElementById("parent");
let noeudsEnfants = parent.childNodes;
console.log(noeudsEnfants.length); // suppose "2"
parent.appendChild(document.createElement("div"));
console.log(noeudsEnfants.length); // affiche "3"
Dans d'autres cas, le NodeList est statique, où toute modification dans le DOM n'affecte pas le contenu de la collection. La méthode omniprésente document.querySelectorAll() est la seule API qui retourne un NodeList statique.
Il est bon de garder cette distinction à l'esprit lorsque vous choisissez comment itérer sur les éléments du NodeList, et si vous devez mettre en cache la length de la liste.
Propriétés d'instance
NodeList.lengthLecture seule-
Le nombre de nœud dans
NodeList.
Méthodes d'instance
NodeList.item()-
Retourne un élément de la liste par son index, ou
nullsi l'index est hors limites.Une alternative à l'accès
nodeList[i](qui retourneundefinedlorsqueiest hors limites). Cela est principalement utile pour les implémentations DOM non JavaScript. NodeList.entries()-
Retourne un itérateur, permettant au code de parcourir toutes les paires clé/valeur contenues dans la collection. (Dans ce cas, les clés sont des entiers commençant à
0et les valeurs sont des nœuds.) NodeList.forEach()-
Exécute une fonction fournie une fois par élément
NodeList, en passant l'élément en tant qu'argument à la fonction. NodeList.keys()-
Retourne un itérateur, permettant au code de parcourir toutes les clés des paires clé/valeur contenues dans la collection. (Dans ce cas, les clés sont des entiers commençant à
0.) NodeList.values()-
Retourne un itérateur permettant au code de parcourir toutes les valeurs (nœuds) des paires clé/valeur contenues dans la collection.
Exemples
Il est possible de parcourir les éléments d'un NodeList en utilisant une boucle for :
for (let i = 0; i < maListeDeNoeuds.length; i++) {
let element = maListeDeNoeuds[i];
}
N'utilisez pas for...in pour énumérer les éléments dans les NodeList, car elles énumèrent également ses propriétés length et item et provoquent des erreurs si votre script suppose qu'il ne doit traiter que des objets element. De plus, for...in ne garantit pas de visiter les propriétés dans un ordre particulier.
Les boucles for...of parcourent correctement les objets NodeList :
const liste = document.querySelectorAll("input[type=checkbox]");
for (const caseACocher of liste) {
caseACocher.checked = true;
}
Les navigateurs prennent également en charge la méthode d'itérateur (forEach()) ainsi que entries(), values() et keys().
Spécifications
| Spécification |
|---|
| DOM # interface-nodelist |