GSAP 动画架构
已验证基线(2026-11-15)
[email protected]是 npm 上的最新版本。其许可证字段为 "Standard 'no charge' license"(gsap.com/standard-license):免费用于商业网站,包括客户项目。唯一的禁止用途是构建与 Webflow 竞争的可视化动画构建器工具。所有插件都包含在公共包中:ScrollTrigger、ScrollSmoother、SplitText、Flip、Observer、Draggable、InertiaPlugin、CustomEase、CustomBounce、CustomWiggle、MorphSVGPlugin、DrawSVGPlugin、MotionPathPlugin、ScrambleTextPlugin、ScrollToPlugin、Physics2D、PhysicsProps、GSDevTools 等。@gsap/[email protected]提供了useGSAP。- 新项目前请重新检查:
npm view gsap version license和ls node_modules/gsap/*.js。 - 使用 ScrollSmoother 或 Lenis,切勿同时使用。本工作室标准化使用 Lenis(请参阅
lenis-scroll技能)。
架构(将 assets/ 复制到 src/motion/)
| 文件 | 作用 |
|---|---|
assets/registry.ts | 一次性注册插件、创建项目的 CustomEases、设置默认值、ScrollTrigger.config({ ignoreMobileResize: true })。所有内容都从此处导入 gsap。 |
assets/tokens.ts | 动效令牌(持续时间、缓动、交错),镜像自 ANIMATION_SPECIFICATION.md + prefersReducedMotion() |
assets/lit.ts | 示例可重用文本原语:使用 aria:'auto'、autoSplit 和返回补间的 onSplit 的 SplitText。根据品牌调整揭示方式(亮显、遮罩、滑动……)。 |
assets/useReducedMotion.ts | 用于 DOM 级切换(例如渲染静态步骤而非固定)的实时 prefers-reduced-motion 钩子 |
assets/examples/*.tsx | 来自参考演示的经过测试的模式:固定擦除序列(Method)、Flip 过滤器(ScheduleIndex)、quickTo 驱动的交互(TheHour)、一次性揭示(Rooms)、路由过渡遮罩(Router) |
这些文件是本仓库中 demo/ 的经过验证的实现,并由其 Playwright 套件进行了测试(跨路由清理、减少动效、滚动同步)。
防止 React 中 90% GSAP 错误的规则
- 每个动画都位于
useGSAP(() => {...}, { scope: ref })内部。上下文会在卸载时撤销所有补间、ScrollTrigger、SplitText 和 matchMedia 分支。事件处理程序动画使用contextSafe。 - 切勿在模块作用域或在未撤销的情况下在普通
useEffect中创建 ScrollTrigger。切勿将ScrollTrigger.killAll()作为清理策略。 - 每个部分使用一个
gsap.matchMedia(),并带有motion/reduce(以及桌面/移动端)条件。初始隐藏状态设置在 motion 分支内部,以便无 JS 和减少动效的用户看到最终内容。 - 严格模式安全:
useGSAP处理 React 18/19 的重复调用。通过泄漏检查进行验证:导航离开并返回后,ScrollTrigger.getAll().length应恢复为基线值。 - 布局更改后刷新: 字体加载后(
document.fonts.ready.then(() => ScrollTrigger.refresh()))、过滤列表后以及路由内容挂载后。对于其值根据布局计算的任何触发器,设置invalidateOnRefresh: true。 - 正确固定: 固定一个内部包装器,保留
pinSpacing,为其设置不依赖于网页字体的min-height: 100svh,并与 Lenis 一起使用anticipatePin: 1。每次体验只使用一个固定;堆叠的固定会使用户困惑。 - 动画化廉价的属性: transform、opacity、clip-path;仅在小子树上的 CSS 变量。避免在擦除时间线中使用 width/height/top/left,并在写入之前读取布局(GSAP 会批量处理自己的写入)。
will-change仅在动画期间使用,且仅用于少数图层。
配方
references/recipes.md 包含经过测试或有文档记录的模式,包括:电影级英雄序列、SplitText 揭示(字符/单词/行、遮罩)、clip-path 和蒙版过渡、固定擦除叙事、水平滚动部分(containerAnimation)、视差图层、Flip 状态变形、Observer 驱动的手势部分、Draggable + Inertia 轮播、磁铁按钮、光标跟随器、SVG 变形/绘制、图像失真传递到 WebGL、页面过渡以及使用 WebGL 相机的 3D 滚动。
references/react-lifecycle.md 涵盖路由更改、窗口大小调整、内容更改和调试泄漏。
有目的的动效清单(在动画化之前)
- 这个动画传达了什么(层次结构、因果关系、状态、品牌材料)?如果什么也没传达,请删除它。
- 它是标志性时刻,还是应该保持低调?
- 减少动效会显示什么?(它必须仍然完全可理解。)
- 移动端表达是什么?(悬停效果需要触摸替代方案;固定变得更短。)
- 页面创建了多少个 ScrollTrigger?将清单写入规范,以便 QA 可以断言它。