querySelector do JavaScript Explicado: Sintaxe, Seletores Avançados, Boas Práticas e Exemplos

By 佐川 直弘 | Naohiro Sagawa (運営者)

※記事内に広告を含みます。Amazonアソシエイトとして適格販売により収入を得ています。　

.## 1. Introdução: O que é querySelector?

Visão geral básica e papel do querySelector

querySelector é um método que retorna o primeiro elemento que corresponde ao seletor especificado.

Vamos observar o exemplo abaixo.

const element = document.querySelector('.example');
console.log(element);

Este código obtém o primeiro elemento com o nome de classe example.

Mesmo que existam múltiplos elementos para o mesmo seletor, apenas o primeiro elemento correspondente é retornado.

<div class="example">1</div>
<div class="example">2</div>

Neste caso, apenas o primeiro <div class="example">1</div> será selecionado.

Por que o querySelector é importante na manipulação do DOM

querySelector é especialmente útil em situações como as seguintes.

1. Seleção flexível de elementos usando seletores CSS * Suporta uma ampla variedade de seletores, como classes, IDs, atributos e pseudo‑classes.

2. Código limpo mesmo para estruturas complexas * Encontra eficientemente elementos aninhados ou elementos com atributos específicos.

3. Estilo JavaScript consistente e moderno * Mais versátil que getElementById ou getElementsByClassName, e funciona bem com padrões modernos de JavaScript.

Aqui está um exemplo de seleção de um botão específico dentro de um formulário.

const submitButton = document.querySelector('form button[type="submit"]');
console.log(submitButton);

Este código seleciona apenas o botão de envio dentro do formulário.

Diferença entre querySelector e querySelectorAll

Enquanto querySelector retorna apenas o primeiro elemento correspondente, querySelectorAll retorna todos os elementos correspondentes como um NodeList.

const elements = document.querySelectorAll('.example');
console.log(elements);

Este código recupera todos os elementos com o nome de classe example.

Resumo

Nesta seção, explicamos o conceito básico e o papel do método querySelector do JavaScript.

Principais pontos:

1. Você pode selecionar elementos de forma flexível usando seletores CSS
2. querySelector retorna apenas a primeira correspondência, enquanto querySelectorAll retorna todas as correspondências
3. É um método importante para manipulação concisa e eficiente do DOM

Na próxima seção, analisaremos mais detalhadamente a sintaxe básica do querySelector e exemplos práticos de uso.

2. Sintaxe básica e uso do querySelector

Sintaxe básica

A sintaxe básica do querySelector é a seguinte:

document.querySelector(selector);

• Argumento : Uma string de seletor CSS.
• Valor de retorno : O primeiro elemento que corresponde ao seletor. Se nenhuma correspondência for encontrada, retorna null.

Exemplos: Selecionando elementos básicos

1. Selecionar por ID Como um ID é único, você pode selecionar de forma confiável exatamente um elemento.

   const element = document.querySelector('#header');
   console.log(element);
   

Este código seleciona o elemento com o ID header.

2. Selecionar por classe Quando você especifica um nome de classe, apenas o primeiro elemento correspondente é retornado.

   const element = document.querySelector('.content');
   console.log(element);
   

Este código seleciona o primeiro elemento com o nome de classe content.

3. Selecionar por nome de tag Você também pode selecionar elementos especificando um nome de tag.

   const element = document.querySelector('p');
   console.log(element);
   

Este código seleciona a primeira tag <p> na página.

Selecionando elementos com seletores combinados

Ao combinar seletores CSS, você pode direcionar elementos de forma mais flexível.

1. Seletores aninhados Selecione elementos especificando uma relação pai‑filho.

   const element = document.querySelector('div.container p');
   console.log(element);
   

Este código seleciona a primeira tag <p> dentro de um <div> com o nome de classe container.

2. Seletores de atributo Selecione elementos que possuam um atributo específico.

   const element = document.querySelector('input[type="text"]');
   console.log(element);
   

Este código seleciona o primeiro elemento <input> cujo atributo type é text.

3. Usando pseudo‑classes Use pseudo‑classes para selecionar elementos em um estado ou posição específicos.

   const element = document.querySelector('li:first-child');
   console.log(element);
   

Este código seleciona o primeiro elemento <li>.

O que fazer quando querySelector não encontra um elemento

querySelector retorna null quando nenhum elemento correspondente é encontrado. Por esse motivo, é importante verificar se o elemento existe após selecioná‑lo.

const element = document.querySelector('.nonexistent');
if (element) {
  console.log('Element found');
} else {
  console.log('Element not found');
}

Este código funciona com segurança sem lançar um erro mesmo quando o elemento não existe.

Resumo

Nesta seção, cobrimos a sintaxe básica e o uso do querySelector.

Recapitulação rápida:

1. Você pode selecionar facilmente elementos por ID, classe ou nome da tag
2. Você pode selecionar de forma flexível elementos combinando seletores complexos e pseudo‑classes
3. O tratamento de erros para elementos ausentes também é importante

Na próxima seção, mergulharemos em exemplos avançados de uso com seletores mais poderosos.

3. Exemplos avançados: como usar seletores mais poderosos

Selecionar elementos específicos com seletores de atributos

Seletores de atributos permitem selecionar de forma flexível elementos que possuam atributos ou valores específicos.

1. Selecionar um elemento com um valor de atributo específico

   const checkbox = document.querySelector('input[type="checkbox"]');
   console.log(checkbox);
   

Este código seleciona o primeiro elemento <input> cujo atributo type é checkbox.

2. Usar correspondências parciais para valores de atributo

   const link = document.querySelector('a[href^="https://"]');
   console.log(link);
   

Este código seleciona um link cujo atributo href começa com https://.

Seletores de atributos mais usados:

Selecionando com pseudo‑classes e pseudo‑elementos

Pseudo‑classes e pseudo‑elementos facilitam a seleção de elementos em estados ou posições específicas.

1. Pseudo‑classes para estado

   const activeLink = document.querySelector('a.active');
   console.log(activeLink);
   

Este código seleciona um link que possui a classe active.

2. Pseudo‑classes para posição

   const firstItem = document.querySelector('ul > li:first-child');
   console.log(firstItem);
   

Este código seleciona o primeiro item da lista.

Pseudo‑classes mais usadas:

Filtragem refinada com seletores compostos

Você também pode combinar múltiplos seletores para expressar condições mais complexas.

1. Filtrar por relação pai‑filho

   const nestedElement = document.querySelector('div.container > p.text');
   console.log(nestedElement);
   

Este código seleciona o primeiro elemento p com a classe text dentro de um elemento div com a classe container.

2. Combinar múltiplas condições

   const inputField = document.querySelector('input[type="text"].required');
   console.log(inputField);
   

Este código seleciona o primeiro elemento <input> que tem type="text" e também possui a classe required.

Resumo

Nesta seção, explicamos o uso avançado de seletores com querySelector.

Pontos principais:

1. Seletores de atributos permitem filtragem flexível de elementos
2. Pseudo‑classes e pseudo‑elementos permitem direcionar estado e posição
3. Seletores compostos facilitam especificar condições detalhadas e selecionar alvos complexos

Na próxima seção, abordaremos precauções importantes e boas práticas ao usar querySelector.

4. Precauções e boas práticas ao usar querySelector

Tratamento de erros e verificações de null

Se nenhum elemento corresponder ao seletor especificado, querySelector retorna null. Por esse motivo, você deve sempre confirmar que o elemento existe antes de tentar manipulá‑lo.

Exemplo: Implementando uma verificação de null

.

const element = document.querySelector('.nonexistent');
if (element) {
  console.log('Element found');
  element.textContent = 'New text';
} else {
  console.log('Element not found');
}

Este código evita erros com segurança mesmo que o elemento não exista.

Escapando Caracteres Especiais

Se o seu seletor contém caracteres especiais, querySelector pode lançar um erro a menos que você os escape corretamente.

Exemplo: Selecionando um elemento que contém caracteres especiais

HTML:

<div id="my.id">Special ID</div>

JavaScript:

const element = document.querySelector('#my\.id');
console.log(element);

Ao lidar com caracteres especiais (por exemplo, ., #, [, ], etc.), escape‑os usando uma barra invertida (\).

Considerações de Performance

1. Evite seletores profundamente aninhados À medida que os seletores se tornam mais complexos, o navegador pode demorar mais para encontrar o elemento alvo. Use seletores mais simples sempre que possível.

Não recomendado

const element = document.querySelector('div.container > ul > li.item > span.text');

Recomendado

const container = document.querySelector('.container');
const textElement = container.querySelector('.text');

2. Selecione múltiplos elementos de forma eficiente Use querySelectorAll para recuperar todos os elementos alvo e então filtre‑os conforme necessário.

   const items = document.querySelectorAll('.item');
   items.forEach((item) => {
     console.log(item.textContent);
   });
   

Boas Práticas

1. Use seletores específicos Use seletores específicos para garantir que você selecione apenas o(s) elemento(s) desejado(s).

   const button = document.querySelector('button.submit');
   

2. Use convenções de nomenclatura consistentes Defina nomes de classes CSS e IDs seguindo regras consistentes para melhorar a legibilidade dos seletores.
3. Foque em código reutilizável Se você seleciona certos elementos com frequência, é conveniente encapsular a lógica em uma função reutilizável.

   function getElement(selector) {
     const element = document.querySelector(selector);
     if (!element) {
       console.warn(`Element not found: ${selector}`);
     }
     return element;
   }
   
   const header = getElement('#header');
   

Resumo

Nesta seção, abordamos precauções importantes e maneiras eficientes de usar querySelector.

Pontos principais:

1. Previna erros realizando verificações de nulidade de forma consistente
2. Escape corretamente seletores que incluam caracteres especiais
3. Projete seletores de forma simples, pensando em performance
4. Use funções e convenções de nomenclatura para melhorar a reutilização e a legibilidade

Na próxima seção, apresentaremos exemplos práticos úteis em projetos reais.

5. Perguntas Frequentes (FAQ) e Soluções

Qual a Diferença entre querySelector e getElementById?

Pergunta:
querySelector e getElementById podem ser usados para selecionar elementos. Qual a diferença entre eles?

Resposta:

Comparação de uso:

// With querySelector
const element1 = document.querySelector('#example');

// With getElementById
const element2 = document.getElementById('example');

Qual deles você deve usar?

• Para seleção simples baseada em ID, getElementById é rápido e recomendado.
• Quando precisar de seleção flexível baseada em seletor, use querySelector .

Por que querySelector às Vezes Não Funciona?

Pergunta:
Mesmo que meu código pareça correto, querySelector não funciona. Qual pode ser a causa?

Resposta:

1. O elemento ainda não existe no DOM

• O DOM pode não estar totalmente carregado quando o script é executado. Solução: Use o evento DOMContentLoaded.

  document.addEventListener('DOMContentLoaded', () => {
    const element = document.querySelector('.example');
    console.log(element);
  });
  

2. O seletor está incorreto

• O nome da classe ou o ID podem estar errados.

O que verificar:

• Verifique o seletor nas ferramentas de desenvolvedor do seu navegador.

  const element = document.querySelector('.my-class');
  console.log(element); // Check the result in DevTools
  

3. O elemento é adicionado dinamicamente

• Se o elemento for adicionado dinamicamente via JavaScript, ele pode não existir no momento em que você tentar selecioná-lo pela primeira vez.

Solução:
Anexe um ouvinte de eventos a um elemento pai para lidar com elementos adicionados dinamicamente.

document.body.addEventListener('click', (e) => {
  if (e.target.matches('.dynamic-element')) {
    console.log('Clicked');
  }
});

Como Acessar Elementos Adicionados Dinamicamente

Pergunta:
Elementos adicionados dinamicamente podem ser selecionados com querySelector?

Resposta:
Sim, eles podem. No entanto, você precisa prestar atenção ao momento em que o elemento é adicionado.

Solução 1: Observar elementos dinâmicos

const observer = new MutationObserver((mutations) => {
  mutations.forEach((mutation) => {
    if (mutation.addedNodes.length) {
      const newElement = document.querySelector('.dynamic-element');
      if (newElement) {
        console.log('A new element was added:', newElement);
      }
    }
  });
});

observer.observe(document.body, { childList: true, subtree: true });

Solução 2: Use setTimeout ou setInterval

Se o elemento for adicionado após um certo atraso, você pode monitorá-lo assim:

setTimeout(() => {
  const dynamicElement = document.querySelector('.dynamic-element');
  console.log(dynamicElement);
}, 1000); // Check for the element after 1 second

Resumo

Nesta seção, cobrimos perguntas comuns e dicas de solução de problemas para usar querySelector.

Resumo rápido:

1. Entenda quando usar querySelector vs. getElementById .
2. Se não funcionar, verifique timing de carregamento do DOM e erros de seletor .
3. Para elementos dinâmicos, use delegação de eventos ou MutationObserver .

Na próxima seção, resumiremos os pontos principais para usar querySelector de forma eficaz.

6. Exemplos Práticos: Como Usar querySelector em Projetos Reais

Obter Valores de Entrada de Formulário e Validá-los

Cenário: Quando um usuário insere valores em um formulário, você os recupera e realiza a validação.

HTML

<form id="userForm">
  <input type="text" id="username" placeholder="Username">
  <input type="email" id="email" placeholder="Email address">
  <button type="submit">Submit</button>
</form>

JavaScript

const form = document.querySelector('#userForm');

form.addEventListener('submit', (event) => {
  event.preventDefault(); // Prevent form submission

  const username = document.querySelector('#username').value;
  const email = document.querySelector('#email').value;

  if (!username) {
    alert('Please enter a username');
    return;
  }

  if (!email.includes('@')) {
    alert('Please enter a valid email address');
    return;
  }

  alert('The form was submitted successfully');
});

Pontos principais:

• Use a propriedade value para obter valores de entrada.
• Realize verificações simples de validação na entrada do usuário.
• Use ouvintes de eventos para personalizar o comportamento de envio do formulário.

Como Adicionar Ouvintes de Eventos a Elementos Adicionados Dinamicamente

Cenário: Aplicar ouvintes de eventos a elementos que são adicionados dinamicamente via JavaScript.

HTML

<div id="container">
  <button id="addButton">Add a button</button>
</div>

JavaScript

const container = document.querySelector('#container');
const addButton = document.querySelector('#addButton');

// Add a new button
addButton.addEventListener('click', () => {
  const newButton = document.createElement('button');
  newButton.classList.add('dynamic-button');
  newButton.textContent = 'Click me!';
  container.appendChild(newButton);
});

// Capture events on the parent element
container.addEventListener('click', (event) => {
  if (event.target.classList.contains('dynamic-button')) {
    alert('The new button was clicked!');
  }
});

Pontos principais:

• Como os elementos adicionados dinamicamente não podem ser referenciados diretamente, anexe o listener de evento a um elemento pai.
• Use event.target para identificar qual elemento foi clicado.

Abrindo e Fechando uma Janela Modal

Cenário: Implementar comportamento de abrir/fechar modal.

HTML

<div id="modal" class="modal hidden">
  <div class="modal-content">
    <span id="closeModal" class="close">&times;</span>
    <p>This is the modal content.</p>
  </div>
</div>
<button id="openModal">Open modal</button>

CSS

.hidden {
  display: none;
}

.modal {
  position: fixed;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  background: rgba(0, 0, 0, 0.5);
  display: flex;
  justify-content: center;
  align-items: center;
}

.modal-content {
  background: white;
  padding: 20px;
  border-radius: 5px;
}

JavaScript

const modal = document.querySelector('#modal');
const openModal = document.querySelector('#openModal');
const closeModal = document.querySelector('#closeModal');

// Open the modal
openModal.addEventListener('click', () => {
  modal.classList.remove('hidden');
});

// Close the modal
closeModal.addEventListener('click', () => {
  modal.classList.add('hidden');
});

// Close when clicking outside the modal
modal.addEventListener('click', (event) => {
  if (event.target === modal) {
    modal.classList.add('hidden');
  }
});

Pontos‑chave:

• Use classList para adicionar/remover classes e alternar a visibilidade.
• Melhore a UX permitindo que o modal seja fechado ao clicar fora da área de conteúdo.

Resumo

Nesta seção, apresentamos exemplos práticos de como usar querySelector em cenários reais de desenvolvimento.

O que você aprendeu:

1. Implementar tratamento seguro de formulários ao recuperar e validar a entrada do usuário.
2. Manipular elementos adicionados dinamicamente de forma flexível usando delegação de eventos.
3. Melhorar a interface implementando o comportamento de abrir/fechar modal.

Use esses exemplos como referência e aplique‑os em seus próprios projetos de desenvolvimento. Na próxima seção, concluiremos o artigo resumindo os pontos‑chave para usar querySelector.

7. Resumo: Principais Lições para Usar querySelector de Forma Eficaz

Neste artigo, abordamos o método querySelector do JavaScript em detalhes, desde o básico até casos de uso avançados. Por fim, vamos revisar os pontos mais importantes e resumir como usá‑lo de forma eficaz.

O Papel Central do querySelector

• Seleção flexível de elementos: Você pode selecionar elementos do DOM de forma eficiente usando seletores CSS.
• Sintaxe simples: Você pode selecionar elementos de forma intuitiva usando nomes de classe, IDs, nomes de tags e seletores de atributos.
• Funciona com elementos dinâmicos: Ao anexar listeners de evento a elementos pais, você pode lidar com elementos adicionados posteriormente.

Exemplo da sintaxe básica:

const element = document.querySelector('.example');

Uso Avançado e Considerações Importantes

1. Use seletores avançados

• Seletores de atributos e pseudo‑classes permitem direcionar elementos de forma mais precisa e flexível.
• Exemplo:

  const element = document.querySelector('input[type="checkbox"]:checked');
  

2. Escreva código consciente de desempenho

• Reduza a sobrecarga de processamento usando seletores simples sempre que possível.
• Transforme a lógica de seleção frequentemente usada em funções reutilizáveis.

2. Tratamento de erros completo

• Realize verificações de null e trate casos em que o elemento não exista.
• Exemplo:

  const element = document.querySelector('.nonexistent');
  if (element) {
    console.log('Element found');
  } else {
    console.log('Element not found');
  }
  

Revisando os Exemplos Práticos

• Validação de formulário: Valide valores de entrada para implementar um processamento seguro de formulários.
• Manipulação de elementos dinâmicos: Manipule de forma flexível elementos gerados via JavaScript.
• Controle de janela modal: Adicione comportamento interativo para melhorar a UI/UX.

.Através desses exemplos, você aprendeu a praticidade e a extensibilidade do querySelector.

Dicas para Aproveitar ao Máximo o querySelector

1. Aproveite suas ferramentas de desenvolvimento

• Use as ferramentas de desenvolvedor do seu navegador para validar e testar seletores.

1. Priorize a legibilidade

• Crie nomes de seletores e estrutura de código que sejam fáceis de entender, melhorando a manutenção.

1. Use querySelectorAll em conjunto quando necessário

• Ao trabalhar com múltiplos elementos, use querySelectorAll para implementar um processamento eficiente.

Resumo

querySelector é um método poderoso que torna a manipulação do DOM simples e eficiente.

Principais aprendizados deste artigo:

• Você pode compreender tudo, desde o uso básico até exemplos avançados, de forma estruturada.
• Ao combinar seletores e pseudo‑classes, você pode direcionar elementos com mais flexibilidade.
• Ao tratar erros adequadamente e considerar o desempenho, você pode escrever código mais prático e confiável.

Ao trabalhar com manipulação do DOM em JavaScript, certifique‑se de aplicar as técnicas apresentadas neste artigo.

Como próximo passo, aprofunde seu conhecimento em manipulação do DOM e melhore suas habilidades aprendendo a combinar o querySelector com outros métodos!