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

CKTIS / JavaScript

Element.replaceWith — substituir um elemento

Element.replaceWith substitui um elemento no interior do respetivo elemento-pai por nós e texto. As cadeias de caracteres tornam-se texto, não marcação HTML.

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.replaceWith(...nodes)

Element.replaceWith faz parte do mixin ChildNode da norma DOM, não de uma edição de ECMAScript. A chamada element.replaceWith(...nodes) substitui o próprio elemento, não os seus filhos; replaceChildren(...nodes) altera os filhos.

Os argumentos são nós e cadeias de caracteres, pela ordem indicada. Os nós são movidos, não copiados; as cadeias criam nós Text sem analisar HTML. O método devolve undefined. Uma chamada sem argumentos remove o elemento; se este não tiver elemento-pai, não altera nada.

Uma estrutura de árvore inválida pode causar HierarchyRequestError. Verifique a disponibilidade com typeof Element.prototype.replaceWith === 'function' num ambiente DOM; a versão de Node.js, por si só, não confirma que existe suporte.

Exemplos

const container = document.createElement('div');
const oldElement = document.createElement('span');
oldElement.textContent = 'old';
container.appendChild(oldElement);

const replacement = document.createElement('strong');
replacement.textContent = 'new';
const result = oldElement.replaceWith(replacement, ' <text>');

console.log(container.textContent);
console.log(container.firstChild === replacement);
console.log(oldElement.parentNode === null);
console.log(result === undefined);

Resultado

new <text>
true
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