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

CKTIS / JavaScript

Element.attachShadow — anexar uma árvore Shadow DOM

Element.attachShadow() anexa uma raiz Shadow DOM a um elemento suportado e devolve um ShadowRoot. O modo obrigatório, open ou closed, controla o acesso através de host.shadowRoot, mas não constitui uma barreira 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 = element.attachShadow({ mode: "open" });

Element.attachShadow() cria uma árvore Shadow DOM associada a um elemento anfitrião e devolve o respetivo ShadowRoot. Trata-se de uma árvore separada: os seus nós não se tornam filhos normais do anfitrião. Por isso, host.querySelector() não pesquisa no seu interior; chama o método na raiz devolvida.

A opção mode é obrigatória. Com "open", host.shadowRoot expõe a raiz; com "closed", devolve null. Em ambos os modos, attachShadow() devolve a raiz, pelo que uma referência guardada continua a permitir modificá-la. "closed" não protege dados confidenciais.

Nem todos os elementos podem ser anfitriões: div é suportado, mas input, por exemplo, não. Um anfitrião não suportado ou uma nova anexação a uma raiz normal já existente causa NotSupportedError. Uma raiz declarativa existente é uma exceção: um mode correspondente permite reutilizá-la, mas limpa o seu conteúdo; um modo diferente causa um erro.

Esta é uma API DOM do browser, não uma funcionalidade de uma edição específica de ECMAScript. Verifique typeof Element.prototype.attachShadow === "function" no browser de destino; este teste não comprova o suporte de todas as opções adicionais. A presença de Node 24 no repositório não comprova o suporte desta API.

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(host.shadowRoot === root);
  console.log(host.querySelector("span") === null);
  console.log(root.querySelector("span").textContent);
})();

Resultado

true
true
Hello

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