Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

CKTIS / JavaScript

Element.querySelector() e Element.querySelectorAll()

Cerca i discendenti di un elemento con i selettori CSS e scegli tra la prima corrispondenza e un elenco statico di tutte le corrispondenze.

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

Sintassi

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

querySelector() e querySelectorAll() sono metodi di istanza di Element. Ciascuno accetta una stringa contenente un selettore CSS o un elenco di selettori CSS separati da virgole. querySelector() restituisce il primo elemento corrispondente nell’ordine del documento, oppure null. querySelectorAll() restituisce una NodeList statica di tutti gli elementi corrispondenti nello stesso ordine: i genitori prima dei discendenti e i fratelli precedenti prima di quelli successivi. L’ordine dei selettori non stabilisce alcuna priorità e ogni elemento compare al massimo una volta. Se non ci sono corrispondenze, l’elenco è vuoto (length === 0).

Il risultato può includere solo i discendenti dell’elemento su cui chiami il metodo, mai l’elemento stesso. Una corrispondenza può comunque dipendere da antenati esterni a quel sottoalbero. :scope indica l’elemento su cui chiami il metodo, quindi :scope > .item seleziona solo i suoi figli diretti con la classe item. Le ricerche non attraversano i confini dello shadow DOM; per cercare al suo interno, chiama il metodo su uno ShadowRoot accessibile.

Un elenco statico mantiene le voci e il loro ordine al momento della chiamata. Modificare una classe, aggiungere, rimuovere o spostare un elemento non aggiorna l’elenco. Le voci fanno ancora riferimento agli oggetti Element originali, non a copie. Ripeti la ricerca per ottenere un risultato aggiornato; usa Array.from(list) se ti servono i metodi degli array.

Se la stringa del selettore non è valida, entrambi i metodi sollevano una DOMException chiamata SyntaxError. Non equivale a non trovare corrispondenze. Gli pseudo-elementi CSS come ::before non vengono restituiti come elementi del DOM. Per inserire un ID dinamico in un selettore, usa "#" + CSS.escape(id): l’escape riguarda l’identificatore CSS, non l’intero selettore né l’HTML. Questi metodi appartengono al DOM della piattaforma web, non a ECMAScript 2024. Controlla il supporto per il DOM e per i selettori nell’ambiente di destinazione.

Esempi

<!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>

Risultato

A
2
1
2 1

Salva l’esempio come file HTML, aprilo in un browser e controlla il risultato nella console del browser. `:scope > .item` trova solo `A`, mentre `.frame .item` trova entrambi i paragrafi grazie a un antenato esterno a `root`. Dopo aver rimosso `B`, l’elenco salvato contiene ancora due voci, ma la nuova ricerca ne restituisce una.

Lezioni correlate

  • JavaScript · Lezione 30 · Avanzato · Versione: 4

Fonti