Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

document.querySelector — o primeiro elemento correspondente

document.querySelector(selectors) procura o primeiro elemento correspondente a um seletor CSS. Devolve um elemento ou null; um seletor inválido lança uma exceção.

Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Sintaxe

document.querySelector(selectors)

document.querySelector(selectors) é um método do DOM, não faz parte do próprio ECMAScript. Aceita uma cadeia de caracteres de seletor CSS e devolve o primeiro Element correspondente, pela ordem da árvore do documento, ou null.

Verifique se o resultado é null antes de ler as respetivas propriedades. Uma sintaxe de seletor inválida lança uma DOMException com o nome SyntaxError, em vez de devolver null. Numa lista de seletores separados por vírgulas, o resultado é determinado pela ordem dos elementos na árvore, não pela ordem dos seletores.

Em contrapartida, querySelectorAll() devolve uma lista estática de todas as correspondências. O exemplo chama querySelector() no document da página atual, pelo que as correspondências dependem do código HTML dessa página.

Exemplos

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Document.querySelector</title>
</head>
<body>
  <h1>First matching element</h1>
  <ul>
    <li class="item">First</li>
    <li class="item">Second</li>
  </ul>
  <script>
    console.log(document.querySelector('.item').textContent);
    console.log(document.querySelector('.missing') === null);
    try {
      document.querySelector('[');
    } catch (error) {
      console.log(error.name);
    }
  </script>
</body>
</html>

Resultado

First
true
SyntaxError

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes