Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

Element.replaceChildren() — substituir todos os nós filhos

Element.replaceChildren() substitui os nós filhos de um elemento pelos nós e cadeias de caracteres fornecidos como argumentos. Se for chamada sem argumentos, remove todos os nós filhos.

Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Sintaxe

element.replaceChildren(...nodes)

Element.replaceChildren faz parte do mixin ParentNode da norma DOM, não do ECMAScript. Substitui todos os nós filhos de um elemento, incluindo os nós de texto, mantendo o próprio elemento intacto. Devolve undefined.

Os argumentos são nós ou cadeias de caracteres e são processados pela ordem em que são fornecidos. As cadeias tornam-se nós Text; não são interpretadas como HTML. Os nós existentes são movidos, não clonados. Se o mesmo nó for passado novamente, é movido em vez de se acrescentar outro nó filho. Se a e b forem elementos distintos, após element.replaceChildren(a, b, a) ficam b e a, por esta ordem. element.replaceChildren() remove todos os nós filhos.

Uma hierarquia inválida, como inserir um elemento dentro de si próprio, lança uma DOMException com o nome HierarchyRequestError.

Esta é uma API do DOM dos browsers; ter Node 24 não prova que esteja disponível. Verifique typeof Element !== 'undefined' && typeof Element.prototype.replaceChildren === 'function' no ambiente de destino.

Exemplos

const box = document.createElement('div');
box.textContent = 'Old';
const label = document.createElement('strong');
label.textContent = 'New';

box.replaceChildren('Status: ', label);
console.log(box.textContent);
console.log(box.childNodes.length);
console.log(box.lastChild === label);

box.replaceChildren();
console.log(box.childNodes.length);

Resultado

Status: New
2
true
0

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes