JavaScript Modificando o documento
Aprenda a modificar o DOM com JavaScript: criar, inserir, substituir e remover nós, usar insertAdjacentHTML, textContent vs innerHTML e DocumentFragment.
O JavaScript permite alterar uma página depois que ela foi carregada: adicionar novos elementos, movê-los, atualizar texto, trocar atributos e remover o que o usuário não precisa mais. Esta é a base de toda interface dinâmica — desde exibir uma mensagem de validação até renderizar uma lista completa de resultados de busca.
Esta página cobre o conjunto de ferramentas práticas para modificar o DOM: criar e inserir nós, a diferença entre textContent e innerHTML, inserção rápida de HTML com insertAdjacentHTML, remover e substituir nós, e usar um DocumentFragment para manter as atualizações rápidas. Para encontrar os elementos que você deseja alterar primeiro, consulte Buscando: getElement* e querySelector*. Para ter uma visão mais ampla de como a página é estruturada como uma árvore de nós, consulte Entendendo os nós do DOM.
Criando novos nós
Antes de inserir algo na página, é preciso criá-lo. Existem dois blocos de construção: nós de elemento (<div>, <li>, …) e nós de texto (texto simples).
Criando elementos
Novos elementos são criados com o método document.createElement(tag). O elemento existe apenas na memória até ser inserido no documento — até então o usuário não vê nada. Veja como criar um div e adicioná-lo à página:
<body></body>
<script>
let div = document.createElement('div');
div.innerHTML = "Hello, world!";
document.body.appendChild(div);
</script>O elemento só aparece quando appendChild (ou outro método de inserção) o conecta a um nó que já está no documento.
Criando nós de texto
Para adicionar texto simples, use document.createTextNode(text). Ao contrário de innerHTML, um nó de texto trata seu conteúdo literalmente — <b> permanece como os caracteres <b> em vez de se tornar uma tag de negrito. Isso torna os nós de texto a escolha segura quando o texto vem de um usuário ou de qualquer fonte não confiável:
<body>
<div id="container"></div>
</body>
<script>
const div = document.getElementById("container");
let textNode = document.createTextNode('Here is some text');
div.appendChild(textNode);
</script>Inserindo nós
Uma vez que um nó existe, você precisa posicioná-lo em algum lugar. O método clássico é parent.appendChild(node), que adiciona o nó como o último filho. Os navegadores modernos também fornecem uma família de métodos mais flexíveis que aceitam nós ou strings:
| Método | Onde insere |
|---|---|
node.append(...) | No final, dentro de node |
node.prepend(...) | No início, dentro de node |
node.before(...) | Logo antes de node |
node.after(...) | Logo após node |
node.replaceWith(...) | Substitui node completamente |
Aqui append e prepend adicionam itens de lista nas extremidades opostas de um <ul>:
<body>
<ul id="list">
<li>middle</li>
</ul>
</body>
<script>
const list = document.getElementById("list");
const first = document.createElement("li");
first.textContent = "first";
list.prepend(first);
const last = document.createElement("li");
last.textContent = "last";
list.append(last);
</script>insertAdjacentHTML
Quando você deseja inserir uma string de HTML em relação a um elemento — sem perturbar o conteúdo existente — element.insertAdjacentHTML(position, html) é a ferramenta ideal. O argumento position é uma das quatro palavras-chave:
"beforebegin"— antes do próprio elemento"afterbegin"— dentro, antes do primeiro filho"beforeend"— dentro, após o último filho"afterend"— após o próprio elemento
<body>
<div id="box">existing content</div>
</body>
<script>
const box = document.getElementById("box");
box.insertAdjacentHTML("beforeend", "<p>added inside, at the end</p>");
box.insertAdjacentHTML("afterend", "<p>added after the box</p>");
</script>Como insertAdjacentHTML analisa uma string HTML, nunca passe entradas não confiáveis a ela — o mesmo risco de XSS se aplica como com innerHTML. Existem métodos irmãos insertAdjacentText e insertAdjacentElement para inserir texto simples ou um nó existente nas mesmas posições.
textContent vs innerHTML
Ambas as propriedades definem o conteúdo de um elemento, mas se comportam de maneira muito diferente:
innerHTMLanalisa a string como HTML.el.innerHTML = "<b>Hi</b>"produz um nó em negrito. Atribuir a ela substitui todos os filhos existentes.textContenttrata a string como texto simples.el.textContent = "<b>Hi</b>"exibe os caracteres literais<b>Hi</b>.
Prefira textContent sempre que estiver inserindo texto — é mais rápido e imune à injeção de HTML/script. Use innerHTML apenas quando você realmente precisa de marcação e a fonte é confiável.
<body>
<div id="asHtml"></div>
<div id="asText"></div>
</body>
<script>
const input = "<b>3 < 5</b>";
document.getElementById("asHtml").innerHTML = input; // renders bold text
document.getElementById("asText").textContent = input; // shows the literal markup
</script>Modificando elementos
Alterando atributos
Para alterar um atributo de um elemento, você pode usar element.setAttribute(name, value). Este método permite definir o valor de um atributo no elemento especificado.
<body>
<div id="firstID"></div>
<div>new id is: <span id="result"></span></div>
</body>
<script>
const div = document.getElementById("firstID");
const result = document.getElementById("result");
div.setAttribute("id", "newDiv");
result.innerHTML = div.id;
</script>Para uma análise mais aprofundada da distinção entre atributos HTML e propriedades do DOM (e quando usar setAttribute em vez do acesso direto à propriedade como el.id = "..."), consulte Atributos e propriedades.
Manipulações avançadas
Clonando elementos
Você pode criar uma cópia de um elemento usando o método element.cloneNode(deep). Definir deep como true clona o elemento e seus descendentes.
<body>
<div id="mydiv">one div here, or two divs if cloned! <span>And here is a span inside the div!</span></div>
</body>
<script>
const div = document.getElementById("mydiv");
const clone = div.cloneNode(true);
document.body.appendChild(clone);
</script>Substituindo elementos
Para trocar um nó por outro, chame element.replaceWith(newNode). O nó antigo sai do documento e o novo ocupa seu lugar:
<body>
<p id="old">I will be replaced.</p>
</body>
<script>
const old = document.getElementById("old");
const fresh = document.createElement("p");
fresh.textContent = "I am the replacement.";
old.replaceWith(fresh);
</script>Removendo elementos
Para remover um elemento do DOM, você pode usar element.remove().
<body>
<div>It's the only thing you see, as the next div is removed!</div>
<div id="mydiv">you don't see me if I'm removed!</div>
</body>
<script>
const div = document.getElementById("mydiv");
div.remove();
</script>Agrupando atualizações com um DocumentFragment
Cada vez que você insere um nó no documento ativo, o navegador pode recalcular o layout. Inserir muitos nós em um loop, um de cada vez, pode portanto ser lento. Um DocumentFragment é um contêiner leve e fora da tela: você monta todos os seus nós dentro dele e, em seguida, insere o fragmento uma única vez. Apenas seus filhos acabam no DOM — o fragmento em si desaparece.
<body>
<ul id="list"></ul>
</body>
<script>
const list = document.getElementById("list");
const fragment = document.createDocumentFragment();
for (let i = 1; i <= 5; i++) {
const li = document.createElement("li");
li.textContent = "Item " + i;
fragment.appendChild(li);
}
// One single insertion into the live document
list.appendChild(fragment);
</script>Para mais formas de manter as atualizações do DOM eficientes, consulte Otimização de desempenho do DOM. Se a sua marcação for reutilizável, o elemento <template> é outra forma rápida de clonar estruturas prontas.
Exemplo prático: construindo uma lista de tarefas
Vamos aplicar esses conceitos para criar uma lista de tarefas simples com JavaScript:
<body></body>
<script>
// Creating the list container
let list = document.createElement('ul');
document.body.appendChild(list);
// Adding items to the list
function addItem(text) {
let item = document.createElement('li');
item.textContent = text;
list.appendChild(item);
}
addItem('Learn JavaScript');
addItem('Build a to-do list');
</script>Conclusão
Modificar o documento é o núcleo de toda interface dinâmica: crie nós com createElement/createTextNode, posicione-os com append/prepend/before/after ou insertAdjacentHTML, escolha textContent para texto seguro e innerHTML apenas para marcação confiável, e use um DocumentFragment para manter atualizações em massa rápidas. Use replaceWith e remove para trocar ou remover nós.
Para ir além, explore Manipulação do DOM para uma visão geral mais ampla, Percorrendo o DOM para navegar entre nós relacionados, e Propriedades de nó: tipo, tag e conteúdo para entender o que cada nó contém.