Document : méthode querySelectorAll()

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.

La méthodequerySelectorAll() deElement retourne uneNodeList statique représentant une liste des éléments du document qui correspondent au groupe de sélecteurs définis.

Une chaîne de caractères qui contient un ou plusieurs sélecteurs CSS. La chaîne de caractères doit être une chaîne de sélecteurs CSS valide ; si ce n'est pas le cas, une exceptionSyntaxError est lancée.

Notez que la spécification HTML n'exige pas que les valeurs d'attribut soient des identifiants CSS valides. Si la valeur d'un attributclass ouid n'est pas un identifiant CSS valide, vous devez l'échapper avant de l'utiliser dans un sélecteur, soit en appelantCSS.escape() sur la valeur, soit en utilisant l'une des techniques décrites dansÉchapper les caractères. VoirÉchapper les valeurs d'attribut pour un exemple.

Valeur de retour

UneNodeList statique contenant un objetElement pour chaque élément qui correspond à au-moins un des sélecteurs spécifiés ou uneNodeList vide si aucune correspondance n'est trouvée.

Note :Si lesselectors spécifiés contiennent unpseudo-element CSS, la liste retournée sera toujours vide.

Exceptions

SyntaxErrorDOMException: Signale que la syntaxe des chaînes deselectors définies n'est pas valide.

Exemples

Obtenir une liste de correspondances

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

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 valeurnote oualert :

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".

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

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

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" :

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

Accès aux correspondances

Une fois que laNodeList 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 :

const highlightedItems = userList.querySelectorAll(".highlighted");highlightedItems.forEach(function (userItem) {  deleteUser(userItem);});

Échapper les valeurs d'attribut

Cet exemple montre que si un document HTML contient unid qui n'est pas unidentifiant CSS valide, il faut échapper la valeur de l'attribut avant de l'utiliser dansquerySelectorAll().

HTML

Dans le code ci‑dessous, un élément<div> a pourid la valeur"this?element", qui n'est pas un identifiant CSS valide, car le caractère"?" n'est pas autorisé dans les identifiants CSS.

Nous avons également trois boutons et un élément<pre> pour consigner les erreurs.

html

<div></div><button>Aucun échappement</button><button>CSS.escape()</button><button>Échappement manuel</button><pre></pre>

CSS

css

div {  background-color: blue;  margin: 1rem 0;  height: 100px;  width: 200px;}

JavaScript

Les trois boutons, lorsqu'on clique dessus, essaient tous de sélectionner le<div>, puis définissent sa couleur de fond sur une valeur aléatoire.

Le premier bouton utilise directement la valeur"this?element".
Le deuxième bouton échappe la valeur en utilisantCSS.escape().
Le troisième bouton échappe explicitement le caractère"?" avec une barre oblique inverse. Notez qu'il faut aussi échapper la barre oblique inverse elle‑même, en utilisant une autre barre oblique inverse, par exemple :"\\?".

const log = document.querySelector("#log");function random(number) {  return Math.floor(Math.random() * number);}function setBackgroundColor(id) {  log.textContent = "";  try {    const elements = document.querySelectorAll(`#${id}`);    const randomColor = `rgb(${random(255)} ${random(255)} ${random(255)})`;    elements[0].style.backgroundColor = randomColor;  } catch (e) {    log.textContent = e;  }}document.querySelector("#no-escape").addEventListener("click", () => {  setBackgroundColor("this?element");});document.querySelector("#css-escape").addEventListener("click", () => {  setBackgroundColor(CSS.escape("this?element"));});document.querySelector("#manual-escape").addEventListener("click", () => {  setBackgroundColor("this\\?element");});