`attachShadow` et racine d’ombre

Le Shadow DOM donne à un élément son propre arbre shadow isolé, qui n’apparaît pas dans le DOM principal de la page. Le CSS extérieur ne s’y infiltre pas et le CSS intérieur n’en sort pas : c’est une encapsulation parfaite pour les composants.

Appelez this.attachShadow({ mode: "open" }) depuis le constructeur ou connectedCallback d’un élément personnalisé. La méthode renvoie une racine ShadowRoot que vous pouvez remplir comme un arbre DOM ordinaire à l’aide de innerHTML, appendChild, etc.

mode: "open" expose l’arbre shadow via element.shadowRoot. mode: "closed" le masque : element.shadowRoot renvoie null, de sorte que les scripts externes ne peuvent pas entrer dans l’arbre. Le mode fermé est rarement utile en pratique, car le même code que celui qui a défini l’élément peut de toute façon conserver sa propre référence.

Les styles définis dans l’arbre shadow (via <style> ou des feuilles de style adoptées) s’appliquent uniquement dans cet arbre shadow. Les sélecteurs CSS du document principal ne ciblent jamais les descendants shadow, et les styles de l’arbre shadow ne se propagent jamais au document.

Depuis l’intérieur de l’arbre shadow, l’élément hôte (l’élément personnalisé lui-même) est sélectionné avec la pseudo-classe spéciale :host. :host(.large) correspond lorsque l’hôte possède la classe .large ; :host([disabled]) correspond lorsque l’hôte possède l’attribut disabled.

Les éléments personnalisés sont affichés en ligne par défaut. Dans la racine shadow, appliquez :host { display: block } afin que l’élément se comporte comme un composant de niveau bloc. Oublier cette règle est une cause fréquente des problèmes où « ma largeur de 100 % est ignorée ».

Les événements qui remontent depuis l’arbre shadow sont réadressés au niveau de l’hôte. Un clic sur un bouton interne arrive auprès des écouteurs externes avec event.target === host. Utilisez event.composedPath() pour voir la véritable cible interne si nécessaire.

Les événements personnalisés déclenchés à l'intérieur de la racine fantôme ne franchissent pas la frontière, sauf si vous les créez avec à la fois bubbles: true et composed: true. Sans composed, les écouteurs externes placés sur l'hôte ne voient jamais l'événement.

Les scripts externes peuvent interroger l'élément hôte, mais pas ses descendants fantômes. document.querySelector("my-card span") ne renvoie rien si le <span> se trouve dans l'arbre fantôme. L'encapsulation protège les éléments internes contre les couplages accidentels.

Avec <template shadowrootmode="open"> dans le code HTML d'un élément, le navigateur construit l'arbre fantôme lors de l'analyse, sans JavaScript. Cela rend les composants rendus côté serveur compatibles avec l'hydratation, car l'arbre fantôme existe avant l'exécution du JS.

Chaque racine fantôme entraîne un surcoût — une portée de style et une couche de rendu supplémentaires. Des centaines de racines fantômes ne posent aucun problème ; plusieurs dizaines de milliers peuvent avoir un impact. Pour les interfaces à très forte densité (grands tableaux, listes virtualisées), profilez votre application afin de vérifier que les coûts du DOM fantôme restent acceptables.

Que fait le mode open que le mode closed ne fait pas ?

attachShadow({ mode: "open" }) crée une sous-arborescence DOM isolée où les CSS et les identifiants ne fuient dans aucune direction. Appliquez un style à l'hôte avec :host, n'oubliez pas display: block, et utilisez composed: true pour les événements qui doivent s'échapper. L'arbre fantôme se comporte sinon comme un DOM ordinaire — innerHTML, appendChild et querySelector fonctionnent tous normalement à l'intérieur.