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

CKTIS / JavaScript

Element.querySelector — primeiro descendente correspondente

Element.querySelector procura o primeiro descendente que corresponde a um seletor CSS. Devolve um elemento ou null; um seletor inválido provoca 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

element.querySelector(selectors)

Element.querySelector aceita uma cadeia selectors que contém um seletor CSS ou uma lista de seletores separados por vírgulas. Devolve o primeiro descendente correspondente pela ordem da árvore, não pela ordem da lista de seletores. O elemento no qual é chamado não é, por si só, um resultado.

Se não houver correspondências, devolve null. Verifique o resultado antes de aceder às propriedades. Uma sintaxe de seletor inválida provoca uma DOMException com o nome SyntaxError, em vez de devolver null.

Utilize :scope > .action para selecionar um filho direto. Sem :scope, a correspondência do seletor pode considerar antepassados fora do elemento que faz a chamada, embora o resultado continue a ser seu descendente. querySelectorAll() devolve uma lista estática de todas as correspondências, em vez de um único elemento.

Esta é uma API do padrão DOM, não uma funcionalidade da linguagem ECMAScript. O exemplo requer um ambiente de navegador com DOM; a presença de Node 24 num repositório não comprova o suporte desta API.

Exemplos

const root = document.createElement('section');
const first = document.createElement('button');
const second = document.createElement('button');
first.className = 'action';
second.className = 'action';
first.textContent = 'First';
second.textContent = 'Second';
root.append(first, second);

console.log(root.querySelector('.action').textContent);
console.log(root.querySelector(':scope > .action') === first);
console.log(root.querySelector('.missing') === null);

Resultado

First
true
true

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