Sélecteurs
Par défaut, Glaze recherche les éléments portant l'attribut data-animate et construit l'animation en fonction de la valeur de cet attribut. Cette page présente les trois options qui modifient les éléments lus par Glaze : dataAttribute, className et element, ainsi que les sélecteurs entre crochets qui dirigent une animation vers d'autres éléments. Les utilitaires de la chaîne sont décrits dans Syntaxe.
Comment les éléments sont trouvés
Lorsque glaze() s'exécute, puis à chaque refresh() ou reconstruction en mode surveillance, il parcourt chaque élément à l'intérieur de la racine et conserve ceux qui portent l'attribut configuré ou, en mode classe, une classe avec le préfixe configuré. L'élément racine lui-même est également pris en compte s'il en porte un. Les éléments sont lus dans l'ordre du document.
Chaque élément trouvé de cette façon obtient sa propre timeline, sauf s'il se trouve dans un élément tl ou qu'il est associé à l'un d'eux avec tl:<id>. Dans ce cas, il est ajouté à cette timeline. Consultez Timelines pour comprendre le fonctionnement du regroupement.
Attribut personnalisé
Utilisez un autre attribut data :
glaze({
lib: { gsap: { core: gsap } },
dataAttribute: "data-move",
})
Désormais, Glaze recherchera data-move au lieu de data-animate :
<div data-move="from:opacity-0"></div>
L’option remplace l’attribut au lieu d’en ajouter un. Avec le réglage ci-dessus, un élément qui porte encore data-animate est ignoré. Utilisez cette option lorsqu’un autre script de la page lit déjà data-animate, ou si vous souhaitez que le balisage utilise le nom d’attribut propre à votre projet.
En mode surveillance, Glaze observe l’attribut configuré : modifier la valeur de data-move sur un élément déclenche donc une reconstruction.
Syntaxe basée sur les classes
Vous préférez les classes aux attributs data ? Activez le mode classes :
glaze({
lib: { gsap: { core: gsap } },
className: "animate",
})
Vous pouvez maintenant écrire les animations sous forme de classes :
<div class="animate-from:opacity-0|duration-1"></div>
Cette approche convient si vous utilisez déjà CSS selon une approche utility-first et souhaitez donner une apparence similaire à vos animations. Le mode classe est également utile lorsqu’un système de modèles permet d’ajouter des classes à un élément, mais pas des attributs arbitraires.
Glaze lit chaque classe dont le préfixe est suivi d’un tiret (animate- ici) et supprime cette partie. Les classes sans ce préfixe restent inchangées : les classes d’animation peuvent donc coexister avec les classes de style sur un même élément. Vous pouvez répartir une animation sur plusieurs classes :
<div class="card animate-from:opacity-0 animate-from:y-24"></div>
Les classes adaptatives acceptent le point de rupture après ou avant le préfixe. Dans les deux cas, elles ne s’appliquent que lorsque le lg point de rupture correspond :
<div class="animate-@lg:from:opacity-0"></div>
<div class="@lg:animate-from:opacity-0"></div>
Les préréglages fonctionnent de la même façon dans les classes, par exemple animate-preset-fadeIn.
Le mode classe ne désactive pas l’attribut de données. Lorsqu’un élément possède les deux, Glaze les assemble en une seule chaîne : d’abord la valeur de l’attribut, puis les classes préfixées dans l’ordre où elles apparaissent dans l’attribut class.
<div
class="animate-from:opacity-0 animate-@lg:from:y-50"
data-animate="from:duration-1"
></div>
Cet élément s’anime depuis opacity: 0 pendant une seconde, quelle que soit la taille, et aussi depuis y: 50 lorsque lg correspond. Comme les chaînes sont assemblées, la même règle s’applique que dans une chaîne unique : lorsque deux parties définissent la même propriété, la dernière l’emporte. Ici, la valeur de classe remplace la valeur de l’attribut pour x :
<div class="animate-to:x-100" data-animate="to:x-50|y-20"></div>
L’élément s’anime vers x: 100 et y: 20.
Lorsque watch est activé en mode classe, Glaze observe également les changements de class. L’ajout d’une classe animate- à un élément, ou la modification des classes d’un élément que Glaze lit ou anime déjà, planifie une reconstruction. À l’intérieur d’un élément doté d’un sélecteur relatif, les changements de classe de ses descendants en planifient aussi une, car ils peuvent modifier les éléments correspondant au sélecteur. Les changements de classe des autres éléments n’en planifient pas, y compris ceux des ancêtres des éléments animés. Ainsi, activer une classe de mode sombre sur <html> ou une classe de verrouillage du défilement sur <body> ne perturbe pas les animations en cours. Un changement de classe qui fait qu’un élément correspond désormais à un sélecteur global n’est pas détecté non plus ; appelez refresh() après ce changement.
Limiter la recherche
Glaze recherche dans tout le document par défaut. Passez element pour n’animer que les éléments à l’intérieur d’un conteneur :
glaze({
lib: { gsap: { core: gsap } },
element: document.querySelector("#app"),
})
element accepte un Element ou un Document. Cette option limite trois éléments :
- Seuls la racine et ses descendants sont parcourus pour rechercher les utilitaires d’animation. Les éléments ailleurs sur la page sont ignorés, même s’ils portent
data-animate. - Le mode surveillance observe uniquement les mutations à l’intérieur de la racine.
destroy()nettoie uniquement ce que cette instance a créé ; les animations des autres parties de la page sont donc conservées.
C’est pourquoi element est l’option à privilégier dans les frameworks de composants. Créez une instance par composant monté en lui passant son élément racine, puis appelez destroy() lors de son démontage, comme indiqué dans Actualisation et nettoyage. Attribuez aux instances des racines distinctes, sans chevauchement ; un élément situé dans deux racines est animé par les deux instances.
Cibler d’autres éléments
Les options ci-dessus déterminent quels éléments Glaze lit. Un sélecteur entre crochets au début d’un segment détermine les éléments auxquels l’animation est appliquée. En l’absence de sélecteur, l’animation cible l’élément qui porte les utilitaires.
Sélecteurs relatifs
Un sélecteur commençant par & est résolu à partir de l’élément lui-même, représenté par &. Il est interrogé avec querySelectorAll et peut donc correspondre à plusieurs éléments :
<ul data-animate="[&>li]:from:opacity-0|y-20|stagger-0.1">
<li>One</li>
<li>Two</li>
<li>Three</li>
</ul>
[&>li] correspond aux enfants li directs. La valeur stagger espace leurs heures de début de 0.1 seconde. Utilisez cette option lorsqu’un élément doit piloter l’animation d’une liste, d’une grille ou d’un groupe d’enfants sans ajouter d’attribut à chacun d’eux.
Remplacez les espaces par des traits de soulignement. [&_p] devient & p et correspond à chaque p à l’intérieur de l’élément, quelle que soit la profondeur :
<article data-animate="[&_p]:from:opacity-0|stagger-0.2">
<p>First paragraph</p>
<div><p>Nested paragraph</p></div>
</article>
Chaque trait de soulignement dans un sélecteur est converti en espace. Il est donc impossible de cibler ainsi un nom de classe qui contient un trait de soulignement.
[&] seul est résolu en l’élément lui-même. Il est principalement utilisé comme valeur, par exemple scrollTrigger.trigger-[&] dans ScrollTrigger et dans les valeurs par défaut de la timeline.
Sélecteurs globaux
Un sélecteur sans & est transmis au moteur d’animation sous forme de chaîne. GSAP et Motion le résolvent dans l’ensemble du document, et non par rapport à l’élément ou à la racine element :
<h2 data-animate="[.badge]:from:opacity-0|scale-0.5|duration-0.3">Inbox</h2>
<span class="badge">3</span>
Cela anime chaque .badge de la page, où qu’il se trouve. Préférez les sélecteurs relatifs dans les composants réutilisables, car un sélecteur global cible également les copies du composant présentes ailleurs sur la page.
Limites
Chaque élément a une seule cible. Lorsque plusieurs segments comportent un sélecteur, le dernier s’applique à tous les états de l’élément. Ici, from et to s’appliquent tous deux à p, et non à h1 :
<div data-animate="[&>h1]:from:opacity-0 [&>p]:to:x-20">
<h1>Title</h1>
<p>Text</p>
</div>
Pour animer différemment deux groupes, placez les utilitaires sur les enfants eux-mêmes ou regroupez-les dans une timeline.
Un sélecteur s’arrête au premier ] ; les sélecteurs contenant des crochets, comme les sélecteurs d’attribut tels que [&>[data-item]], ne sont donc pas pris en charge. Utilisez plutôt un sélecteur de classe ou d’élément.
Les sélecteurs se combinent avec les points de rupture dans l’ordre décrit dans Syntaxe, par exemple @lg:[&>div]:from:opacity-0.