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

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.

Fontes