Vai al contenuto

Guida introduttiva

Installate Glaze e il motore di animazione che usate:

Shell
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:

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>

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:

TypeScript
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:

TypeScript
// 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:

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 } } })