Personaliser le préfixe des tags
Que ce soit pour éviter la collision avec une autre librairie, ou adopter votre propre convention de nommage, Ariane vous permet de définir votre propre préfixe pour ses composants.
Définissez window.ARIANE_CONFIG.prefix avant le script Ariane (autoloader, bundle complet, ou import d'un composant seul) :
<script>
window.ARIANE_CONFIG = { prefix: 'acme' };
</script>
<script type="module" src="https://unpkg.com/@ariane-ui/core/cdn/autoloader.js"></script>Les composants s'utilisent alors sous le préfixe configuré :
<acme-alert variant="success">
Opération réussie.
</acme-alert>Le préfixe défini ainsi est global et s'applique à tous les composants. Le renommage libre par composant nécessite d'utiliser Ariane via le paquet npm.
Deux possibilités, selon que vous voulez un préfixe commun ou choisir chaque tag.
Les imports qui enregistrent les composants (@ariane-ui/core ou l'import d'un composant seul) lisent window.ARIANE_CONFIG.prefix au moment où ils sont évalués. La variable doit donc être posée dans un module importé avant la librairie :
// ariane-config.ts
window.ARIANE_CONFIG = { prefix: 'acme' };import './ariane-config'; // évalué en premier
import '@ariane-ui/core';Le préfixe ne s'applique qu'aux tags : les noms d'événements restent en ar-* (<acme-pagination> émet ar-pagination-page-changed).
Avec un bundler ou du code évalué en différé (chunk partagé en build de production, pré-bundling du serveur de développement), l'ordre d'évaluation des modules n'est pas garanti : la variable peut être lue trop tard et le préfixe est alors ignoré, sans erreur. Préférez @ariane-ui/core/headless (ci-dessous) ; réservez ARIANE_CONFIG aux scripts classiques et au CDN.
Poser la variable dans le même module que l'import, après la ligne import, ne fonctionne pas : les imports d'un module sont évalués avant son propre code, et la librairie enregistre alors les tags ar-*.
Pour choisir vous-même le tag de chaque composant, importez les classes depuis @ariane-ui/core/headless : cette entrée n'enregistre rien, vous appelez customElements.define() vous-même. Contrairement au préfixe global, ce mode permet de renommer chaque composant individuellement. whenAllDefined prend alors le préfixe en option :
import { ArAlert } from '@ariane-ui/core/headless';
import { whenAllDefined } from '@ariane-ui/core/utils';
customElements.define('acme-alert', ArAlert);
await whenAllDefined({ prefix: 'acme-' });Les types (HTMLElementTagNameMap) décrivent les tags par défaut ar-* : avec un préfixe personnalisé, les tags ne sont pas typés.
| Mode de chargement | ARIANE_CONFIG.prefix |
|---|---|
| Autoloader (CDN) | honoré |
| Bundle complet (CDN) | honoré |
| Import d'un composant seul (CDN ou npm) | honoré |
Import de @ariane-ui/core (npm) | honoré, à poser avant l'import |
@ariane-ui/core/headless (npm) | non utilisé : vous choisissez chaque tag |
Certains composants en embarquent un autre dans leur shadow DOM (aujourd'hui ar-table-sort, qui affiche un tooltip). Ils l'enregistrent eux-mêmes, au premier usage, sous un nom interne privé : vous n'avez rien à enregistrer, Ariane ne définit aucun tag ar-* à votre insu et le préfixe que vous choisissez n'est pas concerné. Ce nom interne est un détail d'implémentation : ne vous appuyez pas dessus.
L'élément embarqué se personnalise par ses tokens (--ar-tooltip-* pour le tooltip de ar-table-sort) : sur :root pour toutes les instances, ou sur le composant hôte pour une seule.
:root {
--ar-tooltip-bg: #1f2937; /* toutes les instances */
}
ar-table-sort {
--ar-tooltip-bg: #7c2d12; /* le tooltip de ce composant seulement */
}Les règles CSS qui ciblent un tag ou ses ::part() n'atteignent pas un élément situé dans le shadow DOM d'un autre composant : seuls les tokens, hérités par les éléments imbriqués, le font.