Element : méthode querySelector()

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éthodequerySelector() de l'interfaceElement renvoie le premier élément descendant de l'élément sur lequel elle est invoquée qui correspond au groupe de sélecteurs défini.

Syntaxe

querySelector(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 exceptionSyntaxError 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 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

Le premier élément descendant debaseElement qui correspond au groupe deselectors « sélecteurs » défini. La hiérarchie entière des éléments est considérée lors de la mise en correspondance, y compris ceux qui sont en dehors de l'ensemble des éléments, y comprisbaseElement et ses descendants ; En d'autres termes, les sélecteurs sont d'abord appliqués au document entier, et non à l'élément de base, pour générer une liste initiale d'éléments potentiels. Les éléments résultants sont ensuite examinés pour voir s'ils sont des descendants debaseElement. La première correspondance de ces éléments restants est renvoyée par la méthodequerySelector().

Si aucune correspondance n'est trouvée, la valeur retournée estnull.

Exceptions

SyntaxError: Signale que lesselectors définis sont invalides.

Exemple

Voyons quelques exemples.

Trouver un élément spécifique avec des valeurs spécifiques d'un attribut

Dans ce premier exemple, est retourné le premier élément<style> dans le corps du document HTML qui, soit n'a pas de type, soit a le typetext/css :

const el = document.body.querySelector(  "style[type='text/css'], style:not([type])",);

Obtenir les descendants directs avec la pseudo-classe`:scope`

Cet exemple utilise la pseudo-classe:scope pour récupérer les enfants directs de l'élémentparentElement.

HTML

html

<div>  <h6>Titre de la page</h6>  <div>    <span>L'amour est bienveillant.</span>    <span>      <span>L'amour est patient.</span>    </span>    <span>      <span>L'amour est altruiste.</span>    </span>  </div></div>

CSS

css

span {  display: block;  margin-bottom: 5px;}.red span {  background-color: red;  padding: 5px;}

JavaScript

const parentElement = document.querySelector("#parent");let allChildren = parentElement.querySelectorAll(":scope > span");allChildren.forEach((item) => item.classList.add("red"));

Résultat

La hiérarchie entière compte

Cet exemple montre que la hiérarchie du document entier est prise en compte lors de l'application desselectors, de sorte que les niveaux en dehors dubaseElement défini sont toujours pris en compte lors de la recherche des correspondances.

HTML

html

<div>  <h5>Contenu original</h5>  <p>    à l'intérieur du paragraphe    <span>à l'intérieur de la balise span</span>    à l'intérieur du paragraphe  </p></div><div>  <h5>Résultat</h5>  <div></div></div>

JavaScript

const baseElement = document.querySelector("p");document.getElementById("output").textContent =  baseElement.querySelector("div span").textContent;

Résultat

Le résultat ressemble à ceci :

Remarquez que le sélecteur"div span" correspond toujours avec succès à l'élément<span>, même si les nœuds enfants debaseElement n'incluent pas l'élément<div> (il fait toujours partie du sélecteur défini).

É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 dansquerySelector().

HTML

Dans le code suivant, un élément<div> a unid 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.

html

<div>  <div></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 valeurthis?element.
Le deuxième bouton échappe la valeur en utilisantCSS.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 element = container.querySelector(`#${id}`);    const randomColor = `rgb(${random(255)} ${random(255)} ${random(255)})`;    element.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");});