Element : méthode getElementsByClassName()
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 octobre 2017.
La méthode getElementsByClassName() de l'interface Element retourne une collection HTMLCollection dynamique qui contient tous les éléments descendants qui ont le nom de classe ou les noms de classe définis.
La méthode getElementsByClassName() de l'interface Document fonctionne essentiellement de la même manière, sauf qu'elle agit sur l'ensemble du document, en commençant par la racine du document.
Syntaxe
getElementsByClassName(names)
Paramètres
names-
Une chaîne de caractères contenant un ou plusieurs noms de classes à rechercher, séparés par des espaces.
Valeur de retour
Une collection HTMLCollection fournissant une liste mise à jour en temps réel de tous les éléments qui sont membres de chaque classe dans names.
Notes d'utilisation
Comme toujours, la collection retournée est dynamique, ce qui signifie qu'elle reflète toujours l'état actuel de l'arbre DOM enraciné à l'élément sur lequel la fonction a été appelée. Lorsque de nouveaux éléments correspondant à names sont ajoutés au sous-arbre, ils apparaissent immédiatement dans la collection. De même, si un élément existant qui ne correspond pas à names voit son ensemble de classes modifié pour correspondre, il apparaît immédiatement dans la collection.
L'inverse est également vrai : lorsque des éléments ne correspondent plus à l'ensemble des noms, ils sont immédiatement retirés de la collection.
Note : En mode Quirks, les noms de classes sont comparés de manière insensible à la casse. Sinon, ils sont sensibles à la casse.
Exemples
Correspondance avec une seule classe
Pour rechercher des éléments qui incluent parmi leurs classes une seule classe définie, il suffit de fournir ce nom de classe lors de l'appel de getElementsByClassName() :
element.getElementsByClassName("test");
Cet exemple trouve tous les éléments qui ont une classe test, et qui sont également des descendants de l'élément ayant pour id main :
document.getElementById("main").getElementsByClassName("test");
Correspondance avec plusieurs classes
Pour rechercher des éléments dont la liste de classes inclut à la fois les classes red et test :
element.getElementsByClassName("red test");
Examiner les résultats
Vous pouvez utiliser soit la méthode item() sur la HTMLCollection retournée, soit la syntaxe standard des tableaux pour examiner les éléments individuels de la collection. Cependant, le code suivant ne fonctionne pas comme on peut s'y attendre, car "matches" change dès qu'une classe "color-box" est supprimée.
const correspondances = element.getElementsByClassName("color-box");
for (let i = 0; i < correspondances.length; i++) {
correspondances[i].classList.remove("color-box");
correspondances.item(i).classList.add("hue-frame");
}
Sinon, utilisez une autre méthode, par exemple :
const correspondances = element.getElementsByClassName("color-box");
while (correspondances.length > 0) {
correspondances.item(0).classList.add("hue-frame");
correspondances[0].classList.remove("color-box");
}
Ce code trouve les éléments descendants ayant la classe "color-box", ajoute la classe "hue-frame" en appelant item(0), puis supprime "color-box" (en utilisant la notation de tableau). Un autre élément (s'il en reste) devient alors item(0).
Filtrer les résultats en utilisant les méthodes de tableau
On peut également utiliser les méthodes Array sur n'importe quel HTMLCollection en passant le HTMLCollection comme valeur de this de la méthode. Ici, nous allons trouver tous les éléments <div> qui ont une classe test :
const elementsTest = document.getElementsByClassName("test");
const divsTest = Array.prototype.filter.call(
elementsTest,
(elementTest) => elementTest.nodeName === "DIV",
);
Spécifications
| Spécification |
|---|
| DOM # ref-for-dom-element-getelementsbyclassname |