gsap

name	gsap
description	当你需要在 HTML/CSS/JS/React 中用 GSAP（时间线、ScrollTrigger、错峰、变换）添加或调试专业级网页动画时使用。包含顺滑运动、性能与常见坑的模式。

GSAP (GreenSock) — Web Animation Skill

何时使用

• 高质量的 UI/运动设计：入场、微交互、页面转场
• 基于时间线的序列（相对于零散的 CSS transition）
• 滚动驱动的叙事（配合 ScrollTrigger）
• 复杂的缓动、错峰、跨多元素的编排

核心概念与 API

• 补间（Tweens）：
  • gsap.to(targets, vars)
  • gsap.from(targets, vars)
  • gsap.fromTo(targets, fromVars, toVars)
• 时间线（Timelines）：
  • const tl = gsap.timeline({ defaults, repeat, yoyo, paused })
  • 链式调用：tl.to(...).from(...).addLabel('x').add(() => ...)
  • 位置参数：绝对 1.2、相对 "+=0.5"、重叠 "-=0.3"、标签 "intro"
• 缓动（Eases）：ease: "power2.out"、"expo.inOut"、"elastic.out(1, 0.3)"
• 错峰（Staggers）：stagger: 0.05 或 { each, from: "start|center|end|random", grid }
• 性能友好的属性：
  • 优先使用变换（x、y、scale、rotation）与不透明度（autoAlpha）
• ScrollTrigger（插件）：
  • gsap.registerPlugin(ScrollTrigger)
  • 内联：gsap.to(".box", { scrollTrigger: ".box", x: 500 })
  • 进阶：scrollTrigger: { trigger, start, end, scrub, pin, snap, markers }
  • 独立：ScrollTrigger.create({ trigger, start, end, onUpdate, onToggle })

常见坑（及修复）

• 对布局属性（top/left/width/height）做动画 → 卡顿
  • 使用变换，添加 will-change: transform，避免强制回流。
• ScrollTrigger 因触发元素尺寸/溢出容器错误而「不触发」
  • 确保触发元素存在、有高度，并检查滚动容器（嵌套滚动需要额外配置）。
• 在 SPA/React 中未做清理
  • 使用 gsap.context() 并在卸载时 revert；必要时杀掉触发器（ScrollTrigger.getAll().forEach(t => t.kill())）。
• FOUC / 在字体或图片加载前测量
  • 在布局稳定后再初始化；图片加载后运行 ScrollTrigger.refresh()。

快速配方

1) 主视觉入场（错峰）

gsap.from(".hero [data-anim]", {
  y: 24,
  autoAlpha: 0,
  duration: 0.8,
  ease: "power2.out",
  stagger: 0.06,
});

2) 序列化时间线

const tl = gsap.timeline({ defaults: { ease: "power2.out", duration: 0.6 } });
tl.from(".nav", { y: -20, autoAlpha: 0 })
  .from(".hero-title", { y: 30, autoAlpha: 0 }, "-=0.2")
  .from(".hero-cta", { scale: 0.95, autoAlpha: 0 }, "-=0.2");

3) 滚动刷新的钉住区块

gsap.registerPlugin(ScrollTrigger);

gsap.timeline({
  scrollTrigger: {
    trigger: ".story",
    start: "top top",
    end: "+=800",
    scrub: 1,
    pin: true,
  },
}).to(".story .panel", { xPercent: -200 });

需求不明确时应向用户询问

• 这是静态站还是 SPA（React/Next/Vue）？是否需要页面转场？
• 我们是否需要滚动驱动的区块（pin/scrub/snap）？
• 性能约束（移动端支持、减弱动效）？