跳转到正文

快速入门

安装 Glaze 和你使用的动画引擎:

命令行
pnpm add glazejs gsap
# Or choose Motion:
pnpm add glazejs motion

GSAP 和 Motion 是可选的对等依赖项。Glaze 不会打包任何一个引擎。

仅初始化一次

等元素进入 DOM 后,调用 glaze()。在一次调用中提供引擎和所有配置:

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>

此调用会扫描根节点并创建其中的动画。再次调用 glaze() 会创建另一个实例,不会向现有实例添加配置。

对于 GSAP,显式适配器 API 的效果相同:

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

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

使用 Motion 时,请从 glazejs/motion 引入 createMotionAdapter({ animate, stagger })。有关设置和支持的功能,请参阅 Motion 指南。在单个配置中选择 adapter 或 lib。

选项

选项 默认值 用途
lib.gsap.core 无 原始设置 API 的 GSAP 实例。
adapter 无 显式指定 GSAP 或 Motion 适配器;可替代 lib。
element document 要扫描和监听的 DOM 根节点。
dataAttribute "data-animate" 包含动画工具类的属性。
className 无 类语法的类名前缀。
breakpoints { default: "(min-width: 1px)" } 命名的媒体查询。
defaults.tl 无 时间线默认设置。
defaults.element 无 动画默认属性;元素工具类优先。
presets 无 可复用的命名动画字符串。
watch false 监听 DOM 变化;true 使用 500 毫秒的防抖延迟,也可以传入 { debounceTime }。

监听模式会监视根节点内子元素的添加和移除,以及动画属性的变化。在类模式下,它还会监视类名变化。相关的 DOM 变更会安排一次防抖重建。内联动画样式的变化不会触发重建。

刷新和清理

保留返回的实例,以便管理生命周期:

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

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

refresh() 会使用原始配置重新构建。destroy() 会停止动画、移除观察器和媒体查询监听器,并恢复原始内联样式。可以安全地多次调用。已销毁的实例无法通过 refresh() 重新启动;再次挂载时请创建新实例。

返回值还包含 timelines、breakpoints 和解析后的 state。每个时间线条目都会记录其引擎时间线、ID、媒体查询、根元素、设置和动画元素。请在知道创建该实例的适配器类型的代码中调用引擎专属的播放方法。

刷新和响应式重建可能会替换原生时间线对象。重建后控制播放时,请读取当前的 timelines[index].timeline,不要保留之前的原生时间线引用。

CDN

公共入口点是 ES 模块,也可以从 ESM CDN 加载:

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