Utiliser Ariane dans un shadow DOM
Si votre application encapsule sa propre page ou une partie de son contenu dans un web component avec son propre shadow DOM, le thème CSS ne s'appliquera que partiellement à vos composants.
Il s'agit là d'une contrainte inhérente au shadow DOM, mais cette page vous guidera pour vous aider à afficher vos composants correctement.
Les CSS Custom properties de votre thème chargé dans le document traversent la frontière du shadow DOM par héritage CSS natif.
Les règles utilisant ::part() par contre ne peuvent pas traverser le shadow DOM de votre composant et les règles de votre thème ne s'appliquent donc pas.
C'est la raison pour laquelle votre thème ne s'applique que partiellement.
N'importe quelle feuille de style peut être transformée en CSSStyleSheet. Elle peut ensuite être "adoptée" par chaque composant qui en a besoin, chacun partageant une même instance chargée et parsée une seule fois.
Contrairement au chargement du CSS via une balise <link>, les adoptedStyleSheets permettent un chargement synchrone (pas de FOUC).
Le plus souvent votre application a déjà son propre thème, local à votre code — la technique est la même quel que soit le CSS.
Il s'agit de créer à partir de votre fichier CSS une version *.js qui sera utilisée en complément de votre fichier CSS.
// mon-theme.js — dans l'idéal, généré au build à partir de votre thème CSS
export const monTheme = new CSSStyleSheet();
/* Injectez le contenu de votre fichier CSS ci-dessous */
monTheme.replaceSync(`
ar-datepicker::part(panel) {
width: 20rem;
padding: 1rem;
}
...
`);
// mon-app.js — définition du composant, importe le fichier ainsi créé
import { monTheme } from 'mon-theme.js';
export class MonComposant extends HTMLElement {
connectedCallback() {
const shadow = this.attachShadow({ mode: 'open' });
// Importez le thème dans le shadowRoot
shadow.adoptedStyleSheets = [monTheme];
}
}
customElements.define('mon-composant', MonComposant);N'importez pas les tokens CSS
Les CSS Custom properties n'ont pas besoin d'être incluses dans cette version JS, le sélecteur :root ne s'appliquant pas dans le contexte du shadow DOM.
Le thème CSS reste chargé dans le document (ses tokens traversent le shadow DOM) : la version JavaScript vient en complément, pour les règles ::part().
Le starter-kit fournit un script qui la génère à partir de son thème CSS :
# Dans une copie du starter-kit (ou de votre thème)
npm install
npm run build:js # génère ariane-starter.js : export const starterTheme = new CSSStyleSheet()Il ne reste qu'à adopter la feuille obtenue dans votre shadow DOM :
// mon-app.js — définition du composant, fichier séparé de la page
import { starterTheme } from './ariane-starter.js';
class MonComposant extends HTMLElement {
connectedCallback() {
const shadow = this.attachShadow({ mode: 'open' });
shadow.adoptedStyleSheets = [starterTheme];
shadow.append(document.createElement('ar-datepicker'));
}
}
customElements.define('mon-composant', MonComposant);