⚡ 快速定位 >>>

• import gsap from "gsap"
• 核心概念：Tween（单次动画）→ Timeline（时间轴，按顺序组织多个 Tween）→ Plugin（扩展能力）
• gsap.registerPlugin(...)：，必须在使用插件能力前调用
• 官方文档：https://gsap.com/docs/v3/

// 最小工作流：import → 注册插件 → 写动画
import gsap from "gsap";
import ScrollTrigger from "gsap/ScrollTrigger";

gsap.registerPlugin(ScrollTrigger);

gsap.to(".box", {
  x: 200,
  rotation: 45,
  duration: 1,
  ease: "power2.out"
});

🏃 最小工作流 >>>

核心 Tween 四兄弟

• gsap.to(targets, vars)
• gsap.from(targets, fromVars)
• gsap.fromTo(targets, fromVars, toVars)
• gsap.set(targets, vars)

// 入场动画：从 y:50 运动到当前位置
gsap.from(".hero-title", {
  y: 50,
  opacity: 0,
  duration: 0.8,
  ease: "power2.out"
});

// 交互反馈：暂停状态，点击后播放
gsap.to(".card", {
  scale: 1.05,
  duration: 0.2,
  paused: true
});
// 触发：tween.play()

常用参数

gsap.to(".item", {
  opacity: 1,
  y: 0,
  duration: 0.5,
  stagger: { each: 0.08, from: "start" },
  ease: "power3.out"
});

🍳 高频 Recipes >>>

1. 列表项依次入场

// 批量列表项依次出现，每项间隔 80ms
gsap.from(".item", {
  opacity: 0,
  y: 20,
  duration: 0.4,
  stagger: {
    each: 0.08,
    from: "start"  // "end" | "center" | "random"
  },
  ease: "power2.out"
});

2. 时间轴串联

const tl = gsap.timeline({
  defaults: { duration: 0.5, ease: "power2.out" }
});

tl.from(".hero-title", { y: 30, opacity: 0 })
  .from(".hero-subtitle", { y: 18, opacity: 0 }, "<0.1")   // 紧随前一个
  .from(".hero-cta", { scale: 0.92, opacity: 0 }, ">-0.1")  // 重叠 0.1s
  .addLabel("ready");

3. ScrollTrigger 滚动驱动

gsap.registerPlugin(ScrollTrigger);

gsap.to(".feature-image", {
  y: -80,
  ease: "none",
  scrollTrigger: {
    trigger: ".feature",
    start: "top bottom",    // trigger 顶部接触视口底部
    end: "bottom top",       // trigger 底部接触视口顶部
    scrub: true             // 绑定到滚动进度
  }
});

4. Flip 布局切换过渡

gsap.registerPlugin(Flip);

const state = Flip.getState(".card");  // 拍摄当前状态
document.querySelector(".grid").classList.toggle("is-expanded");
Flip.from(state, {
  duration: 0.45,
  ease: "power2.inOut",
  absolute: true
});

5. 响应式 matchMedia

const mm = gsap.matchMedia();

mm.add("(min-width: 768px)", () => {
  const ctx = gsap.context(() => {
    gsap.from(".sidebar", { x: -40, opacity: 0 });
  });
  return () => ctx.revert();
});

window.addEventListener("resize", () => {
  gsap.matchMediaRefresh();
});

6. 鼠标跟随（quickTo 追逐函数）

const moveX = gsap.quickTo(".cursor", "x", {
  duration: 0.18,
  ease: "power3.out"
});
const moveY = gsap.quickTo(".cursor", "y", {
  duration: 0.18,
  ease: "power3.out"
});

window.addEventListener("pointermove", (event) => {
  moveX(event.clientX);
  moveY(event.clientY);
});

🧩 插件速查 >>>

// SplitText 文本拆分动画
import { SplitText } from "gsap/SplitText";

gsap.registerPlugin(SplitText);
const split = SplitText.create(".headline", { type: "chars,words" });
gsap.from(split.chars, { y: 24, opacity: 0, stagger: 0.03 });

🧵 时间轴与位置语法 >>>

基础控制

const tl = gsap.timeline();
tl.to(".el", { x: 100 })
  .to(".el", { y: 50 }, "+=0.3")    // 当前末尾再延迟 0.3s
  .to(".el", { scale: 1.2 }, "-=0.2")  // 重叠前一个 0.2s
  .play()
  .pause()
  .reverse()
  .seek("labelName");

时间位置符号

tl.from(".panel", { opacity: 0 }, 0)
  .from(".panel-title", { opacity: 0 }, "<0.1")
  .from(".panel-body", { opacity: 0 }, ">-0.1")
  .from(".panel-actions", { opacity: 0 }, "ready+=0.2");

🌊 缓动函数 >>>

常用 ease

• "power1.out" "power2.out" "power3.out"
• "power1.inOut" "power2.inOut"
• "back.out(1.7)"
• "elastic.out(1, 0.4)"
• "steps(5)"
• "none"

ease 组合表

// 函数值：每项按索引生成不同偏移
gsap.to(".dot", {
  x: (index) => index * 18,
  scale: (index) => 1 + index * 0.08,
  ease: "back.out(1.7)",
  stagger: 0.05
});

🧱 框架集成 >>>

gsap.context() 清理生命周期

import gsap from "gsap";

function Component() {
  useEffect(() => {
    const ctx = gsap.context(() => {
      gsap.from(".box", { y: 20, opacity: 0 });
    });
    return () => ctx.revert();  // 组件卸载时清理
  }, []);
}

动态注册插件（按需加载）

import gsap from "gsap";
import { ScrollTrigger } from "gsap/ScrollTrigger";

gsap.registerPlugin(ScrollTrigger);

🛠️ 工具函数 >>>

// 快速吸附到 0.5 的倍数
gsap.utils.snap(0.5, 1.3); // 1.5

// 范围限制
gsap.utils.clamp(0, 100, 150); // 100

🎚️ 控制与回调 >>>

const tween = gsap.to(".toast", {
  autoAlpha: 1,
  y: 0,
  paused: true,
  duration: 0.3
});

document.querySelector(".open").addEventListener("click", () => tween.restart());
document.querySelector(".close").addEventListener("click", () => tween.reverse());

🩺 性能与排障 >>>

• transform opacity：和 （GPU 加速，不触发 layout）
• will-change：只在短时间内为热点元素启用
• ScrollTrigger.refresh()
• ScrollTrigger.getAll().forEach(trigger => trigger.kill())
• gsap.config({ nullTargetWarn: false })

// 手风琴展开后刷新触发器
document.querySelector(".accordion")
  .addEventListener("transitionend", () => {
    ScrollTrigger.refresh();
  });

// 页面卸载前清理
window.addEventListener("beforeunload", () => {
  ScrollTrigger.getAll().forEach(trigger => trigger.kill());
});

⚙️ Tween vars 完整配置 >>>

基础动画属性

gsap.to(".box", {
  x: 100,
  y: 50,
  rotation: 45,
  scale: 1.2,
  opacity: 0.8,
  duration: 1
});

颜色与样式属性

gsap.to(".btn", {
  backgroundColor: "#ff6b6b",
  duration: 0.3
});

字符串增量

gsap.to(".draggable", {
  x: "+=200",
  duration: 0.5,
  ease: "power2.out"
});

时间控制

gsap.to(".loader", {
  rotation: 360,
  duration: 1,
  repeat: -1,
  repeatDelay: 0.5,
  yoyo: true,
  ease: "power1.inOut"
});

缓动（ease）

gsap.to(".modal", {
  y: 0,
  opacity: 1,
  duration: 0.4,
  ease: "back.out(1.7)"  // 带回弹
});

回调函数

gsap.to(".toast", {
  y: 0,
  opacity: 1,
  duration: 0.3,
  onStart: () => console.log("开始"),
  onUpdate: () => console.log("进度:", tween.progress()),
  onComplete: () => console.log("完成")
});

stagger（批量错峰）

gsap.from(".card", {
  y: 30,
  opacity: 0,
  duration: 0.4,
  stagger: {
    each: 0.08,
    from: "start",
    ease: "power2.inOut"
  }
});

特殊属性

// overwrite 示例
gsap.to(".box", { x: 100, duration: 1 });
gsap.to(".box", { x: 50, duration: 1, overwrite: "auto" }); // 自动覆盖前一个

// keyframes 示例
gsap.to(".ball", {
  keyframes: [
    { y: -50, duration: 0.2 },
    { y: 0, duration: 0.2, ease: "bounce.out" }
  ]
});

ScrollTrigger 配置（scrollTrigger）

ScrollTrigger.create({
  trigger: ".section",
  start: "top 80%",
  end: "bottom 20%",
  scrub: 1,
  pin: true,
  pinSpacing: false,
  toggleActions: "play none none reverse",
  markers: false
});

过滤器与 autoAlpha

gsap.to(".modal", {
  autoAlpha: 1,  // 等效于 opacity:1, visibility:visible
  duration: 0.3
});

gsap.to(".img", {
  filter: "grayscale(100%)",
  duration: 0.5
});

🧵 Timeline 完整 API >>>

创建与配置

const tl = gsap.timeline({
  defaults: { duration: 0.5, ease: "power2.out" },  // 所有子项的默认值
  paused: false,
  smoothChildTiming: true,    // 子项时间自动校准父级
  align: "sequence",          // 子项对齐方式
  onStart: () => {},
  onComplete: () => {}
});

Timeline 配置选项

添加动画（add / insert）

const tl = gsap.timeline();

tl.to(".a", { x: 100 })
  .addLabel("phase1")  // 添加标签
  .to(".b", { x: 100 }, "+=0.2")
  .call(() => console.log("回调"), null, "-=0.1")
  .add(() => console.log("直接添加函数"))
  .to(".c", { x: 100 }, "phase1+=0.3");  // 基于标签定位

标签控制

tl.addLabel("intro", 0)
  .from(".title", { opacity: 0 }, "intro")
  .from(".body", { opacity: 0 }, "intro+=0.2")
  .addLabel("ready", "+=0.5");

console.log(tl.getLabelTime("ready"));  // 1.7

时间位置语法（position 参数）

tl.to(".a", { x: 100 }, 0)         // 绝对时间 0
  .to(".b", { x: 100 }, "+=0.3")    // 当前末尾 +0.3s
  .to(".c", { x: 100 }, "-=0.2")    // 提前 0.2s 插入
  .to(".d", { x: 100 }, "<")        // 与 c 同起点
  .to(".e", { x: 100 }, ">")        // 在 c 结束后
  .to(".f", { x: 100 }, "ready")    // 在 ready 标签处
  .to(".g", { x: 100 }, "ready+=0.5"); // ready 后 0.5s

播放控制

tl.play();           // 播放
tl.pause();           // 暂停
tl.reverse();         // 反向
tl.seek("ready");     // 跳到 ready 标签
tl.progress(0.5);     // 跳到 50%
tl.timeScale(2);      // 2 倍速播放

查询

console.log(tl.duration());        // 总时长
console.log(tl.totalDuration());   // 含 repeat
console.log(tl.isActive());        // 是否播放中
tl.getChildren();                 // 所有子 Tween

销毁与回收

tl.kill();           // 杀死整个 timeline
tl.clear();          // 清空
tl.revert();         // 恢复初始

嵌套 Timeline

const innerTl = gsap.timeline({ paused: true });
innerTl.to(".inner", { x: 50 });

const outerTl = gsap.timeline();
outerTl.to(".outer", { x: 100 })
  .add(innerTl, "-=0.2");  // innerTl 作为子 timeline 插入

📋 Quick Ref >>>

安装

npm install gsap
# 或 CDN: https://cdnjs.com/libraries/gsap

插件导入（全部免费）

import gsap from "gsap";
import { ScrollTrigger, Flip, SplitText } from "gsap/all";
// 或按需单独导入
import ScrollTrigger from "gsap/ScrollTrigger";
import Flip from "gsap/Flip";
gsap.registerPlugin(ScrollTrigger, Flip);

核心速查