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

CKTIS / JavaScript

Element.replaceChildren() e Element.className

Substitui ou remove todos os nós filhos de um elemento e lê ou define o valor completo do seu atributo `class` sem alterar esses nós.

Versão: Current web platform; runtime support varies

Sintaxe

element.replaceChildren();
element.replaceChildren(node, "text");
element.replaceChildren(...items); // Spread an iterable of nodes and/or strings.
const classes = element.className; // Read the class attribute of an HTML element.
element.className = "panel ready"; // Replace the entire class attribute value.

element.replaceChildren(...items) substitui todos os nós filhos diretos, incluindo os nós de texto, e devolve undefined. A mesma chamada aceita qualquer número de objetos Node e cadeias de caracteres. As cadeias tornam-se nós de texto e não são interpretadas como HTML. Sem argumentos, a chamada esvazia o elemento sem o remover nem alterar os seus atributos.

Os nós existentes são movidos, não clonados. Um nó desligado da árvore pode ser reutilizado se mantiveres uma referência a ele. Violar uma regra da árvore DOM, por exemplo ao tentar inserir um antepassado como filho do elemento, lança uma DOMException com o nome HierarchyRequestError.

Num elemento HTML, a propriedade element.className reflete o atributo class como uma cadeia de nomes de classes separados por caracteres de espaço em branco. Uma atribuição substitui o valor completo sem alterar os nós filhos. Para alterar classes individuais sem substituir as restantes, usa classList.add(), classList.remove() ou classList.toggle(). Em elementos SVG, className pode ser um objeto SVGAnimatedString; usa getAttribute('class') ou setAttribute('class', value) para ler ou escrever o próprio atributo.

Na indicação de versão, ECMAScript 2024 refere-se apenas à versão de referência da linguagem JavaScript. Estas API do DOM pertencem à plataforma Web, não ao ECMAScript 2024. A disponibilidade depende do ambiente de execução; um ambiente sem DOM não as disponibiliza por si só.

Exemplos

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Element.replaceChildren() and Element.className</title>
</head>
<body>
<script>
{
  const panel = document.createElement("div");
  panel.className = "panel loading";
  panel.textContent = "Loading…";

  const label = document.createElement("span");
  label.textContent = "Ready";
  panel.replaceChildren(label, " <pending>");
  panel.className = "panel ready";
  console.log(`${panel.childNodes.length} | ${panel.textContent} | ${panel.className}`);

  panel.replaceChildren();
  console.log(`${panel.childNodes.length} | ${panel.className}`);
}
</script>
</body>
</html>

Resultado

2 | Ready <pending> | panel ready
0 | panel ready

Guarda o exemplo como ficheiro HTML, abre-o num navegador e consulta a consola do navegador. A primeira linha mostra dois nós filhos: o elemento `span` e o texto literal ` <pending>`. A segunda mostra que, depois de remover os filhos, o atributo `class` mantém o valor `panel ready`.

Lições relacionadas

  • JavaScript · Lição 43 · Intermédio · Versão: 3

Fontes