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éthode querySelectorAll() de Element retourne une NodeList 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 exception SyntaxError 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 attribut class ou id n'est pas un identifiant CSS valide, vous devez l'échapper avant de l'utiliser dans un sélecteur, soit en appelant CSS.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

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 DOMException: Signale que la syntaxe des chaînes de selectors définies n'est pas valide.

Exemples

Obtenir une liste de correspondances

Pour obtenir une NodeList (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 valeur note ou alert :

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 un sé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 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 :

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 un id qui n'est pas un identifiant CSS valide, il faut échapper la valeur de l'attribut avant de l'utiliser dans querySelectorAll().

HTML

Dans le code ci‑dessous, un élément <div> a pour id 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 id="this?element"></div>

<button id="no-escape">Aucun échappement</button>
<button id="css-escape">CSS.escape()</button>
<button id="manual-escape">Échappement manuel</button>

<pre id="log"></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 utilisant CSS.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");
});