Saltar al contenido

Primeros pasos

Instala Glaze y el motor de animación que uses:

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

GSAP y Motion son dependencias entre pares opcionales. Glaze no incluye ninguno de los dos motores.

Inicializa una sola vez

Llama a glaze() cuando tus elementos ya estén en el DOM. Proporciona el motor y toda la configuración en una sola llamada:

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>

Esto analiza el elemento raíz y crea sus animaciones. Si vuelves a llamar a glaze(), se crea otra instancia; no se añade configuración a una instancia existente.

El adaptador explícito API es equivalente para GSAP:

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

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

Para Motion, usa createMotionAdapter({ animate, stagger }) desde glazejs/motion. Consulta la guía de Motion para conocer la configuración y las funciones compatibles. Elige adapter o lib en una sola configuración.

Opciones

Opción Predeterminado Propósito
lib.gsap.core ninguno Instancia GSAP para la configuración original API.
adapter ninguno Adaptador explícito de GSAP o Motion; alternativa a lib.
element document Elemento raíz del DOM que se analiza y observa.
dataAttribute "data-animate" Atributo que contiene las utilidades de animación.
className ninguno Prefijo de clase para la sintaxis de clases.
breakpoints { default: "(min-width: 1px)" } Consultas de medios con nombre.
defaults.tl ninguno Configuración predeterminada de la línea de tiempo.
defaults.element ninguno Propiedades de animación predeterminadas; prevalecen las utilidades del elemento.
presets ninguno Cadenas de animación reutilizables con nombre.
watch false Observar cambios en el DOM; true usa un retraso de 500 ms, o bien pasa { debounceTime }.

El modo de observación detecta la adición y eliminación de elementos secundarios, así como los cambios en los atributos de animación dentro del elemento raíz. En el modo de clases, también detecta los cambios en las clases. Una mutación relevante del DOM programa una reconstrucción con retraso. Los cambios en los estilos de animación en línea no provocan reconstrucciones.

Actualización y limpieza

Conserva la instancia devuelta para gestionar el ciclo de vida:

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

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

refresh() reconstruye usando la configuración original. destroy() detiene las animaciones, elimina los observadores y los detectores de consultas de medios, y restaura los estilos en línea originales. Se puede llamar varias veces sin problema. Una instancia destruida no se puede reiniciar con refresh(); cree una instancia nueva al volver a montar.

El valor devuelto también incluye timelines, breakpoints y state, ya resuelto. Cada entrada de la línea de tiempo registra la línea de tiempo del motor, el ID, la consulta de medios, el elemento raíz, la configuración y los elementos animados. Mantenga las llamadas de reproducción específicas del motor en código que sepa qué adaptador creó la instancia.

Las actualizaciones y las reconstrucciones adaptables pueden reemplazar los objetos nativos de la línea de tiempo. Para controlar la reproducción después de una reconstrucción, lea el valor actual de timelines[index].timeline en lugar de conservar una referencia anterior a la línea de tiempo nativa.

CDN

Los puntos de entrada públicos son módulos ES y también se pueden cargar desde un CDN de 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 } } })