Base de connaissancesCentre d’examen
FRFrançais
Choisir la langue13

CKTIS / JavaScript

Element.querySelector() et Element.querySelectorAll()

Recherchez les descendants d’un élément à l’aide de sélecteurs CSS et récupérez le premier résultat ou une liste statique de tous les résultats.

Version : ECMAScript 2024 and the current web platform; runtime support varies

Syntaxe

element.querySelector(selectors)     // Element | null
element.querySelectorAll(selectors)  // static NodeList of Element objects

querySelector() et querySelectorAll() sont des méthodes d’instance de Element. Chacune prend une chaîne contenant un sélecteur CSS ou une liste de sélecteurs CSS séparés par des virgules. querySelector() renvoie le premier élément correspondant dans l’ordre du document, ou null. querySelectorAll() renvoie une NodeList statique de tous les éléments correspondants dans le même ordre : les parents avant leurs descendants et les éléments frères précédents avant les suivants. L’ordre des sélecteurs ne définit aucune priorité et chaque élément apparaît au plus une fois. Sans correspondance, la liste est vide (length === 0).

Seuls les descendants de l’élément sur lequel la méthode est appelée peuvent être renvoyés, jamais cet élément lui-même. Un sélecteur peut toutefois tenir compte d’ancêtres extérieurs à ce sous-arbre. :scope désigne l’élément sur lequel la méthode est appelée : :scope > .item ne sélectionne donc que ses enfants directs de classe item. Les requêtes ne franchissent pas les limites du DOM fantôme. Pour chercher à l’intérieur, appelez la méthode sur un ShadowRoot accessible.

Une liste statique conserve ses entrées et leur ordre au moment de l’appel. La modification d’une classe, l’ajout, la suppression ou le déplacement d’un élément ne modifie pas la liste. Ses entrées désignent toujours les objets Element d’origine, et non des copies. Relancez la requête pour obtenir un résultat à jour, ou utilisez Array.from(list) pour accéder aux méthodes de tableau.

Si la chaîne du sélecteur n’est pas valide, les deux méthodes lèvent une DOMException nommée SyntaxError : ce n’est pas une absence de correspondance. Les pseudo-éléments CSS comme ::before ne sont pas renvoyés comme éléments du DOM. Pour insérer un ID dynamique dans un sélecteur, utilisez "#" + CSS.escape(id) : l’échappement concerne l’identifiant CSS, pas le sélecteur entier ni du HTML. Ces méthodes appartiennent au DOM de la plateforme web, pas à ECMAScript 2024. Vérifiez la prise en charge du DOM et des sélecteurs dans l’environnement cible.

Exemples

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Element selector queries</title>
</head>
<body>
  <script>
    const frame = document.createElement("div");
    frame.className = "frame";
    const root = frame.appendChild(document.createElement("section"));
    const direct = root.appendChild(document.createElement("p"));
    const wrapper = root.appendChild(document.createElement("div"));
    const nested = wrapper.appendChild(document.createElement("p"));
    direct.className = nested.className = "item";
    direct.textContent = "A";
    nested.textContent = "B";

    const snapshot = root.querySelectorAll(".frame .item");
    console.log(root.querySelector(":scope > .item").textContent);
    console.log(snapshot.length);
    console.log(root.querySelectorAll(":scope > .item").length);

    nested.remove();
    console.log(`${snapshot.length} ${root.querySelectorAll(".frame .item").length}`);
  </script>
</body>
</html>

Résultat

A
2
1
2 1

Enregistrez l’exemple dans un fichier HTML, ouvrez-le dans un navigateur et vérifiez le résultat dans la console du navigateur. `:scope > .item` trouve seulement `A`, tandis que `.frame .item` trouve les deux paragraphes grâce à un ancêtre situé hors de `root`. Après la suppression de `B`, la liste enregistrée contient encore deux entrées, mais la nouvelle requête n’en renvoie qu’une.

Leçons associées

  • JavaScript · Leçon 30 · Avancé · Version : 4

Sources