Communitygithub.com

gsap-motion

GSAP 3 动画架构,用于构建高端网站 — 插件注册表(ScrollTrigger、SplitText、Flip、Observer、Draggable、Inertia、CustomEase、MorphSVG、DrawSVG — 所有插件均免费包含在公开的 gsap 包中)、React 集成(使用 useGSAP 进行作用域和清理)、gsap.matchMedia(用于响应式和减少动效分支)、时间线、滚动擦除固定序列、文本揭示、clip-path/蒙版过渡、Flip 布局变形、水平滚动、视差、磁铁/光标效果和页面过渡。适用于所有 GSAP 或 ScrollTrigger 工作、任何滚动驱动或电影级动画,以及当动画在路由更改或窗口大小调整后泄漏、重复、卡顿或失效时。

gsap-motion 是什么?

该技能为使用 GSAP 3 创建高级网页动画提供了完整的架构和最佳实践。它涵盖了插件注册(所有插件,包括 ScrollTrigger、SplitText、Flip 等,均免费包含在公开的 gsap 包中)、与 React 的集成(通过 `@gsap/react` 中的 `useGSAP` 实现作用域和清理),以及响应式设计(通过 `gsap.matchMedia` 实现减少动效分支)。技能详细说明了六条关键规则,用于防止 React 中 90% 的 GSAP 错误,包括始终在 `useGSAP` 内创建动画、避免在模块作用域创建 ScrollTrigger、以及正确处理布局变化后的刷新。此外,它还提供了经过验证的架构文件(如 `registry.ts`、`tokens.ts`、`lit.ts`)和示例模式(如固定擦除序列、Flip 过滤器、磁铁按钮和页面过渡),并推荐了 Lenis(而非 ScrollSmoother)进行平滑滚动。该技能适用于 Claude Code、Cursor 和 Cursor Composer 等 AI 代理编程工具,可确保动画在路由更改和窗口大小调整后不泄漏、不卡顿。

兼容平台~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/jakyherr05-hash/Claude-code-skill/tree/HEAD/plugins/premium-web-studio/skills/gsap-motion

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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 错误的规则

  1. 每个动画都位于 useGSAP(() => {...}, { scope: ref }) 内部。上下文会在卸载时撤销所有补间、ScrollTrigger、SplitText 和 matchMedia 分支。事件处理程序动画使用 contextSafe。
  2. 切勿在模块作用域或在未撤销的情况下在普通 useEffect 中创建 ScrollTrigger。切勿将 ScrollTrigger.killAll() 作为清理策略。
  3. 每个部分使用一个 gsap.matchMedia(),并带有 motion/reduce(以及桌面/移动端)条件。初始隐藏状态设置在 motion 分支内部,以便无 JS 和减少动效的用户看到最终内容。
  4. 严格模式安全: useGSAP 处理 React 18/19 的重复调用。通过泄漏检查进行验证:导航离开并返回后,ScrollTrigger.getAll().length 应恢复为基线值。
  5. 布局更改后刷新: 字体加载后(document.fonts.ready.then(() => ScrollTrigger.refresh()))、过滤列表后以及路由内容挂载后。对于其值根据布局计算的任何触发器,设置 invalidateOnRefresh: true。
  6. 正确固定: 固定一个内部包装器,保留 pinSpacing,为其设置不依赖于网页字体的 min-height: 100svh,并与 Lenis 一起使用 anticipatePin: 1。每次体验只使用一个固定;堆叠的固定会使用户困惑。
  7. 动画化廉价的属性: transform、opacity、clip-path;仅在小子树上的 CSS 变量。避免在擦除时间线中使用 width/height/top/left,并在写入之前读取布局(GSAP 会批量处理自己的写入)。
  8. will-change 仅在动画期间使用,且仅用于少数图层。

配方

references/recipes.md 包含经过测试或有文档记录的模式,包括:电影级英雄序列、SplitText 揭示(字符/单词/行、遮罩)、clip-path 和蒙版过渡、固定擦除叙事、水平滚动部分(containerAnimation)、视差图层、Flip 状态变形、Observer 驱动的手势部分、Draggable + Inertia 轮播、磁铁按钮、光标跟随器、SVG 变形/绘制、图像失真传递到 WebGL、页面过渡以及使用 WebGL 相机的 3D 滚动。

references/react-lifecycle.md 涵盖路由更改、窗口大小调整、内容更改和调试泄漏。

有目的的动效清单(在动画化之前)

  • 这个动画传达了什么(层次结构、因果关系、状态、品牌材料)?如果什么也没传达,请删除它。
  • 它是标志性时刻,还是应该保持低调?
  • 减少动效会显示什么?(它必须仍然完全可理解。)
  • 移动端表达是什么?(悬停效果需要触摸替代方案;固定变得更短。)
  • 页面创建了多少个 ScrollTrigger?将清单写入规范,以便 QA 可以断言它。

相关技能