attachShadow e raiz de sombra

O DOM isolado fornece ao elemento sua própria árvore DOM, a “árvore isolada”, que não aparece no DOM principal da página. O CSS externo não entra nela e o CSS interno não sai — é um encapsulamento perfeito para componentes.

Chame this.attachShadow({ mode: "open" }) no construtor ou em connectedCallback de um elemento personalizado. O método retorna um ShadowRoot, que o senhor pode preencher como uma árvore DOM comum usando innerHTML, appendChild etc.

mode: "open" expõe a árvore isolada como element.shadowRoot. mode: "closed" a oculta — element.shadowRoot retorna nulo, portanto scripts externos não podem entrar na árvore. O modo fechado raramente é útil na prática, porque o mesmo código que definiu o elemento pode manter sua própria referência.

Os estilos definidos dentro da árvore isolada, por meio de <style> ou de folhas de estilo adotadas, aplicam-se somente dentro dessa árvore. Os seletores CSS do documento principal nunca correspondem aos descendentes isolados, e os estilos da árvore isolada nunca atravessam para o documento.

Dentro da árvore isolada, o elemento hospedeiro, que é o próprio elemento personalizado, é selecionado com a pseudoclasse especial :host. :host(.large) corresponde quando o hospedeiro tem a classe .large; :host([disabled]) corresponde quando o hospedeiro tem o atributo disabled.

Por padrão, os elementos personalizados usam display: inline. Dentro da raiz isolada, aplique :host { display: block } para que o elemento se comporte como um componente em nível de bloco. Esquecer isso é uma causa comum de erros em que “minha largura de 100% está sendo ignorada”.

Os eventos que se propagam para fora da árvore isolada têm o alvo redefinido no elemento hospedeiro. Um clique em um botão interno chega aos ouvintes externos com event.target === host. Use event.composedPath() para ver o alvo interno real, se necessário.

Eventos personalizados despachados dentro da raiz de sombra não atravessam o limite a menos que sejam criados com bubbles: true e composed: true. Sem composed, os ouvintes externos no elemento hospedeiro nunca veem o evento.

Os scripts externos podem consultar o elemento hospedeiro, mas não seus descendentes da sombra. document.querySelector("my-card span") não retorna nada se o <span> estiver dentro da árvore de sombra. O encapsulamento protege os elementos internos contra acoplamentos acidentais.

Com <template shadowrootmode="open"> dentro do HTML de um elemento, o navegador constrói a árvore de sombra durante a análise, sem JavaScript. Isso torna os componentes renderizados no servidor compatíveis com hidratação, pois a árvore de sombra existe antes da execução do JS.

Cada raiz de sombra tem um custo adicional — um escopo de estilos extra e uma camada de renderização extra. Centenas de raízes de sombra funcionam bem; dezenas de milhares podem fazer diferença. Em interfaces de usuário de densidade muito alta (tabelas grandes e listas virtualizadas), faça uma análise de desempenho para confirmar que os custos do DOM de sombra são aceitáveis.

O que o modo aberto faz que o modo fechado não faz?

attachShadow({ mode: "open" }) cria uma subárvore DOM isolada, na qual CSS e IDs não vazam em nenhuma direção. Estilize o elemento hospedeiro com :host, lembre-se de display: block e use composed: true para eventos que precisam escapar. Fora isso, a árvore de sombra se comporta como um DOM comum — innerHTML, appendChild e querySelector funcionam normalmente dentro dela.