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

CKTIS / JavaScript

Element.querySelectorAll — encontrar elementos descendentes

Element.querySelectorAll devolve um NodeList estático dos descendentes que correspondem a um seletor CSS. As alterações posteriores à árvore não atualizam a lista.

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.querySelectorAll(selectors)

Element.querySelectorAll(selectors) devolve os descendentes correspondentes, pela ordem da árvore, como um NodeList, não como um array. O próprio elemento que faz a chamada não é incluído. Se não houver correspondências, a lista fica vazia; querySelector devolve, em vez disso, o primeiro elemento ou null.

A lista é estática: as alterações à árvore não atualizam o seu conteúdo, mas os elementos que contém não são cópias. Uma nova chamada devolve os resultados atuais. Um seletor inválido lança uma DOMException com o nome SyntaxError.

Um seletor pode ter em conta antepassados fora do elemento que faz a chamada; utiliza :scope > .item para selecionar filhos diretos. Esta é uma API do DOM, não uma funcionalidade de ECMAScript; a disponibilidade de Node.js, por si só, não comprova o suporte.

Exemplos

const root = document.createElement('section');
const first = document.createElement('span');
first.className = 'item';
root.append(first);

const matches = root.querySelectorAll('.item');
const second = document.createElement('span');
second.className = 'item';
root.append(second);

console.log(matches.length);
console.log(root.querySelectorAll('.item').length);
console.log(matches[0] === first);

Resultado

1
2
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