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

CKTIS / JavaScript

ShadowRoot.append — adicionar nós e texto a uma árvore shadow

ShadowRoot.append adiciona nós e texto no fim de uma árvore shadow. É herdado de DocumentFragment, não sendo uma implementação separada. Saiba como os nós são movidos, como um fragmento fica vazio e em que difere de appendChild().

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

shadowRoot.append(...nodesOrStrings);
fragment.append(...nodesOrStrings);

ShadowRoot.append é o método herdado DocumentFragment.append: ShadowRoot herda de DocumentFragment. A chamada root.append(...) adiciona conteúdo depois do último filho da raiz shadow, e não aos filhos normais do elemento anfitrião. Um fragmento normal serve, em vez disso, para preparar uma subárvore antes de a inserir no destino.

O método aceita vários nós e cadeias de caracteres, pela ordem dos argumentos. As cadeias tornam-se nós Text; não são analisadas como HTML. Um nó existente é movido, não copiado. Ao passar um DocumentFragment normal, os respetivos filhos são movidos e o fragmento fica vazio; o próprio fragmento não se torna filho da raiz.

O resultado é undefined. Ao contrário de append(), appendChild() aceita um único nó, não suporta diretamente cadeias de caracteres como argumentos e devolve o nó adicionado ou o fragmento esvaziado. Uma inserção inválida, como uma que crie um ciclo, pode lançar uma DOMException HierarchyRequestError.

Esta é uma API do DOM, não uma funcionalidade de uma edição específica de ECMAScript. A MDN assinala DocumentFragment.append() como amplamente disponível nos browsers desde abril de 2018; a sua utilização numa raiz shadow também requer suporte de Shadow DOM. A presença de Node 24 num repositório, por si só, não comprova o suporte destas APIs de browser.

Exemplos

(() => {
  const host = document.createElement("div");
  const root = host.attachShadow({ mode: "open" });
  const fragment = document.createDocumentFragment();
  const label = document.createElement("strong");
  label.textContent = "DOM";

  fragment.append("Hello ", label);
  const result = root.append(fragment, "!");

  console.log(root.textContent);
  console.log(root.childNodes.length);
  console.log(fragment.childNodes.length);
  console.log(label.parentNode === root);
  console.log(host.childNodes.length);
  console.log(result === undefined);
})();

Resultado

Hello DOM!
3
0
true
0
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