DOM d’ombre déclaratif

Le DOM d’ombre traditionnel est créé par JavaScript (attachShadow). Pour les pages rendues côté serveur, cela signifie que l’arbre d’ombre reste vide jusqu’à l’exécution de JS, ce qui va à l’encontre de l’objectif du SSR : fournir un HTML complet dès le premier octet. Le DOM d’ombre déclaratif résout ce problème.

Un <template> avec shadowrootmode="open" déclare une racine d’ombre en HTML au moment de l’analyse. Le navigateur rattache automatiquement la racine d’ombre à l’élément parent ; le contenu du modèle devient l’arbre d’ombre. Aucun JavaScript n’est nécessaire.

Le DOM d’ombre déclaratif permet de véritables composants web rendus côté serveur : le serveur inclut directement l’arbre d’ombre complet, le navigateur l’analyse et le rattache avant toute exécution de JS, puis le JS d’hydratation peut prendre le relais à partir d’une base entièrement rendue. Les composants web sont ainsi sur un pied d’égalité avec le SSR des cadres logiciels.

Les modes sont les mêmes que pour attachShadow impératif : shadowrootmode="open" expose la racine d’ombre via element.shadowRoot ; shadowrootmode="closed" la masque. Le comportement est identique à celui de son équivalent attaché par JavaScript.

Le navigateur rattache la racine d’ombre la première fois qu’il rencontre le <template shadowrootmode>. Une fois rattaché, le modèle est consommé : toute recherche ultérieure ne renvoie rien. Cela correspond au cycle de vie de attachShadow : une racine d’ombre existe pendant toute la durée de vie de l’élément.

Les enfants du DOM léger, c’est-à-dire le <p> situé à l’extérieur du <template> dans l’exemple, sont projetés dans les éléments <slot> de l’arbre d’ombre, comme avec le DOM d’ombre impératif. Le fonctionnement de la composition est identique ; seul le mécanisme de rattachement diffère.

Si <my-card> est un élément personnalisé enregistré, le processus de mise à niveau récupère la racine d’ombre déjà rattachée au lieu d’appeler de nouveau attachShadow. La classe de l’élément personnalisé peut lire this.shadowRoot dans son connectedCallback sans avoir besoin de la créer.

Le render de Lit-html, les composants Astro et plusieurs autres cadres logiciels génèrent désormais un DOM d’ombre déclaratif dans leur sortie SSR. Une solution maison est possible : tout système de création de modèles à partir de chaînes peut écrire le modèle contenant shadowrootmode.

Le DOM d’ombre déclaratif est disponible dans Chrome, Edge, Safari et Firefox. Les navigateurs plus anciens ignorent silencieusement l’élément <template> : son contenu reste invisible, ce qui assure une dégradation progressive pour les environnements qui ne le prennent pas en charge.

Pour une compatibilité plus large, un petit script peut parcourir le DOM et convertir template[shadowrootmode] en véritables racines d’ombre. Exécutez-le avant tout enregistrement d’élément personnalisé afin que les mises à niveau ultérieures des composants trouvent l’arbre d’ombre attendu.

Le DOM d’ombre déclaratif duplique la structure : le contenu du <template> figure dans le HTML alors qu’il est également intégré à la classe du composant. Pour les pages contenant de nombreux exemplaires du même composant, cela alourdit la charge utile. Les cadres logiciels dédupliquent cette structure ; un SSR fait maison peut vouloir faire de même.

Si vous livrez des composants web et vous souciez du rendu dès le premier octet ou du référencement naturel, adoptez-le dès maintenant. La fonctionnalité est stable, prise en charge et améliore considérablement le SSR des applications fondées sur des composants web. Elle ne s’applique pas aux applications qui n’utilisent pas le DOM d’ombre.

Quel problème le DOM d’ombre déclaratif résout-il par rapport à attachShadow impératif ?

Le DOM d’ombre déclaratif utilise <template shadowrootmode="open"> à l’intérieur d’un élément personnalisé pour rattacher une racine d’ombre au moment de l’analyse, sans nécessiter de JS. Il permet un véritable SSR pour les composants web : l’arbre d’ombre, les styles isolés et les emplacements fonctionnent tous avant l’hydratation. Il est pris en charge par tous les navigateurs modernes ; une couche de compatibilité est disponible pour les navigateurs plus anciens. Les cadres logiciels, notamment Lit et Astro, le génèrent automatiquement.