Document.querySelector()

Il metodo Document querySelector() ritorna il primo Element all'interno del documento che corrisponde al selettore specificato o al gruppo di selettori. Se non vengono trovate corrispondenze, viene restituito null.

Note: Il matching viene eseguito utilizzando il deep-pre-order traversal dei nodi del documento partendo dal primo elemento nel markup del documento e iterando attraverso i nodi sequenziali per ordine del numero di nodi figli.

Sintassi

element = document.querySelector(selectors);

Parametri

selectors
Una DOMString contenente uno o più selettori da trovare. Questa stringa deve essere una stringa di selettore CSS valida; se non lo è, viene generata un'eccezione SYNTAX_ERR. Vedi Individuazione degli elementi DOM mediante selettori per ulteriori informazioni sui selettori e su come gestirli.

Note: I caratteri che non fanno parte della sintassi CSS standard devono essere sottoposti a escape utilizzando un carattere backslash. Poiché JavaScript utilizza anche l'escape di backslash, prestare particolare attenzione quando si scrivono stringhe letterali utilizzando questi caratteri. Vedi Escaping special characters per maggiori informazioni.

Valore di ritorno

Un oggetto Element che rappresenta il primo elemento nel documento che corrisponde al set specificato di CSS selectors, o null viene restituito se non ci sono corrispondenze.

Se hai bisogno di un elenco di tutti gli elementi che corrispondono ai selettori specificati, dovresti usare querySelectorAll().

Eccezioni

SYNTAX_ERR
La sintassi dei selettori specificati non è valida.

Note di utilizzo

Se il selettore specificato corrisponde a un ID erroneamente utilizzato più di una volta nel documento, viene restituito il primo elemento con quell'ID.

Gli pseudo-elementi CSS non restituiranno mai alcun elemento, come specificato nelle API dei selettori.

Escaping caratteri speciali

Per eseguire la corrispondenza con un ID o selettori che non seguono la sintassi CSS standard (ad esempio utilizzando due punti o uno spazio in modo inappropriato), è necessario eseguire l'escape del carattere con un backslash ("\"). Poiché il backslash è anche un carattere di escape in JavaScript, se si immette una stringa letterale, è necessario eseguire l'escape due volte (una per la stringa JavaScript e un'altra per querySelector ()):

<div id="foo\bar"></div>
<div id="foo:bar"></div>

<script>
  console.log('#foo\bar');               // "#fooar" (\b è il carattere di controllo backspace)
  document.querySelector('#foo\bar');    // Non corrisponde a nulla

  console.log('#foo\\bar');              // "#foo\bar"
  console.log('#foo\\\\bar');            // "#foo\\bar"
  document.querySelector('#foo\\\\bar'); // Seleziona il primo div

  document.querySelector('#foo:bar');    // Non corrisponde a nulla
  document.querySelector('#foo\\:bar');  // Seleziona il secondo div

Esempi

Trovare il primo elemento che corrisponde a una classe

In questo esempio, viene restituito il primo elemento del documento con la classe "myclass":

var el = document.querySelector(".myclass");

Un selettore più complesso

I selettori possono anche essere molto potenti, come dimostrato nel seguente esempio. Qui, il primo elemento <input> con il nome "login" (<input name="login"/>) situato all'interno di un <div> la cui classe è "user-panel main" (<div class="user-panel main">) nel documento viene restituito:

var el = document.querySelector("div.user-panel.main input[name='login']");

Specifiche

Specifica Stato Commento
Selectors API Level 2
The definition of 'document.querySelector()' in that specification.
Obsolete
Selectors API Level 1
The definition of 'document.querySelector()' in that specification.
Obsolete Definizione iniziale

Compatibilità con i browser

BCD tables only load in the browser

Vedi anche