Aller au contenu

Premiers pas

Installez Glaze et le moteur d'animation que vous utilisez :

Shell
pnpm add glazejs gsap
# Or choose Motion:
pnpm add glazejs motion

GSAP et Motion sont des dépendances homologues facultatives. Glaze n'intègre aucun des deux moteurs.

Initialiser une seule fois

Appelez glaze() après l'ajout de vos éléments au DOM. Fournissez le moteur et toute la configuration en un seul appel :

TypeScript
import glaze from "glazejs"
import { gsap } from "gsap"

const root = document.querySelector("#app")
if (!root) throw new Error("Missing application root")

const animations = glaze({
  lib: { gsap: { core: gsap } },
  element: root,
  breakpoints: { md: "(min-width: 768px)" },
  defaults: { element: "duration-0.6" },
  presets: { rise: "from:opacity-0|y-24" },
  watch: { debounceTime: 200 },
})
HTML
<div id="app">
  <div data-animate="preset-rise"></div>
  <div data-animate="@md:preset-rise from:duration-1"></div>
</div>

Cela parcourt la racine et crée ses animations. Un nouvel appel à glaze() crée une autre instance ; il n'ajoute pas de configuration à une instance existante.

L'adaptateur explicite API est équivalent pour GSAP :

TypeScript
import glaze from "glazejs"
import { createGsapAdapter } from "glazejs/gsap"
import { gsap } from "gsap"

const animations = glaze({ adapter: createGsapAdapter(gsap) })

Pour Motion, utilisez createMotionAdapter({ animate, stagger }) depuis glazejs/motion. Consultez le guide Motion pour la configuration et les fonctionnalités prises en charge. Choisissez adapter ou lib dans une même configuration.

Options

Option Valeur par défaut Rôle
lib.gsap.core aucune Instance GSAP pour la configuration initiale API.
adapter aucune Adaptateur explicite GSAP ou Motion ; alternative à lib.
element document Racine DOM à parcourir et à observer.
dataAttribute "data-animate" Attribut contenant les utilitaires d'animation.
className aucune Préfixe de classe pour la syntaxe de classe.
breakpoints { default: "(min-width: 1px)" } Requêtes média nommées.
defaults.tl aucune Paramètres de timeline par défaut.
defaults.element aucune Propriétés d'animation par défaut ; les utilitaires d'élément sont prioritaires.
presets aucune Chaînes d'animation réutilisables nommées.
watch false Observer les changements du DOM ; true utilise un délai anti-rebond de 500 ms, ou transmettez { debounceTime }.

Le mode de surveillance observe les ajouts et suppressions d'enfants ainsi que les changements d'attributs d'animation au sein de la racine. En mode classe, il observe également les changements de classe. Toute mutation pertinente du DOM programme une reconstruction avec délai anti-rebond. Les changements de style d'animation en ligne ne déclenchent pas de reconstruction.

Actualisation et nettoyage

Conservez l'instance renvoyée pour gérer son cycle de vie :

TypeScript
// Rescan after rendering new elements when watch is disabled.
animations.refresh()

// On component unmount or page teardown:
animations.destroy()

refresh() reconstruit avec la configuration d'origine. destroy() arrête les animations, supprime les observateurs et les écouteurs de requêtes média, et restaure les styles intégrés d'origine. Cette méthode peut être appelée plusieurs fois sans risque. Une instance détruite ne peut pas être redémarrée avec refresh() ; créez une nouvelle instance lors du montage suivant.

La valeur de retour comprend également timelines, breakpoints et le state résolu. Chaque entrée de la timeline indique la timeline du moteur, l'ID, la requête média, l'élément racine, les paramètres et les éléments animés. Réservez les appels de lecture propres au moteur au code qui sait quel adaptateur a créé l'instance.

Les actualisations et les reconstructions responsives peuvent remplacer les objets de timeline natifs. Après une reconstruction, lisez la valeur actuelle de timelines[index].timeline pour contrôler la lecture au lieu de conserver une ancienne référence à la timeline native.

CDN

Les points d'entrée publics sont des modules ES et peuvent également être chargés depuis un CDN ESM :

JavaScript
import glaze from "https://esm.sh/glazejs"
import { gsap } from "https://esm.sh/gsap@3.15.0"

const animations = glaze({ lib: { gsap: { core: gsap } } })