Document.querySelectorAll()

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

La méthode querySelectorAll() de Element renvoie une NodeList statique représentant une liste des éléments du document qui correspondent au groupe de sélecteurs spécifiés.

Note : Cette méthode est implémentée à partir de ParentNode, méthode du mixin querySelectorAll() .

Syntaxe

js
elementList = parentNode.querySelectorAll(selectors);

Paramètres

selecteurs

une DOMString (chaîne de caractères) qui contient un ou plusieurs sélecteurs CSS ; s'il n'y en a pas, une exception SyntaxError est lancée. Voir localisation des éléments DOM avec les sélecteurs pour plus d'informations sur l'utilisation des sélecteurs en vue d'identifier les éléments. Plusieurs sélecteurs peuvent être spécifiés, séparés par une virgule.

Note : Les caractères qui ne font pas partie de la syntaxe CSS standard doivent être échappés à l'aide d'une barre oblique inverse. Puisque JavaScript utilise également l'échappement en retour arrière, un soin particulier doit être pris lors de l'écriture de littéraux de chaîne utilisant ces caractères. Voir Échapper des caractères spéciaux pour plus d'informations.

Valeur renvoyée

Une NodeList statique contenant un objet Element pour chaque élément qui correspond à au-moins un des sélecteurs spécifiés ou une NodeList vide si aucune correspondance n'est trouvée .

Note : Si les selectors spécifiés contiennent un pseudo-element CSS, la liste retournée sera toujours vide.

Exceptions

SyntaxError

la syntaxe des chaînes selectors spécifiés n'est pas valide.

Exemples

Pour obtenir une NodeList (liste de noeuds) de tous les éléments <p> dans le document :

js
const matches = document.querySelectorAll("p");

Cet exemple renvoie la liste de tous les éléments div du document dont l'attribut de classe a pour valeur "note" ou "alert" :

js
const matches = document.querySelectorAll("div.note, div.alert");

Ici, nous obtenons une liste des éléments <p> dont l'élément parent immédiat est un div avec la classe "highlighted" et qui sont situés dans un conteneur dont l'identifiant est "test".

js
const container = document.querySelector("#test");
const matches = container.querySelectorAll("div.highlighted > p");

Cet exemple utilise un sélecteur d'attribut pour renvoyer une liste d'éléments iframe dans le document qui contient un attribut nommé "data-src" :

js
const matches = document.querySelectorAll("iframe[data-src]");

Ici, un sélecteur d'attribut est utilisé pour renvoyer une liste d'éléments de liste contenus dans une liste dont l'identifiant est "userlist" lequel a un attribut "data-active" dont la valeur est "1":

js
const container = document.querySelector("#userlist");
const matches = container.querySelectorAll("li[data-active='1']");

Accès aux correspondances

Une fois que la NodeList des éléments correspondants est renvoyée, vous pouvez l'examiner comme un tableau (array). Si le tableau est vide (c'est quand sa propriété length est 0), alors aucune correspondance n'a été trouvée.

Sinon, vous pouvez simplement utiliser la notation de tableau standard pour accéder au contenu de la liste. Vous pouvez utiliser n'importe quelle instruction de boucle commune, telle que :

js
const highlightedItems = userList.querySelectorAll(".highlighted");

highlightedItems.forEach(function (userItem) {
  deleteUser(userItem);
});

Notes d'utilisation

querySelectorAll() se comporte différemment des bibliothèques DOM JavaScript les plus courantes, ce qui peut entraîner des résultats inattendus.

HTML

Considérez ce HTML, avec ses trois blocs <div> imbriqués.

html
<div class="outer">
  <div class="select">
    <div class="inner"></div>
  </div>
</div>

JavaScript

js
const select = document.querySelector(".select");
const inner = select.querySelectorAll(".outer .inner");
inner.length; // 1, not 0!

Dans cet exemple, lors de la sélection de ".outer .inner" dans le contexte, le <div> avec la classe "select", l'élément avec la classe ".inner" est toujours trouvé, même si .outer n'est pas un descendant de l'élément de base sur lequel la recherche (".select") est effectuée. Par défaut, querySelectorAll() vérifie uniquement que le dernier élément du sélecteur se trouve dans la portée de la recherche.

La pseudo-classe :scope restaure le comportement attendu, ne faisant correspondre les sélecteurs que sur les descendants de l'élément de base :

js
const select = document.querySelector(".select");
const inner = select.querySelectorAll(":scope .outer .inner");
inner.length; // 0

Spécifications

Specification
DOM Standard
# ref-for-dom-parentnode-queryselectorall①

Compatibilité des navigateurs

BCD tables only load in the browser

Voir aussi