Element : méthode querySelectorAll()

La méthode querySelectorAll() de Element retourne une NodeList statique (non-dynamique) des éléments correspondants au groupe de sélecteurs CSS spécifiés qui sont des descendants de l'élément sur lequel la méthode a été appelée.

Syntaxe

querySelectorAll(selectors)

Paramètres

selectors

Une chaîne de caractères contenant un ou plusieurs sélecteurs à comparer. Cette chaîne doit être composée de sélecteurs CSS valides ; sinon une exception SyntaxError est levé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.

Les sélecteurs sont appliqués à l'ensemble du document, et non uniquement à l'élément sur lequel querySelectorAll() est appelé. Pour restreindre le sélecteur à l'élément sur lequel querySelectorAll() est appelé, incluez la pseudo-classe :scope au début du sélecteur. Voir l'exemple Portée du sélecteur.

Valeur de retour

Une NodeList statique contenant un objet Element pour chaque nœud descendant qui correspond à au moins un des sélecteurs spécifiés au moment où la méthode est appelée.

Exception

SyntaxError DOMException

La syntaxe de la chaîne de selectors définie est invalide.

Exemples

Obtenir tous les éléments avec une valeur de donnée personnalisée

Cet exemple utilise le sélecteur d'attribut pour sélectionner plusieurs éléments ayant un attribut de donnée data-name qui contient « funnel-chart-percent ».

<section class="box" id="sect1">
 <div data-name="funnel-chart-percent1">10.900%</div>
 <div data-name="funnel-chart-percent2">3700.00%</div>
 <div data-name="funnel-chart-percent3">0.00%</div>
</section>

const refs = [
 ...document.querySelectorAll(`[data-name*="funnel-chart-percent"]`),
];

Obtenir d'une liste de correspondances

Pour obtenir une NodeList de tous les éléments <p> contenus dans l'élément myBox :

const matches = myBox.querySelectorAll("p");

Cet exemple renvoie une liste de tous les éléments <div> dans myBox avec une classe note ou alert :

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

Ici, nous obtenons une liste d'éléments <p> du document, dont le parent immédiat est un <div> qui a la classe highlighted et qui sont inclus dans un conteneur dont l'id 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> du document lesquels contiennent un attribut nommé data-src :

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

Ici, un sélecteur d'attribut est utilisé pour renvoyer une liste des éléments de la liste contenus dans une liste dont l'id est userlist et qui ont un attribut data-active dont la valeur est 1 :

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

Accéder aux correspondances

Une fois que la NodeList des éléments correspondants est retournée, vous pouvez l'examiner pour n'importe quel tableau (array). Si le tableau est vide (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((userItem) => {
 deleteUser(userItem);
});

Portée du sélecteur

La méthode querySelectorAll() applique ses sélecteurs à l'ensemble du document : ils ne sont pas limités à l'élément sur lequel la méthode est appelée. Pour restreindre la portée des sélecteurs, incluez la pseudo-classe :scope au début de la chaîne de sélecteurs.

HTML

Dans cet exemple, le HTML contient :

• deux boutons : #select et #select-scope
• trois éléments <div> imbriqués : #outer, #subject et #inner
• un élément <pre> utilisé pour l'affichage du résultat.

<button id="select">Sélectionner</button>
<button id="select-scope">Sélectionner avec :scope</button>
<div id="outer">
 #outer
 <div id="subject">
 #subject
 <div id="inner">#inner</div>
 </div>
</div>
<pre id="output"></pre>

div {
 margin: 0.5rem;
 padding: 0.5rem;
 border: 3px lightseagreen solid;
 border-radius: 5px;
 font-family: monospace;
}
pre,
button {
 margin: 0.5rem;
 padding: 0.5rem;
}

JavaScript

Dans le JavaScript, nous sélectionnons d'abord l'élément #subject.

Quand le bouton #select est pressé, nous appelons querySelectorAll() sur #subject en passant "#outer #inner" comme chaîne de sélecteur.

Quand le bouton #select-scope est pressé, nous appelons à nouveau querySelectorAll() sur #subject, mais cette fois en passant ":scope #outer #inner" comme chaîne de sélecteur.

const subject = document.querySelector("#subject");
const select = document.querySelector("#select");
select.addEventListener("click", () => {
 const selected = subject.querySelectorAll("#outer #inner");
 output.textContent = `Selection count: ${selected.length}`;
});
const selectScope = document.querySelector("#select-scope");
selectScope.addEventListener("click", () => {
 const selected = subject.querySelectorAll(":scope #outer #inner");
 output.textContent = `Selection count: ${selected.length}`;
});

Result

Quand on clique sur « Sélectionner », le sélecteur sélectionne tous les éléments ayant un identifiant inner qui ont aussi un ancêtre avec l'identifiant outer. Notez que même si #outer est en dehors de l'élément #subject, il est tout de même utilisé dans la sélection, donc notre élément #inner est trouvé.

Quand on clique sur « Sélectionner avec :scope », la pseudo-classe :scope limite la portée du sélecteur à #subject, donc #outer n'est pas utilisé dans la correspondance du sélecteur et l'élément #inner n'est pas trouvé.

É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 suivant, un élément <div> a un id de "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.

<div id="container">
 <div id="this?element"></div>
</div>
<button id="no-escape">Pas d'échappement</button>
<button id="css-escape">CSS.escape()</button>
<button id="manual-escape">Échappement manuel</button>
<pre id="log"></pre>

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 ? à l'aide d'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 container = document.querySelector("#container");
const log = document.querySelector("#log");
function random(number) {
 return Math.floor(Math.random() * number);
}
function setBackgroundColor(id) {
 log.textContent = "";
 try {
 const elements = container.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");
});

Résultat

Cliquer sur le premier bouton génère une erreur, tandis que les deuxième et troisième boutons fonctionnent correctement.

Spécifications

Compatibilité des navigateurs

Voir aussi

• Sélection et parcours de l'arbre DOM
• Le guide des Sélecteurs d'attribut CSS
• Apprendre : Sélecteurs d'attribut CSS
• La méthode querySelector() de l'interface Element
• Les méthodes querySelector() et querySelectorAll() de l'interface Document
• Les méthodes querySelector() et querySelectorAll() de l'interface DocumentFragment