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

CKTIS / JavaScript

Element.querySelector() e Element.querySelectorAll()

Procura descendentes de um elemento com seletores CSS. Obtém a primeira correspondência ou uma lista estática de todas as correspondências.

Versão: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxe

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

querySelector() e querySelectorAll() são métodos de instância de Element. Cada um recebe uma cadeia de caracteres que contém um seletor CSS ou uma lista de seletores CSS separados por vírgulas. querySelector() devolve o primeiro elemento correspondente na ordem do documento, ou null. querySelectorAll() devolve uma NodeList estática com todos os elementos correspondentes na mesma ordem: os elementos-pai antes dos descendentes e os irmãos anteriores antes dos posteriores. A ordem dos seletores não define prioridades e cada elemento aparece, no máximo, uma vez. Se não houver correspondências, a lista está vazia (length === 0).

Apenas os descendentes do elemento em que chamas o método podem ser devolvidos, nunca o próprio elemento. A correspondência pode, ainda assim, depender de antepassados fora dessa subárvore. :scope refere-se ao elemento em que chamas o método, pelo que :scope > .item seleciona apenas os seus filhos diretos com a classe item. As consultas não atravessam os limites do shadow DOM. Para pesquisar no seu interior, chama o método num ShadowRoot acessível.

Uma lista estática mantém as entradas e a ordem que tinham no momento da chamada. Alterar uma classe ou adicionar, remover ou mover um elemento não atualiza a lista. As entradas continuam a referir-se aos objetos Element originais, e não a cópias. Repete a consulta para obter o resultado atual; usa Array.from(list) se precisares de métodos de arrays.

Se a cadeia do seletor for inválida, ambos os métodos lançam uma DOMException chamada SyntaxError. Não é o mesmo que não encontrar correspondências. Pseudoelementos CSS como ::before não são devolvidos como elementos do DOM. Para inserir um ID dinâmico num seletor, usa "#" + CSS.escape(id) para escapar o identificador CSS, não o seletor inteiro nem o HTML. Estes métodos pertencem ao DOM da plataforma web, não ao ECMAScript 2024. Verifica o suporte do DOM e dos seletores no ambiente de execução de destino.

Exemplos

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

Resultado

A
2
1
2 1

Guarda o exemplo como ficheiro HTML, abre-o num navegador e verifica o resultado na consola do navegador. `:scope > .item` encontra apenas `A`, mas `.frame .item` encontra ambos os parágrafos graças a um antepassado fora de `root`. Depois de remover `B`, a lista guardada continua a ter duas entradas, mas a nova consulta devolve uma.

Lições relacionadas

  • JavaScript · Lição 30 · Avançado · Versão: 4

Fontes