DOM em JavaScript: o Modelo de Objetos do Documento

O Modelo de Objetos do Documento, ou DOM, é a árvore dinâmica de objetos da página mantida pelo navegador. JavaScript lê e altera esses objetos para atualizar a página sem recarregá-la. O navegador fornece a API DOM; JavaScript é a linguagem usada para chamá-la.

Comece pelo documento

document é o ponto de entrada. document.documentElement refere-se a <html>, document.head a <head> e document.body a <body>. A aba do navegador é representada por window, cuja propriedade document se refere a esse documento.

Cada item da árvore é um nó. Elementos representam tags; nós de texto contêm caracteres; nós de comentário contêm comentários HTML; o nó de documento fica acima dos elementos da página. Seus valores de nodeType são, respectivamente, 1, 3, 8 e 9. Todo elemento é um nó, mas texto e comentários não são elementos.

Leia as relações familiares

<ul id="menu"><li>Home</li><li>About</li></ul>

A lista é pai de dois elementos de item irmãos. Cada item é seu filho. O primeiro item tem um nó de texto filho que contém “Home”. A lista é ancestral desse nó de texto, e o texto é descendente da lista. Essas relações descrevem o aninhamento, não posições na tela.

Espaços e quebras de linha entre tags geralmente se tornam nós de texto com espaços em branco. Uma lista indentada pode, portanto, ter dois elementos filhos, mas mais de dois nós filhos. children e firstElementChild retornam apenas elementos; childNodes e firstChild incluem texto e comentários.

Compare a árvore com o código-fonte

A análise sintática transforma a marcação na árvore e pode completá-la ou corrigi-la. Linhas escritas diretamente dentro de uma <table> recebem um pai <tbody>. Elementos <html>, <head> ou <body> ausentes também podem ser adicionados. Selecione elementos da árvore real, incluindo os adicionados pelo analisador.

Alterações feitas por scripts afetam o DOM atual do navegador, não o arquivo HTML no servidor. “Ver código-fonte da página” mostra o HTML original, enquanto o painel Elementos das DevTools mostra a árvore atual. Recarregar constrói um novo DOM; uma edição, por si só, não salva os dados que a originaram.

Inspecione um objeto

Clique com o botão direito em um elemento e escolha “Inspecionar”. Digite $0 no Console para se referir ao elemento selecionado. console.log($0) o apresenta como marcação; console.dir($0) mostra suas propriedades. Expanda uma lista indentada para ver os nós de espaços em branco junto aos elementos de item.

As propriedades da árvore permitem que um script alcance conteúdo próximo a partir de um elemento que já possui. Escolha se esse caminho deve incluir texto e comentários ou apenas elementos.

Escolha nós ou elementos

As propriedades para nós incluem parentNode, childNodes, firstChild, lastChild, previousSibling e nextSibling. Suas correspondentes para elementos são parentElement, children, firstElementChild, lastElementChild, previousElementSibling e nextElementSibling. children é uma HTMLCollection; childNodes é uma NodeList.

<ul id="tasks">
  <li>Buy milk</li>
  <li>Call Sam</li>
</ul>

Aqui, tasks.childNodes.length é 5: dois elementos e três trechos de espaços em branco. tasks.children.length é 2. tasks.firstChild é texto com espaços em branco, enquanto tasks.firstElementChild.textContent é “Buy milk”. Os índices começam em 0, portanto tasks.children[1] é o segundo item.

Siga um caminho curto

const tasks = document.querySelector("#tasks");
const first = tasks.firstElementChild;
const second = first.nextElementSibling;
console.log(second.textContent);
console.log(second.parentElement === tasks);

O resultado é “Call Sam”, seguido de true. tasks.lastElementChild alcança o mesmo item diretamente, assim como tasks.children[tasks.children.length - 1].

Trate um parente ausente

O nextElementSibling do último item é null. Um elemento sem elementos filhos tem firstElementChild === null e uma coleção children vazia. O parentNode do elemento HTML raiz é o documento, mas seu parentElement é null.

Ler uma propriedade de null lança um erro de tipo. Verifique antes ou use second.nextElementSibling?.textContent, que fornece undefined quando não existe um próximo elemento.

Encontre um item que contém o elemento

closest(selector) verifica o elemento atual e depois seus ancestrais, retornando a correspondência mais próxima ou null. Um botão dentro de <li class="task" data-id="7"> pode usar button.closest(".task"); o dataset.id do item encontrado é “7”. Já matches(selector) testa apenas o elemento atual e retorna um booleano.

Caminhos longos como el.parentElement.parentElement.nextElementSibling dependem do aninhamento exato. Um elemento envoltório adicionado muda seu significado. Use seletores para regiões nomeadas, navegação curta para relações estáveis e closest() para encontrar um item que contém o elemento.

Um seletor transforma a descrição de um elemento em uma referência a um objeto. Comece com a menor pesquisa que identifique o elemento necessário e verifique se ele foi encontrado antes de alterá-lo.

Pesquise com um seletor CSS ou um id

document.querySelector(selector) retorna o primeiro elemento correspondente na ordem do documento. Ele aceita seletores CSS conhecidos: "h1", ".price", "#cart", "nav a" ou 'input[type="email"]'. Se não houver correspondência, retorna null.

document.getElementById("cart") procura um id diretamente. Seu argumento é o id puro. getElementById("#cart") procura um id que realmente inclua o caractere cerquilha, enquanto querySelector("cart") procura uma tag <cart>. Use querySelector("#cart") para o seletor de id.

Ids devem ser únicos. Se uma marcação copiada der o mesmo id a dois elementos, essas pesquisas retornarão o primeiro na ordem do documento. Corrija a marcação duplicada em vez de esperar que uma pesquisa por id alcance a segunda cópia.

Pesquise dentro de um contêiner

Suponha que vários cartões tenham um elemento com a classe name. Selecione primeiro o cartão de perfil e depois pesquise seus descendentes:

const card = document.querySelector("#profile");
if (card) {
  const name = card.querySelector(".name");
  if (name) name.textContent = "Maya";
}

A pesquisa interna fica limitada ao cartão de perfil, portanto um .name anterior em outro lugar não interfere. O próprio contêiner não é candidato em sua pesquisa com querySelector(). Elementos comuns oferecem esse método, mas getElementById() pertence a document.

Distinga ausência de correspondência de seletor inválido

Uma pesquisa válida sem correspondência fornece null. Tentar definir null.textContent lança um erro de tipo, portanto verifique conteúdo opcional:

const banner = document.querySelector(".banner");
if (banner) banner.textContent = "Sale ends Friday";

Um seletor CSS inválido lança um erro de sintaxe antes que possa haver um resultado. Para <p id="1st">, querySelector("#1st") é inválido porque o algarismo precisa de escape nesse seletor CSS de id. getElementById("1st") usa um id literal e funciona diretamente.

Execute depois que a marcação necessária existir

Um script externo clássico em <head> é executado antes de o navegador analisar o corpo. Uma pesquisa por um parágrafo posterior retorna, portanto, null, mesmo quando o HTML o contém. Use <script src="app.js" defer></script> para executar depois da análise, use um script de módulo ou coloque o script logo antes de </body>. Scripts de módulo têm execução adiada por padrão. O atributo defer não tem efeito em um script clássico incorporado ao HTML.

Em uma página HTML que começa com <!DOCTYPE html>, seletores de id e classe diferenciam maiúsculas de minúsculas: .Price não encontra class="price". Seletores de tags HTML não fazem essa distinção, portanto "LI" e "li" correspondem a itens de lista. Quando uma pesquisa falhar, verifique a escrita, a sintaxe do seletor, o contêiner de pesquisa e o momento de execução do script.

Use querySelectorAll() quando a mesma operação deve ser aplicada a vários elementos. Seu resultado é uma coleção, portanto você precisa decidir como percorrê-la e se precisa de um retrato estático ou de uma visão dinâmica.

Leia e percorra uma NodeList

document.querySelectorAll(".note") retorna uma NodeList de elementos correspondentes na ordem do documento. Sem correspondências, o resultado é uma NodeList vazia de tamanho 0. A coleção em si ainda é avaliada como verdadeira; if (notes) não informa se ela contém elementos. Verifique notes.length.

Uma NodeList oferece índices, length, forEach() e for...of, mas não é um vetor e não tem map(), filter() nem reduce(). Converta-a quando precisar desses métodos:

const weights = Array.from(document.querySelectorAll(".weight"))
  .map(el => Number(el.textContent));
const total = weights.reduce((sum, weight) => sum + weight, 0);

Para elementos que contêm “4.5”, “12” e “3.25”, o vetor é [4.5, 12, 3.25] e o total é 19,75 kg. A conversão para números é importante porque os valores de texto são cadeias de caracteres.

Uma coleção não é um elemento combinado. Definir notes.textContent não altera nenhuma nota, e notes.classList.add("saved") lança um erro porque a NodeList não tem classList. Aplique a alteração a cada elemento:

const notes = document.querySelectorAll(".note");
notes.forEach(note => note.classList.add("saved"));

Compare resultados estáticos e dinâmicos

A NodeList de querySelectorAll() é estática: seus membros são fixados quando a pesquisa é executada. Os elementos aos quais ela se refere continuam sendo os objetos reais, portanto seu texto ou suas classes podem mudar.

getElementsByClassName("note") e getElementsByTagName("li") retornam uma HTMLCollection dinâmica. children também é dinâmica. Essas coleções atualizam seus membros quando o DOM muda. Elas oferecem índices e for...of, mas não forEach().

Em uma lista com três elementos .item, salve tanto list.getElementsByClassName("item") quanto list.querySelectorAll(".item"). Acrescente um quarto elemento correspondente. A coleção dinâmica passa a ter tamanho 4; o retrato estático continua com tamanho 3.

Evite a armadilha de uma coleção dinâmica que diminui durante o laço

Suponha que quatro elementos pertençam a uma coleção dinâmica chamada live:

for (let i = 0; i < live.length; i++) {
  live[i].classList.remove("item");
}

Remover a primeira classe retira esse elemento da coleção. O próximo elemento é deslocado para o índice 0, mas o laço avança para o índice 1 e o ignora. Apenas dois dos quatro perdem a classe. Percorra Array.from(live) ou um retrato estático de querySelectorAll() ao alterar os membros da coleção.

Verifique os espaços nos seletores

.task.done significa um elemento com ambas as classes. .task .done significa um descendente .done dentro de um .task. Para <li class="task done">, conte os itens concluídos com document.querySelectorAll(".task.done").length. Uma vírgula combina seletores: "h2, h3" retorna correspondências na ordem do documento, não todos os títulos de um tipo seguidos pelos do outro.

Texto e HTML são entradas diferentes. Texto simples deve aparecer como caracteres; HTML descreve elementos que o navegador deve construir. Escolher entre eles afeta tanto a estrutura da página quanto a possibilidade de texto externo executar código indesejado.

Leia e substitua texto

Para <p id="msg">Total: <strong>3</strong> items</p>, msg.textContent é “Total: 3 items”. Ele une o texto dos descendentes do elemento sem incluir suas tags e inclui texto ocultado por CSS.

Definir textContent substitui todos os filhos por um nó de texto. Após msg.textContent = "Cart is empty", o filho <strong> deixa de existir dentro do parágrafo. Definir msg.textContent = "<b>Hi</b>" exibe os caracteres literais “Hi”; não cria um elemento em negrito.

Valores de texto são cadeias de caracteres. Se um contador contém “4”, count.textContent + 1 produz “41”. Converta antes de somar:

count.textContent = Number(count.textContent) + 1;

A soma fornece o número 5, e a atribuição exibe sua forma textual, “5”.

Leia o texto que segue o layout

Em um elemento renderizado, innerText acompanha o texto e o layout exibidos. Ele omite descendentes ocultos com display: none e inclui quebras de linha que seguem o layout. Lê-lo pode exigir um cálculo de layout. Use textContent para o trabalho comum com texto; escolha innerText quando precisar do texto renderizado. Se o próprio elemento estiver desconectado ou não for renderizado, innerText recorre ao seu conteúdo de texto.

Analise HTML intencionalmente

innerHTML lê a marcação dentro de um elemento. Defini-lo analisa a cadeia de caracteres e substitui os filhos:

msg.innerHTML = "Total: <strong>5</strong> items";

Isso cria um novo elemento <strong>. É adequado para marcação que você escreveu e controla. Para texto de um usuário ou de dados externos, use textContent e construa a estrutura com createElement().

Inserir HTML não confiável pode permitir injeção de scripts entre sites (XSS): código controlado por um invasor é executado no navegador do visitante. Uma imagem injetada pode conter um atributo onerror que executa código quando a imagem não carrega. Tags de script inseridas por innerHTML não são executadas, mas isso não torna seguro outro HTML injetado. Bloquear apenas tags de script deixa esse caminho de ataque aberto.

Preserve os filhos existentes ao adicionar conteúdo

list.innerHTML += "<li>New</li>" lê a marcação existente, concatena uma cadeia de caracteres e depois analisa e substitui todo o conjunto de filhos. Ele não preserva a identidade dos objetos. Uma variável que contém um filho antigo continua contendo esse objeto desconectado, e valores digitados em campos substituídos podem ser perdidos. Use append() com novos nós, ou insertAdjacentHTML("beforeend", markup) para marcação confiável, para adicionar conteúdo sem recriar os filhos existentes.

outerHTML inclui a própria tag do elemento e também seu conteúdo. Defini-lo substitui o próprio elemento. Uma referência salva continua apontando para o elemento antigo e desconectado após a substituição; ela não passa automaticamente a apontar para o novo.

Um atributo é um nome e um valor no HTML. Uma propriedade pertence ao objeto JavaScript que representa um elemento. Muitos atributos padrão têm propriedades correspondentes, mas essas propriedades podem processar valores ou informar outro tipo de estado.

Trabalhe com um atributo pelo nome

Para <img src="logo.png" alt="Company logo">, o navegador inicializa propriedades como img.src e img.alt. Você também pode usar métodos que recebem o nome do atributo como uma cadeia de caracteres:

• getAttribute(name) retorna uma cadeia de caracteres, ou null se o atributo estiver ausente.
• setAttribute(name, value) adiciona ou altera um atributo e armazena seu valor como texto.
• hasAttribute(name) informa se o atributo está presente.
• removeAttribute(name) o remove.

Por exemplo, link.setAttribute("href", "https://example.com/help") altera o destino de um link. Se não houver um atributo target, link.getAttribute("target") retorna null, não uma cadeia de caracteres vazia.

Leia o valor de que você realmente precisa

Em uma página no endereço https://example.com/shop/, o link <a href="/about"> tem o valor de atributo “/about”. Sua propriedade href é a URL resolvida, “https://example.com/about”. Leia o atributo quando precisar do valor exatamente como foi escrito e a propriedade quando precisar da URL resolvida.

Propriedades podem ter tipos diferentes de cadeia de caracteres. button.disabled é um booleano; input.maxLength é um número. Métodos de atributo ainda retornam cadeias de caracteres ou null. Nomes de propriedades também são nomes JavaScript que diferenciam maiúsculas de minúsculas: el.id funciona, enquanto el.ID é uma propriedade diferente e normalmente é undefined.

A maioria dos nomes é conhecida, mas há exceções. O atributo HTML class é disponibilizado por className e classList. O atributo for de um rótulo corresponde à propriedade htmlFor:

label.htmlFor = "email";

Isso associa o rótulo ao elemento cujo id é “email”.

Trate atributos booleanos pela presença

Atributos booleanos incluem disabled, checked, required e readonly. Sua presença torna o atributo verdadeiro, mesmo que seu texto seja “false”. Este código desabilita um botão:

button.setAttribute("disabled", "false");

Para habilitá-lo, defina button.disabled = false ou chame button.removeAttribute("disabled"). button.toggleAttribute("disabled", isBusy) adiciona o atributo quando isBusy é verdadeiro e o remove quando é falso.

Descreva controles de forma acessível

Atributos ARIA fornecem informações à tecnologia assistiva. Métodos de atributo são úteis para defini-los, como em button.setAttribute("aria-label", "Close dialog"), para dar nome a um botão que contém apenas um ícone. Seus valores são cadeias de caracteres; por exemplo, um valor de estado expandido é “true” ou “false”.

Use propriedades para operações comuns, como img.src = "photo.jpg" ou input.disabled = true. Use métodos de atributo quando o nome estiver em uma variável, quando o valor exato escrito for importante ou quando o atributo não tiver uma propriedade correspondente que você esteja usando.

Acompanhe uma alteração de propriedade até o HTML

const field = document.createElement("input");
field.disabled = true;
console.log(field.hasAttribute("disabled"));
console.log(typeof field.disabled);
console.log(typeof field.getAttribute("disabled"));
field.removeAttribute("disabled");
console.log(field.disabled);

Os resultados são true, “boolean”, “string” e false. Definir a propriedade adiciona o atributo booleano. Ler esse atributo ainda retorna texto, embora a propriedade seja um booleano. Removê-lo faz a propriedade voltar a ser falsa. O método e a propriedade mostram a mesma presença por meio de tipos de valor diferentes.

Um elemento pode carregar um id dos dados que exibe sem mostrar esse id na tela. Controles de formulário também contêm valores, mas seu conteúdo atual é lido por meio de propriedades. Ambos os tipos de valor frequentemente precisam ser convertidos antes de comparações ou operações aritméticas.

Armazene dados personalizados com atributos de dados

Nomes HTML que começam com data- armazenam informações para scripts:

<li data-task-id="17" data-priority="high">Prepare slides</li>

O objeto dataset disponibiliza esses atributos. Remova o prefixo data- e transforme cada hífen seguido de uma letra minúscula nessa letra maiúscula: data-task-id vira dataset.taskId. data-priority vira dataset.priority.

li.dataset.dueDate = "2026-11-05";
delete li.dataset.priority;

A atribuição cria data-due-date="2026-11-05". O delete remove data-priority. Atributos de dados também podem ser selecionados com seletores CSS de atributo, como '[data-priority="high"]'.

Um atributo inventado como taskid="17" é HTML inválido e não cria uma propriedade li.taskid. getAttribute("taskid") ainda pode lê-lo, mas data-task-id é a forma adequada para dados personalizados.

Converta valores de cadeia de caracteres intencionalmente

li.dataset.taskId é “17”, uma cadeia de caracteres. li.dataset.taskId === 17 é falso porque os tipos são diferentes. Quando os ids nos dados forem números, use Number(li.dataset.taskId) === 17. Um atributo de dados ausente fornece undefined. Atribuir li.dataset.count = 3 armazena o texto “3”.

Isso cria uma ligação útil entre um item exibido e seu objeto:

const id = Number(li.dataset.taskId);
const task = tasks.find(task => task.id === id);

A comparação agora usa dois números. Se nenhum objeto tiver esse id, find() retorna undefined; verifique antes de ler suas propriedades.

Leia o valor atual de um campo

Um <input> não contém o valor digitado como conteúdo de texto. Leia input.value, que é uma cadeia de caracteres, ou atribua-lhe um valor para alterar o campo. input.value = "" limpa o campo.

Para <input id="qty" value="1">, depois que o usuário digita 3, qty.value é “3”, mas qty.getAttribute("value") continua sendo “1”. O atributo fornece o valor inicial; a propriedade fornece o atual. Uma caixa de seleção funciona de modo semelhante: sua propriedade checked informa seu estado booleano atual, enquanto o atributo descreve o estado inicial de seleção.

Use o valor certo para cada controle

Até mesmo <input type="number"> tem um value que é uma cadeia de caracteres. Se a quantidade for “3” e cada item pesar 0,25 kg, Number(qty.value) * 0.25 fornecerá 0,75 kg. Mas qty.value + 1 fornece “31” porque + concatena uma cadeia de caracteres e um número. Um <select> retorna o valor da opção selecionada por meio de select.value. Para uma caixa de seleção, leia checkbox.checked, não checkbox.value, quando precisar saber se ela está selecionada.

Mantenha regras visuais fixas no CSS e deixe que JavaScript altere as classes que selecionam essas regras. Uma classe pode expressar um estado como “concluído”, “ativo” ou “erro” sem repetir no código as cores e decorações correspondentes.

Adicione e remova nomes individuais de classe

Suponha que a folha de estilos contenha:

.done { text-decoration: line-through; color: #888; }

item.classList.add("done") aplica a aparência de concluído. item.classList.remove("done") remove esse estado, mantendo as outras classes intactas. Ambos os métodos aceitam vários nomes; adicionar uma classe existente ou remover uma ausente não causa problemas.

contains("done") retorna um booleano. replace("wide", "narrow") troca uma classe presente por outra. toggle("active") adiciona uma classe ausente ou remove uma presente, retornando se a classe existe depois da chamada.

Acompanhe uma alteração de classe

Comece com <div class="card">:

card.classList.add("active", "wide");
const active = card.classList.toggle("active");
const replaced = card.classList.replace("wide", "narrow");

Após a primeira linha, as classes são “card active wide”. A alternância remove “active”, portanto active é false e as classes passam a ser “card wide”. Substituir “wide” deixa “card narrow” e retorna true. Uma chamada posterior a card.classList.contains("active") resulta em false.

Defina uma classe a partir de uma condição

Quando os dados fornecem o estado desejado, passe um segundo argumento:

row.classList.toggle("overdue", daysLeft < 0);

Um daysLeft negativo garante a presença da classe; caso contrário, ela fica ausente. Repetir a chamada preserva esse estado. Uma chamada simples a toggle("overdue") inverteria o estado a cada execução.

Preserve o restante do atributo de classe

className é a cadeia completa de classes. card.className = "active" substitui todas as classes existentes, incluindo “card”. Use essa atribuição quando quiser substituir o conjunto inteiro; use classList para alterar estados individuais.

Passe nomes de classes puros, sem a pontuação de seletores CSS. classList.add(".active") adiciona um nome que contém um ponto literal; essa não é a classe à qual .active corresponde. Um único argumento não pode conter espaços: classList.add("big red") lança um InvalidCharacterError. Escreva classList.add("big", "red") para duas classes.

Verifique o CSS quando a aparência não mudar

Se uma classe não tiver efeito visível, inspecione seu nome e sua regra nas DevTools. Procure uma regra ausente ou escrita incorretamente e declarações sobrepostas, riscadas no painel Estilos.

Use classes para designs fixos e estilos em linha para valores calculados. O objeto style lê e escreve declarações em linha, não todas as regras que afetam um elemento.

Escreva valores CSS por meio de style

Nomes CSS com hífens se tornam propriedades JavaScript em notação camelCase. background-color vira backgroundColor, font-size vira fontSize e z-index vira zIndex:

box.style.backgroundColor = "gold";
box.style.width = "250px";

Valores de estilo são cadeias de caracteres. Inclua uma unidade quando a propriedade exigir. Em uma página no modo padrão, a atribuição box.style.width = 250 é ignorada porque uma largura diferente de zero precisa de uma unidade CSS. A cadeia “0” é válida para uma largura zero.

style.setProperty() recebe a grafia CSS:

box.style.setProperty("background-color", "gold");
document.documentElement.style.setProperty("--accent", "#0a7d5a");

A propriedade personalizada na raiz fornece o valor às regras que fazem referência a var(--accent).

Transforme um cálculo em um valor CSS

Uma barra de progresso mostra 3 tarefas concluídas de um total de 8:

const percent = (3 / 8) * 100;
bar.style.width = `${percent}%`;

A proporção 0,375 se torna 37,5 por cento. O literal de modelo fornece “37.5%”, incluindo a unidade necessária.

Remova uma sobrescrita temporária

Defina box.style.backgroundColor = "" ou chame box.style.removeProperty("background-color") para remover essa declaração em linha. O navegador aplica então as regras restantes da folha de estilos. Use o nome CSS com hífens em removeProperty().

Tenha cuidado com style.cssText. Atribuir box.style.cssText = "color: red" substitui todo o estilo em linha, portanto uma largura em linha existente é perdida. Alterar uma propriedade de estilo mantém intactas as outras declarações em linha.

Leia o que o navegador aplica

Se uma folha de estilos deixar um parágrafo vermelho, mas ele não tiver cor em linha, p.style.color será uma cadeia de caracteres vazia. Use getComputedStyle(p).color para obter o valor aplicado, geralmente “rgb(255, 0, 0)”. Valores computados são somente de leitura; altere a classe ou a declaração em linha para mudar a aparência.

Declarações em linha têm prioridade sobre regras comuns da folha de estilos, mas declarações !important aplicáveis podem prevalecer. Se uma alteração de classe parecer não surtir efeito, verifique se há uma sobrescrita em linha remanescente.

Ocultar um painel o mantém no DOM, pronto para voltar com seu conteúdo e os valores existentes nos campos. Removê-lo o retira da árvore. Escolha a ocultação para um painel que voltará e a remoção para um item cujos dados não existem mais.

Use a propriedade hidden

panel.hidden = true adiciona o estado comum de ocultação. O estilo padrão do navegador oculta o painel sem que ele ocupe espaço no layout. panel.hidden = false remove esse estado e o revela novamente.

Uma folha de estilos pode sobrepor esse padrão. Por exemplo, .panel { display: flex; } pode tornar visível um painel oculto. Quando o estado oculto deve sempre prevalecer, inclua:

[hidden] { display: none !important; }

Outra opção é controlar a visibilidade com uma classe CSS. Com .is-hidden { display: none; }, menu.classList.toggle("is-hidden", !isOpen) adiciona a classe de ocultação quando o menu está fechado. Verifique a folha de estilos se a classe estiver presente, mas outra declaração de display prevalecer.

Compare três formas de ocultar

display: none remove o espaço do elemento no layout e o oculta dos leitores de tela. visibility: hidden torna-o invisível enquanto mantém seu espaço e também o oculta dos leitores de tela. opacity: 0 torna-o transparente, mas mantém seu espaço; ele ainda pode ser clicado e continua disponível para leitores de tela. Portanto, a transparência por si só é uma forma inadequada de fechar um painel que não deve mais estar disponível.

Esses efeitos dizem respeito à visibilidade e ao layout, não à exclusão. Um campo oculto ainda pode manter o valor digitado nele porque o mesmo objeto permanece na árvore.

Mantenha a descrição do controle sincronizada

Um botão associado a um painel expansível deve informar se ele está expandido. Defina aria-expanded como a cadeia de caracteres “true” quando estiver aberto e “false” quando estiver fechado. Baseie esse valor e a visibilidade do painel no mesmo estado.

Para um painel de resposta que começa como <div id="answer-1" hidden>, com referências chamadas answer e button, execute:

const willOpen = answer.hidden;
answer.hidden = !willOpen;
button.setAttribute("aria-expanded", String(willOpen));

Inicialmente, answer.hidden é true, portanto willOpen é verdadeiro. A atribuição define hidden como falso e mostra o painel. O atributo do botão passa a ser “true”. Executar as mesmas instruções novamente começa com hidden falso, oculta o painel e escreve “false” no atributo.

Identifique uma inconsistência

Se o botão anunciar “expandido” enquanto o painel estiver oculto, os dois valores não foram atualizados juntos. Se hidden for verdadeiro, mas o painel ainda estiver visível, inspecione seu display computado e a regra CSS responsável. O primeiro problema é um estado inconsistente da aplicação; o segundo é um estilo que se sobrepõe ao estado oculto. Ler tanto as propriedades DOM quanto o CSS aplicado permite distingui-los.

Um novo elemento não aparece apenas porque você o criou. Primeiro crie o objeto, depois forneça conteúdo e atributos e, por fim, insira-o no documento. Antes da inserção, você pode montar uma estrutura aninhada inteira na memória.

Construa um item completo

const li = document.createElement("li");
li.textContent = "Water the plants";
li.className = "task";
li.dataset.id = "4";
document.querySelector("#tasks").append(li);

createElement("li") cria um elemento vazio. As linhas seguintes o preenchem; a última o insere como o último filho da lista de tarefas existente. O resultado é <li class="task" data-id="4">Water the plants</li>. A chamada precisa de um nome de tag, não de marcação: createElement("<li>") lança um InvalidCharacterError. Defina classes e atributos após a criação.

Para conteúdo aninhado, crie separadamente um span para o título e um botão, defina seus textos e chame li.append(title, button). Depois, insira o item montado na lista. document.createTextNode("…") cria texto diretamente; passar uma cadeia de caracteres para append() também insere um nó de texto.

Escolha uma posição de inserção

• parent.append(...) adiciona depois dos filhos existentes.
• parent.prepend(...) adiciona antes dos filhos existentes.
• element.before(...) adiciona irmãos anteriores.
• element.after(...) adiciona irmãos posteriores.

Cada método aceita vários nós e cadeias de caracteres. As cadeias são tratadas como texto, portanto list.append("<li>New</li>") não constrói um item. Os sinais de menor e maior aparecem como caracteres dentro da lista.

Métodos mais antigos ainda aparecem no código. appendChild(node) aceita um nó e o retorna; não aceita uma cadeia de caracteres. append() retorna undefined. parent.insertBefore(newNode, referenceNode) insere um nó antes de um filho existente; usar null como referência adiciona ao fim.

Compreenda a diferença entre mover e copiar

Um nó pode ocupar apenas um lugar na árvore. Inserir um nó existente o move. Para uma lista na ordem a, b, c, list.prepend(list.lastElementChild) move c para o início, produzindo c, a, b. Ele não deixa um segundo c no fim.

Isso também explica um erro comum em laços: criar um <li> fora de um laço e acrescentá-lo repetidamente deixa apenas um item. Cada passagem altera e move o mesmo objeto. Crie um novo elemento dentro de cada passagem quando a página precisar de vários itens ou faça clones separados.

Insira marcação confiável ao lado do conteúdo existente

insertAdjacentHTML(position, markup) analisa HTML sem substituir os filhos existentes. Seus quatro nomes de posição são "beforebegin" e "afterend" para irmãos fora do elemento, e "afterbegin" e "beforeend" para filhos dentro dele. list.insertAdjacentHTML("beforeend", "<li>New</li>") acrescenta um item analisado. Use isso apenas para marcação confiável; texto externo deve ser inserido em textContent. insertAdjacentElement() e insertAdjacentText() usam os mesmos nomes de posição para um elemento ou texto simples.

Remover um elemento altera a árvore, mas não apaga todas as referências a esse objeto. Substituí-lo cria uma distinção semelhante: o novo objeto ocupa seu lugar, enquanto variáveis salvas ainda podem se referir ao antigo.

Remova um elemento ou várias correspondências

element.remove() desconecta esse elemento. parent.removeChild(child) é a forma mais antiga baseada no pai e retorna o nó removido. Se uma variável ainda contiver o nó, o script poderá lê-lo ou inseri-lo novamente mais tarde.

Para remover tarefas concluídas, selecione uma coleção estática e percorra-a:

document.querySelectorAll(".task.done")
  .forEach(task => task.remove());

Com cinco tarefas, duas marcadas como concluídas, restam três. Remover um elemento não altera as referências mantidas pela NodeList estática, portanto o laço visita as duas tarefas selecionadas.

Não conte em ordem crescente em uma lista dinâmica que diminui

list.children é dinâmica. Com seis filhos, um laço em ordem crescente que remove items[i] remove apenas três. Após a primeira remoção, o segundo elemento é deslocado para o índice 0, mas i avança para 1. O próximo filho original é ignorado, e o mesmo deslocamento se repete.

Faça um retrato estático antes de remover todos os filhos atuais:

Array.from(list.children).forEach(item => item.remove());

Para simplesmente esvaziar um contêiner, list.replaceChildren() é mais claro. Definir list.textContent = "" ou list.innerHTML = "" também o esvazia. Uma cadeia de caracteres vazia não analisa conteúdo externo.

Substitua um único nó ou todo o conjunto de filhos

old.replaceWith(newElement) coloca um novo nó onde estava o antigo. Para <p id="status">Loading…</p>, document.querySelector("#status").replaceWith(list) substitui a mensagem pela lista. parent.replaceChildren(a, b, c) substitui todos os filhos do pai em uma operação, mantendo o próprio pai.

Essa diferença é importante para referências salvas. Uma variável que contém o pai continua válida após replaceChildren(), mas referências aos filhos removidos agora apontam para objetos desconectados. Substituir um contêiner com replaceWith() também desconecta esse contêiner.

Copie o elemento com ou sem descendentes

element.cloneNode(true) faz uma cópia profunda, incluindo descendentes e atributos. cloneNode() ou cloneNode(false) copia o elemento e seus atributos sem seus filhos. Um item de lista clonado sem descendentes não tem o texto do item original.

Um clone começa desconectado e precisa ser inserido. Ele também herda o id do original. Dê a ele um novo id ou remova esse atributo antes de colocá-lo na mesma página, para que a seleção por id continue confiável.

Trate elementos opcionais

Se uma pesquisa puder falhar, não chame imediatamente um método em seu resultado. document.querySelector("#promo").remove() lança um erro quando não existe uma promoção. document.querySelector("#promo")?.remove() não faz nada nesse caso. Para um contêiner obrigatório, um resultado ausente é um sinal útil para verificar o seletor e o momento de execução do script antes de tentar uma atualização estrutural.

Renderização significa transformar dados em uma estrutura DOM visível. Mantenha o vetor como fonte e construa um elemento para cada objeto. Coloque os valores dos dados em textContent para que permaneçam como texto mesmo quando contiverem sinais de menor e maior.

Construa um elemento para cada objeto

Use estes objetos de livros:

const books = [
  { id: 1, title: "Dune", pages: 412 },
  { id: 2, title: "Emma", pages: 474 },
  { id: 3, title: "Beloved", pages: 324 }
];
function createBookItem(book) {
  const li = document.createElement("li");
  li.dataset.id = String(book.id);
  li.textContent = `${book.title} (${book.pages} pages)`;
  return li;
}
const list = document.querySelector("#books");
list.append(...books.map(createBookItem));

map() chama a função de construção uma vez por livro, produzindo três elementos separados. O espalhamento passa esses elementos como argumentos separados para append(). A exibição mostra “Dune (412 pages)”, “Emma (474 pages)” e “Beloved (324 pages)”. As quantidades de páginas somam 1.210.

Sem espalhamento, list.append(books.map(createBookItem)) recebe um único vetor. Ele transforma esse vetor em texto contendo cadeias como “[object HTMLLIElement]” em vez de inserir os elementos de item.

O id armazenado conecta o elemento exibido aos dados. Leia Number(li.dataset.id) antes de compará-lo com ids numéricos de livros e depois use books.find(book => book.id === id).

Trate dados ausentes e vazios

Se um campo opcional de autor estiver ausente, a interpolação direta exibirá “undefined”. Use book.author ?? "Unknown author" como alternativa quando o campo for null ou undefined. A coalescência nula mantém outros valores, incluindo 0 e uma cadeia de caracteres vazia, inalterados.

Se o vetor estiver vazio, exiba uma mensagem como “Nenhum livro ainda”. Um resultado vazio deve informar ao usuário que não há itens no momento. Ao renderizar novamente, substitua a exibição antiga para que uma mensagem ou itens anteriores não permaneçam junto ao novo resultado.

Saiba o que faz uma abordagem com cadeia HTML

Um vetor confiável pode ser mapeado para cadeias HTML, que são unidas com join("") antes da atribuição a innerHTML. A união remove as vírgulas que a conversão de vetor para cadeia de caracteres inseriria. Essa abordagem analisa cada valor interpolado como HTML. Use a abordagem de construção de elementos quando os valores puderem vir de fontes externas.

Construa uma estrutura de tabela válida

Para dados de tabela, construa um <tr> por objeto e um <td> para cada campo exibido. Acrescente as linhas ao <tbody> da tabela. Para medições de Oslo a 4,25 °C e do Cairo a 28,5 °C, a célula de temperatura pode usar reading.temp.toFixed(1): ela exibe “4.3” e “28.5”. toFixed() retorna uma cadeia de caracteres com as casas decimais solicitadas. Já toLocaleString() formata conforme a configuração regional do usuário, que pode usar vírgula decimal. Mantenha a formatação na etapa de exibição para que os dados numéricos continuem disponíveis para cálculos.

Construa as duas células antes de inserir a linha

Para um corpo de tabela vazio existente chamado tbody, isto renderiza as medições:

const readings = [{ city: "Oslo", temp: 4.25 }, { city: "Cairo", temp: 28.5 }];
const rows = readings.map(reading => {
  const row = document.createElement("tr");
  const city = document.createElement("td");
  const temperature = document.createElement("td");
  city.textContent = reading.city;
  temperature.textContent = reading.temp.toFixed(1) + " °C";
  row.append(city, temperature);
  return row;
});
tbody.replaceChildren(...rows);

Cada passagem cria uma nova linha e duas novas células. Preencher as duas células antes de acrescentar a linha mantém explícita a ordem dos campos. Espalhar rows fornece os dois nós de linha separadamente; a substituição final também remove quaisquer linhas anteriores.

Quando uma lista contém muitos itens, construa o novo conteúdo fora da página e insira-o de uma vez. Um fragmento de documento agrupa nós sem adicionar um elemento envoltório. Um template permite escrever uma estrutura repetida em HTML e preencher uma nova cópia para cada objeto.

Reúna nós em um fragmento

const fragment = document.createDocumentFragment();
for (const book of books) {
  fragment.append(createBookItem(book));
}
list.append(fragment);

O fragmento começa fora do documento. Cada novo item se torna seu filho. Acrescentar o fragmento move seus filhos para a lista na ordem existente; não insere o próprio fragmento como envoltório. Depois que 100 itens são transferidos para uma lista vazia, a lista tem 100 filhos e o fragmento tem 0.

Esse padrão agrupa a inserção e mantém o código de construção organizado. Ele não promete um ganho específico de velocidade. Um vetor de nós construídos também funciona: list.append(...items) os adiciona, enquanto list.replaceChildren(...items) substitui o conteúdo atual por eles.

Defina marcação repetida em um template

<template id="book-row">
  <li class="book"><span class="title"></span>
    (<span class="pages"></span> pages)</li>
</template>

O navegador analisa essa marcação sem exibi-la. O conteúdo fica em um DocumentFragment separado em template.content. Uma pesquisa no nível do documento não pesquisa dentro desse fragmento. Selecione o template, clone seu conteúdo e depois pesquise dentro do clone:

const template = document.querySelector("#book-row");
const clone = template.content.cloneNode(true);
clone.querySelector(".title").textContent = book.title;
clone.querySelector(".pages").textContent = book.pages;
const item = clone.firstElementChild;
list.append(clone);

O título e a quantidade de páginas são preenchidos antes da inserção. item salva uma referência ao novo <li>. Após a inserção, clone está vazio porque seus filhos foram movidos, mas item ainda se refere ao elemento inserido.

Preserve a fonte reutilizável

Acrescente uma cópia a cada vez. Chamar list.append(template.content) move os nós de origem para fora do template. Uma pesquisa posterior dentro de template.content retorna então null, e a próxima tentativa de preencher o título ausente lança um erro. O template original deve permanecer disponível para livros posteriores.

Para muitas cópias, preencha cada fragmento clonado, acrescente essas cópias a um fragmento de agrupamento e depois insira a coleção. Um fragmento pode receber os filhos de outro fragmento, assim como uma lista pode.

Escolha um método de construção legível

createElement() é adequado para uma estrutura pequena ou que varia bastante conforme o item. Um template é adequado para uma marcação repetida maior que seja mais fácil de editar como HTML. Em ambos os casos, insira valores externos como texto. Uma cadeia HTML é adequada para marcação confiável, mas a interpolação nela ainda provoca análise de HTML. Selecione o método de construção com base na estrutura que você precisa manter, preservando a mesma ordem de criar ou clonar, preencher e inserir.

Reúna cópias preenchidas para uma substituição

Usando o template de livro acima e um vetor books existente:

const group = document.createDocumentFragment();
for (const book of books) {
  const copy = template.content.cloneNode(true);
  copy.querySelector(".title").textContent = book.title;
  copy.querySelector(".pages").textContent = book.pages;
  group.append(copy);
}
list.replaceChildren(group);

Cada cópia preenchida transfere seu item para group. A última linha substitui o conteúdo da lista por esses itens e esvazia group. O template original permanece intacto durante todo o processo, portanto a função pode repetir a construção para um vetor posterior.

Use os dados como única fonte de verdade. Uma função de renderização deriva uma exibição do vetor atual. Chame-a após alterar o vetor ou um objeto nele contido.

Substitua a exibição a cada renderização

Suponha que tasks contenha quatro objetos, exatamente um concluído, e que a tarefa 2 exista e não esteja concluída. Uma função de renderização pode construir novos itens e um resumo:

function render() {
  const items = tasks.map(task => {
    const li = document.createElement("li");
    li.dataset.id = String(task.id);
    li.textContent = task.text;
    li.classList.toggle("done", task.done);
    return li;
  });
  list.replaceChildren(...items);
  const doneCount = tasks.filter(task => task.done).length;
  summary.textContent = `${doneCount} of ${tasks.length} done`;
}

Após tasks.push({ id: 5, text: "Book dentist", done: false }); render();, a lista tem cinco itens e o resumo diz “1 of 5 done”. Definir tasks.find(task => task.id === 2).done = true; render(); muda o resumo para “2 of 5 done”.

Substituir os filhos é essencial aqui. Se a função apenas acrescentasse todos os itens, chamá-la duas vezes duplicaria a exibição. Remover apenas um item do DOM também é temporário: se seu objeto permanecer no vetor, a renderização o trará de volta. Com tasks declarada usando let, exclua-o dos dados com tasks = tasks.filter(task => task.id !== id) e renderize novamente.

Derive uma visão sem perder a fonte

Para uma função de renderização que aceita um vetor de visão, passe tasks.filter(task => !task.done) para exibir apenas tarefas não concluídas. Mantenha o vetor completo para visões posteriores e contagens da lista inteira. Dê significados claros aos resumos: uma contagem de tarefas visíveis é diferente de uma contagem de todas as tarefas.

sort() altera o vetor no qual é chamado. Ordene uma cópia para exibição com [...tasks].sort(...) ou use tasks.toSorted(...) para obter uma cópia ordenada. Forneça um comparador: valores numéricos precisam de (a, b) => a - b, e títulos podem usar (a, b) => a.title.localeCompare(b.title). A ordenação padrão compara as formas de cadeia de caracteres, portanto [100, 25, 3].sort() permanece nessa ordem; a ordenação numérica fornece [3, 25, 100].

Associe ids e analise dados corretamente

Um dataset.id exibido é uma cadeia de caracteres. Converta-o antes da comparação estrita com ids numéricos, ou find() poderá retornar undefined mesmo quando o objeto desejado existir. Dados JSON são diferentes: JSON.parse() preserva números e booleanos JSON nesses tipos. Objetos analisados podem passar pela mesma função de renderização que objetos escritos diretamente no código.

Preserve o estado local quando necessário

Uma reconstrução completa cria novos elementos. Ela pode causar a perda do foco e do texto digitado em campos dentro da área reconstruída. Para uma pequena alteração de estado que precise preservar esses objetos, atualize os dados e depois atualize o item existente, como em li.classList.toggle("done", task.done). Os dados ainda precisam registrar a alteração para que uma renderização completa posterior corresponda à exibição atual.

Forneça entradas separadas para a visão e o resumo

Uma visão filtrada ainda pode mostrar um resumo de todas as tarefas:

function renderOpenTasks() {
  const visible = tasks.filter(task => !task.done);
  const nodes = visible.map(task => {
    const li = document.createElement("li");
    li.textContent = task.text;
    return li;
  });
  if (visible.length === 0) {
    const empty = document.createElement("li");
    empty.textContent = "No open tasks";
    nodes.push(empty);
  }
  list.replaceChildren(...nodes);
  const done = tasks.filter(task => task.done).length;
  summary.textContent = `${done} of ${tasks.length} done`;
}

Um vetor em que todas as tarefas estão concluídas exibe a mensagem de estado vazio para essa visão, mas mantém todos os objetos para o total. Contar a partir de visible responderia a outra pergunta e poderia indicar que não há tarefas concluídas simplesmente porque essa visão as exclui.