Guida introduttiva
Installate Glaze e il motore di animazione che usate:
pnpm add glazejs gsap
# Or choose Motion:
pnpm add glazejs motion
GSAP e Motion sono dipendenze peer facoltative. Glaze non include nessuno dei due motori.
Inizializzate una sola volta
Chiamate glaze() dopo aver inserito gli elementi nel DOM. Fornite il motore e tutta la configurazione in un'unica chiamata:
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 },
})
<div id="app">
<div data-animate="preset-rise"></div>
<div data-animate="@md:preset-rise from:duration-1"></div>
</div>
L'operazione esegue la scansione dell'elemento radice e crea le relative animazioni. Chiamando di nuovo glaze() si crea un'altra istanza; non si aggiunge la configurazione a un'istanza esistente.
L'adattatore esplicito API è equivalente per GSAP:
import glaze from "glazejs"
import { createGsapAdapter } from "glazejs/gsap"
import { gsap } from "gsap"
const animations = glaze({ adapter: createGsapAdapter(gsap) })
Per Motion, usate createMotionAdapter({ animate, stagger }) da glazejs/motion. Consultate la guida di Motion per la configurazione e le funzionalità supportate. Scegliete adapter oppure lib in un'unica configurazione.
Opzioni
| Opzione | Predefinito | Scopo |
|---|---|---|
lib.gsap.core |
nessuno | Istanza GSAP per la configurazione originale API. |
adapter |
nessuno | Adattatore esplicito GSAP o Motion; alternativa a lib. |
element |
document |
Radice del DOM da scansionare e osservare. |
dataAttribute |
"data-animate" |
Attributo che contiene le utility di animazione. |
className |
nessuno | Prefisso di classe per la sintassi delle classi. |
breakpoints |
{ default: "(min-width: 1px)" } |
Media query con nome. |
defaults.tl |
nessuno | Impostazioni predefinite della timeline. |
defaults.element |
nessuno | Proprietà di animazione predefinite; prevalgono le utility dell'elemento. |
presets |
nessuno | Stringhe di animazione riutilizzabili con nome. |
watch |
false |
Osserva le modifiche del DOM; true usa un ritardo di 500 ms, oppure passate { debounceTime }. |
La modalità di osservazione rileva le aggiunte e rimozioni di figli e le modifiche agli attributi di animazione all'interno dell'elemento radice. In modalità classi rileva anche le modifiche alle classi. Una mutazione pertinente del DOM pianifica una ricostruzione con ritardo. Le modifiche agli stili di animazione inline non attivano ricostruzioni.
Aggiornamento e pulizia
Conservate l'istanza restituita per gestirne il ciclo di vita:
// Rescan after rendering new elements when watch is disabled.
animations.refresh()
// On component unmount or page teardown:
animations.destroy()
refresh() ricostruisce usando la configurazione originale. destroy() interrompe le animazioni, rimuove gli observer e i listener delle media query e ripristina gli stili inline originali. È sicuro chiamarlo più di una volta. Un'istanza distrutta non può essere riavviata con refresh(); create una nuova istanza quando montate di nuovo.
Il valore restituito include anche timelines, breakpoints e state risolto. Ogni voce della timeline registra la timeline del motore, l'ID, la media query, l'elemento radice, le impostazioni e gli elementi animati. Mantenete le chiamate di riproduzione specifiche del motore nel codice che sa quale adapter ha creato l'istanza.
Gli aggiornamenti e le ricostruzioni responsive possono sostituire gli oggetti timeline nativi. Dopo una ricostruzione, leggete l'attuale timelines[index].timeline per controllare la riproduzione, invece di conservare un riferimento a una timeline nativa precedente.
CDN
I punti di accesso pubblici sono moduli ES e possono essere caricati anche da un CDN ESM:
import glaze from "https://esm.sh/glazejs"
import { gsap } from "https://esm.sh/gsap@3.15.0"
const animations = glaze({ lib: { gsap: { core: gsap } } })