attachShadow y Shadow Root

Shadow DOM proporciona a un elemento su propio árbol DOM aislado (el "árbol shadow"), que no aparece en el DOM principal de la página. El CSS externo no se filtra hacia dentro y el CSS interno no se filtra hacia fuera: es una encapsulación perfecta para los componentes.

Llame a this.attachShadow({ mode: "open" }) desde el constructor o connectedCallback de un elemento personalizado. El método devuelve un ShadowRoot, que puede rellenar como un árbol DOM normal mediante innerHTML, appendChild, etc.

mode: "open" expone el árbol shadow como element.shadowRoot. mode: "closed" lo oculta: element.shadowRoot devuelve null, por lo que los scripts externos no pueden entrar en el árbol. En la práctica, el modo cerrado rara vez resulta útil, porque el mismo código que definió el elemento puede conservar su propia referencia.

Los estilos definidos dentro del árbol shadow (mediante <style> u hojas de estilo adoptadas) solo se aplican dentro de ese árbol shadow. Los selectores CSS del documento principal nunca coinciden con los descendientes del árbol shadow, y sus estilos nunca salen al documento.

Desde dentro del árbol shadow, el elemento host (el propio elemento personalizado) se selecciona con la pseudoclase especial :host. :host(.large) coincide cuando el host tiene la clase .large; :host([disabled]) coincide cuando el host tiene el atributo disabled.

Los elementos personalizados tienen de forma predeterminada display: inline. Dentro de la raíz shadow, aplique :host { display: block } para que el elemento se comporte como un componente de nivel de bloque. Olvidarlo es una causa común de errores en los que "se ignora mi width: 100%".

Los eventos que emergen del árbol shadow se redirigen al host. Un clic en un botón interno llega a los escuchadores externos con event.target === host. Use event.composedPath() para ver el destino interno real si lo necesita.

Los eventos personalizados enviados dentro de la raíz de Shadow DOM no atraviesan el límite a menos que los cree con bubbles: true y composed: true. Sin composed, los listeners externos del host nunca ven el evento.

Los scripts externos pueden consultar el elemento host, pero no sus descendientes shadow. document.querySelector("my-card span") no devuelve nada si el <span> vive dentro del árbol shadow. La encapsulación protege los elementos internos frente al acoplamiento accidental.

Con <template shadowrootmode="open"> dentro del HTML de un elemento, el navegador construye el árbol shadow durante el análisis, sin JavaScript. Esto facilita la hidratación de los componentes renderizados en el servidor, porque el árbol shadow existe antes de que se ejecute JavaScript.

Cada raíz shadow tiene cierta sobrecarga: un ámbito de estilos adicional y una capa de renderizado adicional. Cientos de raíces shadow no suponen un problema; decenas de miles pueden ser relevantes. En interfaces de usuario de muy alta densidad (tablas grandes, listas virtualizadas), realice un perfil de rendimiento para confirmar que los costes de Shadow DOM son aceptables.

¿Qué hace el modo open que no hace el modo closed?

attachShadow({ mode: "open" }) crea un subárbol DOM aislado en el que CSS e IDs no se filtran en ninguna dirección. Aplique estilos al host con :host, recuerde display: block y use composed: true para los eventos que deban salir. Por lo demás, el árbol shadow se comporta como un DOM normal: innerHTML, appendChild y querySelector funcionan con normalidad dentro de él.