attachShadow e Shadow Root

Lo Shadow DOM assegna a un elemento un proprio albero DOM isolato (lo "shadow tree") che non compare nel DOM principale della pagina. Il CSS esterno non penetra all'interno e quello interno non fuoriesce: è l'incapsulamento perfetto per i componenti.

Chiami this.attachShadow({ mode: "open" }) dal costruttore di un custom element o da connectedCallback. Il metodo restituisce una ShadowRoot, che può popolare proprio come un normale albero DOM usando innerHTML, appendChild e così via.

mode: "open" espone l'albero shadow come element.shadowRoot. mode: "closed" lo nasconde: element.shadowRoot restituisce null, quindi gli script esterni non possono accedere all'albero. La modalità closed è raramente utile in pratica, perché lo stesso codice che ha definito l'elemento può comunque conservarne un riferimento.

Gli stili definiti all'interno dell'albero shadow, tramite <style> o fogli di stile adottati, si applicano solo a quell'albero shadow. I selettori CSS del documento principale non corrispondono mai ai discendenti shadow e gli stili dello shadow non si propagano al documento.

Dall'interno dell'albero shadow, l'elemento host, cioè il custom element stesso, viene selezionato con la pseudo-classe speciale :host. :host(.large) corrisponde quando l'host ha la classe .large; :host([disabled]) corrisponde quando l'host ha l'attributo disabled.

Per impostazione predefinita, i custom element hanno display: inline. All'interno dello shadow root, applichi :host { display: block } in modo che l'elemento si comporti come un componente a livello di blocco. Dimenticarlo è una causa comune dei problemi in cui "il mio width: 100% viene ignorato".

Gli eventi che risalgono dall'albero shadow vengono reindirizzati sull'host. Un click su un pulsante interno arriva ai listener esterni con event.target === host. Usi event.composedPath() per vedere il vero target interno quando ne ha bisogno.

Gli eventi personalizzati inviati all'interno dello shadow root non attraversano il confine, a meno che non vengano creati con entrambi bubbles: true e composed: true. Senza composed, i listener esterni sull'host non vedranno mai l'evento.

Gli script esterni possono interrogare l'elemento host, ma non i suoi discendenti nello shadow tree. document.querySelector("my-card span") non restituisce nulla se si trova all'interno dello shadow tree. L'incapsulamento protegge gli elementi interni da accoppiamenti accidentali.

Con <template shadowrootmode="open"> all'interno dell'HTML di un elemento, il browser crea lo shadow tree durante il parsing, senza JavaScript. Questo rende i componenti sottoposti a rendering lato server compatibili con l'hydration, perché lo shadow tree esiste prima dell'esecuzione del JavaScript.

Ogni shadow root comporta un costo: un ambito aggiuntivo per gli stili e un ulteriore livello di rendering. Centinaia di shadow root non rappresentano un problema; decine di migliaia possono incidere. Per interfacce con densità molto elevata, come tabelle grandi ed elenchi virtualizzati, esegua il profiling per verificare che i costi dello shadow DOM siano accettabili.

Che cosa offre la modalità open che la modalità closed non offre?

attachShadow({ mode: "open" }) crea un sottoalbero DOM isolato, in cui CSS e ID non si propagano in nessuna delle due direzioni. Stilizzi l'host con :host, ricordi display: block e utilizzi composed: true per gli eventi che devono oltrepassare il confine. Per il resto, lo shadow tree si comporta come un normale DOM: al suo interno, innerHTML, appendChild e querySelector funzionano normalmente.