CKTIS / JavaScript
Node.replaceChild — substituir um filho
Node.replaceChild substitui um filho direto de um nó pai e devolve o nó removido. O nó de substituição é fornecido como primeiro argumento.
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
const removedNode = parent.replaceChild(newChild, oldChild);parent.replaceChild(newChild, oldChild) substitui oldChild por newChild e devolve oldChild. Os argumentos têm de ser nós, não cadeias de texto. Esta é uma API do DOM, não uma funcionalidade de ECMAScript.
Se newChild já existir, é movido, não copiado. Um DocumentFragment insere os seus filhos em vez do próprio fragmento.
Uma estrutura inválida, como um ciclo, pode provocar HierarchyRequestError. O método verifica se a substituição criaria um ciclo antes de verificar se oldChild é um filho direto de parent. Se as verificações anteriores não detetarem erros e oldChild não for um filho direto de parent, o método lança a exceção NotFoundError.
Exemplos
const parent = document.createElement('div');
const oldChild = document.createTextNode('old');
const newChild = document.createTextNode('new');
parent.appendChild(oldChild);
const removedNode = parent.replaceChild(newChild, oldChild);
console.log(parent.textContent);
console.log(removedNode === oldChild);
console.log(oldChild.parentNode === null);Resultado
new true true
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.