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

CKTIS / JavaScript

ShadowRoot — a raiz de uma árvore Shadow DOM

ShadowRoot representa a raiz de uma árvore Shadow DOM associada a um elemento anfitrião. Permite aceder à estrutura interna de um componente. Os modos open e closed diferem no acesso através de host.shadowRoot, mas nenhum deles cria uma fronteira de segurança.

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 root = host.attachShadow({ mode: "open" });
const sameRoot = host.shadowRoot;
root.append(document.createElement("span"));

ShadowRoot é a raiz de uma árvore Shadow DOM, um DocumentFragment especializado associado a um elemento anfitrião. Os seus nós internos formam uma árvore separada: host.querySelector() não os pesquisa, enquanto root.querySelector() pesquisa no seu interior. A propriedade root.host identifica o anfitrião.

Cria uma raiz com host.attachShadow({ mode: "open" }), não com new ShadowRoot(). O método devolve a raiz; no modo open, host.shadowRoot também permite aceder-lhe. No modo closed, essa propriedade devolve null, mas uma referência guardada continua a funcionar. closed restringe o acesso através dessa propriedade, mas não protege contra código não fiável.

Shadow DOM permite encapsular componentes, mas não é um documento separado nem proporciona isolamento completo dos estilos: a herança CSS continua a ser relevante. Um elemento slot pode apresentar os filhos do anfitrião sem os mover para a árvore shadow. Não é necessário registar um elemento personalizado para usar Shadow DOM num anfitrião compatível, como div.

Esta é uma API da plataforma Web, não uma funcionalidade de uma edição específica do ECMAScript. A presença de Node 24 num repositório não comprova o suporte nos navegadores. O exemplo requer um navegador com attachShadow e compara ambos os modos sem modificar a página.

Exemplos

(() => {
  const host = document.createElement("div");
  const root = host.attachShadow({ mode: "open" });
  const label = document.createElement("span");
  label.textContent = "Hello";
  root.append(label);

  console.log(root instanceof ShadowRoot);
  console.log(host.shadowRoot === root);
  console.log(root.host === host);
  console.log(root.querySelector("span").textContent);
  console.log(host.querySelector("span") === null);

  const closedHost = document.createElement("div");
  const closedRoot = closedHost.attachShadow({ mode: "closed" });
  console.log(closedHost.shadowRoot === null);
  console.log(closedRoot.host === closedHost);
})();

Resultado

true
true
true
Hello
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