NodeList vs HTMLCollection: Coleções Estáticas vs Vivas (Live) e Métodos de Iteração
Elimine de uma vez por todas as dúvidas sobre as duas estruturas nativas de agrupamento do DOM: compreenda a fundo o confronto entre NodeList e HTMLCollection, descubra quando uma coleção é viva (live) ou estática (snapshot), domine os métodos seguros de iteração e aprenda como manipular listas de elementos sem cair em armadilhas de mutação concorrente.
📑 Índice do Conteúdo
1. O Duelo das Coleções: Por Que Existem Duas Estruturas no DOM?
Ao contrário de coleções normais do JavaScript que retornam instâncias padrão de Array, o Document Object Model possui seus próprios tipos de coleções de objetos: a HTMLCollection e a NodeList. Essa duplicidade surgiu da evolução histórica das especificações da W3C nos anos 90 e 2000:
- HTMLCollection: Criada no DOM Level 1 (1998) com o objetivo exclusivo de agrupar elementos HTML (tags como
<div>,<a>e<input>). Ela é sempre viva (live) e contém apenas nós do tipoElement(nodeType 1). - NodeList: Criada como uma estrutura mais abrangente e genérica, capaz de armazenar qualquer tipo de nó da árvore (elementos, nós de texto puro com quebras de linha e comentários). Dependendo do método que a gerou, ela pode ser viva ou estática.
2. Quadro Comparativo: HTMLCollection versus NodeList
| Característica | HTMLCollection | NodeList |
|---|---|---|
| Tipos de Nós Aceitos | Apenas nós do tipo Element (tags HTML). |
Qualquer nó da árvore (Element, Text, Comment). |
| Origem Típica | getElementsByClassName, getElementsByTagName, element.children. |
querySelectorAll, element.childNodes. |
| Método `.forEach()` Nativo | ❌ Não possui (lança TypeError). |
✅ Possui nativamente no protótipo. |
| Acesso por ID / Nome (namedItem) | ✅ Suporta colecao.namedItem("meuId") ou colecao["meuId"]. |
❌ Não suporta (apenas índices numéricos). |
| Iteração com `for…of` | ✅ Suporta (implementa Symbol.iterator). |
✅ Suporta (implementa Symbol.iterator). |
3. O Mapa de Ouro da Vitalidade: Quem é Vivo e Quem é Estático?
Um dos mitos mais comuns no desenvolvimento web é acreditar que “HTMLCollection é sempre viva e NodeList é sempre estática”. Isso é uma meia-verdade perigosa! A vitalidade depende estritamente do método que originou a coleção:
element.getElementsByTagName():Retorna HTMLCollection VIVA (Live).element.getElementsByClassName():Retorna HTMLCollection VIVA (Live).element.children:Retorna HTMLCollection VIVA (Live).element.childNodes:Retorna NodeList VIVA (Live)! (Atenção: mutações no DOM alteram childNodes automaticamente!)element.querySelectorAll():Retorna NodeList ESTÁTICA (Static Snapshot). (Congelada no tempo, imune a mutações externas!)
4. Métodos de Iteração e a Armadilha da Mutação Concorrente
Iterar sobre uma coleção viva enquanto você modifica o DOM é uma das causas mais comuns de bugs invisíveis em JavaScript:
// ❌ ARMADILHA: Loop clássico sobre coleção viva excluindo itens
const caixas = document.getElementsByClassName("caixa");
for (let i = 0; i < caixas.length; i++) {
// Quando você remove a primeira caixa do DOM, caixas.length diminui de 4 para 3!
// Na próxima iteração, i valerá 1, o que significa que o segundo item foi PULADO!
caixas[i].remove();
}
Como Resolver a Mutação com Segurança
Existem duas estratégias elegantes de engenharia para resolver essa questão:
- Estratégia A: Iterar de trás para frente: Como o índice final diminui, os elementos anteriores não sofrem deslocamento:
for (let i = caixas.length - 1; i >= 0; i--) { caixas[i].remove(); } - Estratégia B: Converter para Array real (Recomendado): Desacopla a coleção do DOM e cria uma lista imutável em memória com acesso a todos os métodos funcionais:
const caixasArray = [...caixas]; // ou Array.from(caixas) caixasArray.forEach(caixa => caixa.remove());
5. Por Que Preferir `Array.from()` e o Spread Operator?
Mesmo que a NodeList possua o método .forEach() nativo, ela ainda não possui os métodos essenciais de transformação funcional de dados como .map(), .filter(), .find() e .reduce(). Ao converter qualquer coleção do DOM para um Array legítimo, seu código ganha poder declarativo e legibilidade corporativa incomparáveis.
nodelist-vs-htmlcollection.js
// =====================================================================
// LAB: BATALHA PRÁTICA: NODELIST (ESTÁTICA/VIVA) vs HTMLCOLLECTION (VIVA)
// =====================================================================
console.log("=== LABORATÓRIO: NODELIST vs HTMLCOLLECTION ===");
// 1. Criando um ambiente de teste com 3 itens
const listaContainer = document.createElement("ul");
listaContainer.id = "lista-teste";
listaContainer.innerHTML = `
<li class="item" id="item-alpha">Item Alfa</li>
<li class="item" id="item-beta">Item Beta</li>
<li class="item" id="item-gama">Item Gama</li>
`;
document.body.appendChild(listaContainer);
// 2. Capturando as coleções através das duas famílias de métodos
const colecaoViva = listaContainer.getElementsByClassName("item"); // HTMLCollection (Viva)
const snapshotEstatico = listaContainer.querySelectorAll(".item"); // NodeList (Estática)
const noFilhosVivos = listaContainer.childNodes; // NodeList (VIVA!)
console.log("1. Estado Inicial das Coleções:");
console.log(" - HTMLCollection viva (getElementsByClassName):", colecaoViva.length); // 3
console.log(" - NodeList estática (querySelectorAll):", snapshotEstatico.length); // 3
console.log(" - NodeList viva (childNodes, inclui espaços):", noFilhosVivos.length); // 7
// 3. Mutação: Inserindo um novo elemento no DOM
console.log("n2. Executando Mutação: Inserindo Item Delta...");
const novoItem = document.createElement("li");
novoItem.className = "item";
novoItem.id = "item-delta";
novoItem.textContent = "Item Delta";
listaContainer.appendChild(novoItem);
console.log("n--- RESULTADO APÓS A MUTAÇÃO DO DOM ---");
console.log(" - HTMLCollection viva atualizou-se?", colecaoViva.length); // 4 (SIM! VIVA)
console.log(" - NodeList viva (childNodes) atualizou-se?", noFilhosVivos.length); // 8 (SIM! VIVA)
console.log(" - NodeList estática (querySelectorAll) mudou?", snapshotEstatico.length); // 3 (NÃO! CONGELADA)
// 4. Testando NamedItem na HTMLCollection
console.log("n3. Acesso por ID direto na HTMLCollection:");
console.log(" - Buscando 'item-beta' diretamente:", colecaoViva["item-beta"]?.textContent);
// 5. Conversão Segura para Array e Aplicação de Métodos Funcionais
console.log("n4. Transformação Funcional via Array.from():");
const titulosItens = Array.from(colecaoViva).map(el => el.textContent.toUpperCase());
console.log("Array resultante com .map():", titulosItens);
Aplique o que você aprendeu nesta lição
Utilize nossas ferramentas online gratuitas para experimentar os conceitos ou teste o código ao vivo no Playground IDE.
Editor de Códigos Web Online
Ambiente com destaque de sintaxe para você testar tags, tabelas e scripts na hora.
Abrir Ferramenta OnlinePlayground Web Online
Escreva seu código HTML, CSS ou JavaScript e veja o resultado renderizado ao vivo no navegador com zero configuração.
⚡ Codificar no Playground IDE