JavaScript Selecionando Elementos do DOM

Antes de alterar qualquer coisa em uma página com JavaScript — atualizar texto, alternar uma classe, adicionar um manipulador de clique — você primeiro precisa encontrar o elemento desejado. Esse ato de encontrar é chamado de seleção de um elemento do DOM. Este capítulo abrange todos os métodos que você precisa, explica o que cada um retorna e mostra quando usar qual.

O que significa "selecionar um elemento"

O Document Object Model (DOM) é a representação viva em formato de árvore que o navegador faz do seu HTML. Cada tag se torna um objeto nó que você pode ler e modificar com JavaScript. Selecionar é o processo de localizar um ou mais desses nós para que você possa manter uma referência a eles em uma variável:

const heading = document.querySelector('h1');
// `heading` now points at the real <h1> on the page.

Com essa referência em mãos, tudo o mais — ler atributos e propriedades, alterar estilos, adicionar ouvintes de eventos — funciona sobre ela.

Os métodos de seleção se dividem em dois grupos:

• Buscas por ID / classe / tag — rápidas, retornam coleções vivas (exceto getElementById).
• Buscas por seletor CSS (querySelector, querySelectorAll) — flexíveis, aceitam qualquer seletor CSS, retornam um resultado estático.

Selecionando um elemento por ID: getElementById

A maneira mais rápida de obter um único elemento é pelo seu id exclusivo. Retorna o elemento ou null se nenhum elemento com esse ID existir.

const element = document.getElementById('example');
element.textContent = 'You selected the element by its ID!';

Como os IDs devem ser únicos, getElementById retorna um único elemento (não uma coleção) e é a busca mais direta e com melhor desempenho.

Selecionando por nome de classe: getElementsByClassName

Este método retorna uma HTMLCollection viva de todos os elementos que possuem a classe informada. "Viva" significa que a coleção é atualizada automaticamente conforme o DOM muda.

const elements = document.getElementsByClassName('example');
Array.from(elements).forEach((element, index) => {
    element.textContent = `Element ${index + 1} changed!`;
});

Uma HTMLCollection é semelhante a um array, mas não é um array de verdade, por isso não possui forEach/map. Converta-a com Array.from() (ou spread [...elements]) antes de usar métodos de array.

Selecionando por nome de tag: getElementsByTagName

Seleciona todos os elementos com um determinado nome de tag e retorna uma HTMLCollection viva.

const paragraphs = document.getElementsByTagName('p');
for (let i = 0; i < paragraphs.length; i++) {
    paragraphs[i].style.backgroundColor = 'yellow';
}

Passe '*' para corresponder a todos os elementos da página. Isso é útil quando você quer operar em todas as tags de um tipo, como destacar todos os parágrafos.

Selecionando pelo atributo name: getElementsByName

Retorna uma NodeList viva de elementos que compartilham o mesmo atributo name. É mais útil para controles de formulário — por exemplo, todos os botões de rádio em um grupo:

const options = document.getElementsByName('plan');
options.forEach((radio) => {
    radio.addEventListener('change', () => {
        console.log('Selected plan:', radio.value);
    });
});

Para um tratamento mais aprofundado de formulários, consulte trabalhando com formulários no DOM.

Selecionando com seletores CSS: querySelector

querySelector retorna o primeiro elemento que corresponde a qualquer seletor CSS que você passar, ou null se nada corresponder. É o método mais versátil para selecionar um único elemento.

const element = document.querySelector('.example');
element.style.backgroundColor = 'lightblue';

Como aceita a sintaxe completa de seletores CSS, você pode selecionar elementos profundamente aninhados: querySelector('nav ul li.active a') encontra o primeiro link correspondente sem encadear várias chamadas.

Selecionando todas as correspondências: querySelectorAll

Retorna uma NodeList estática de todos os elementos que correspondem ao seletor. Ao contrário de getElementsBy..., esse instantâneo não é atualizado quando o DOM muda posteriormente.

const elements = document.querySelectorAll('.example');
elements.forEach((element, index) => {
    element.style.backgroundColor = 'lightgreen';
    element.textContent = `Element ${index + 1} highlighted!`;
});

Uma NodeList tem o método forEach nativo, então você pode iterá-la diretamente. Para usar map/filter, converta-a com Array.from(elements) primeiro.

Restringindo uma busca a um elemento

Todos os métodos querySelector* e getElementsBy* também existem em elementos individuais, não apenas em document. Chamá-los em um elemento restringe a busca aos descendentes desse elemento:

const card = document.querySelector('.card');
const title = card.querySelector('.title'); // only inside .card

Restringir o escopo mantém as consultas rápidas e evita corresponder acidentalmente elementos em outras partes da página.

Testando um elemento: matches

matches não retorna um elemento — retorna true/false indicando se um dado elemento corresponde a um seletor CSS. É ideal dentro de manipuladores de eventos e delegação de eventos.

const element = document.getElementById('test');
if (element.matches('.example')) {
    element.style.color = 'red';
    element.textContent = 'Element matches the selector!';
}

Subindo pela árvore: closest

closest começa no próprio elemento e sobe pelos seus ancestrais, retornando o mais próximo que corresponde ao seletor (ou null). É a maneira mais limpa de encontrar um elemento contêiner.

const element = document.getElementById('child');
const parent = element.closest('.outer');
parent.style.border = '2px solid red';

Combinando seletores para uma seleção precisa

Seletores CSS se compõem, então você pode ser tão específico quanto precisar sem código extra:

const element = document.querySelector('.example.special');
element.style.backgroundColor = 'pink';
element.textContent = 'Special element highlighted!';

Aqui .example.special corresponde a um elemento que possui ambas as classes. Você pode encadear combinadores (>, espaço descendente, +, ~), seletores de atributo (input[type="email"]) e pseudo-classes (li:first-child).

Qual método devo usar?

Regras práticas:

• Use querySelector / querySelectorAll por padrão — uma API consistente e todo o poder do CSS.
• Use getElementById quando tiver um ID único e quiser a busca mais rápida possível.
• Use uma coleção viva (getElementsBy...) somente quando quiser explicitamente que ela acompanhe as mudanças do DOM; caso contrário, prefira o querySelectorAll estático.

Armadilhas comuns

• Resultados null. getElementById, querySelector e closest retornam null quando não há correspondência. Sempre verifique antes de usar o resultado.
• Executar antes de o DOM existir. Se seu script rodar no <head> antes de os elementos serem analisados, as seleções não retornam nada. Coloque scripts no final do <body>, use defer ou aguarde o DOMContentLoaded.
• Coleções não são arrays. HTMLCollection não tem forEach. NodeList tem forEach, mas não tem map/filter. Converta com Array.from() quando tiver dúvida.

Conclusão

Selecionar elementos é o ponto de entrada para toda tarefa no DOM. Para a maior parte do código, querySelector e querySelectorAll oferecem uma API flexível e poderosa baseada em CSS; getElementById continua sendo a escolha mais rápida para IDs únicos; e matches / closest viabilizam uma delegação de eventos limpa. Depois de conseguir selecionar elementos com confiança, continue com manipulação do DOM e percorrendo o DOM.

Prática