核心入口

• gsap.to(targets, vars)：从当前状态补间到目标状态
• gsap.from(targets, vars)：从给定初始状态进入当前状态
• gsap.fromTo(targets, fromVars, toVars)：显式声明起止状态
• gsap.set(targets, vars)：立即写值，不创建补间
• gsap.delayedCall(delay, fn)：延时执行回调

// 进入场动画
gsap.from(".hero-title", {
  y: 32,
  opacity: 0,
  duration: 0.8,
  ease: "power2.out"
});

// 交互反馈
gsap.to(".card", {
  scale: 1.02,
  duration: 0.2,
  paused: true
});

📦 模块导入与注册 >>>

• import gsap from "gsap"：导入核心
• import ScrollTrigger from "gsap/ScrollTrigger"：单独导入插件
• import { gsap, Flip, ScrollTrigger } from "gsap/all"：一次导入常用公开插件
• gsap.registerPlugin(ScrollTrigger, Flip)：注册后才能使用插件能力

import gsap from "gsap";
import ScrollTrigger from "gsap/ScrollTrigger";
import Flip from "gsap/Flip";

gsap.registerPlugin(ScrollTrigger, Flip);

🎛️ Tween 常用参数 >>>

• duration：动画时长，单位秒
• delay：延迟开始
• ease：缓动函数
• repeat -1：重复次数， 为无限
• yoyo：往返播放
• stagger：批量目标错峰执行
• onStart/onUpdate/onComplete：生命周期回调

// 批量列表项依次出现
gsap.to(".item", {
  opacity: 1,
  y: 0,
  duration: 0.5,
  stagger: {
    each: 0.08,
    from: "start"
  },
  ease: "power3.out"
});

🧵 时间轴 >>>

• gsap.timeline(options)：创建时间轴
• tl.to()：追加一个 tween
• tl.from()：追加进入动画
• tl.addLabel("intro")：增加标签
• tl.play()：播放
• tl.pause()：暂停
• tl.reverse()：反向播放
• tl.seek("intro")：跳到标签或时间点

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")
  .addLabel("ready");

时间位置语法

• 0：绝对时间
• "+=0.3"：在当前末尾后再延迟 0.3 秒
• "-=0.2"：与前一个动画重叠 0.2 秒
• "<"：与前一个动画同起点
• ">"：接在前一个动画结束后
• "label+=0.2"：基于标签偏移

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

🌊 缓动与函数值 >>>

• "power2.out"：常见 UI 进入动画
• "power2.inOut"：前后都平滑
• "back.out(1.7)"：带轻微回弹
• "elastic.out(1, 0.4)"：明显弹性
• "steps(5)"：分段动画
• x: (index) => index * 24：用函数按序生成值

gsap.to(".dot", {
  x: (index) => index * 18,
  scale: (index) => 1 + index * 0.08,
  ease: "back.out(1.7)",
  stagger: 0.05
});

🧲 ScrollTrigger >>>

• gsap.registerPlugin(ScrollTrigger)：注册插件
• trigger：触发元素
• start/end：起止位置
• scrub：将动画与滚动进度绑定
• pin：固定元素
• toggleActions：进入/离开时行为
• markers：调试定位

gsap.registerPlugin(ScrollTrigger);

gsap.to(".feature-image", {
  y: -80,
  ease: "none",
  scrollTrigger: {
    trigger: ".feature",
    start: "top bottom",
    end: "bottom top",
    scrub: true
  }
});

🧩 常用插件 >>>

• ScrollTrigger：滚动驱动动画
• ScrollToPlugin：平滑滚动到目标
• Flip：布局切换过渡
• MotionPathPlugin：沿路径运动
• Observer：统一鼠标、触控、滚轮输入
• Draggable：拖拽交互
• TextPlugin：文本渐变显示
• SplitText：文本拆分动效

// GSAP 3.13 起，原 bonus plugins 已免费开放
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 });

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

🧱 上下文与框架集成 >>>

• gsap.context(fn, scope)：记录当前上下文里创建的动画
• ctx.revert()：清理上下文动画
• gsap.matchMedia()：按媒体查询注册动画
• mm.add(query, fn)：为断点分别定义动画

const mm = gsap.matchMedia();

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

  return () => ctx.revert();
});

工具函数

• gsap.utils.toArray(selector)：把选择器结果转成数组
• gsap.utils.clamp(min, max, value)：限制数值范围
• gsap.utils.interpolate(a, b, progress)：按进度插值
• gsap.quickSetter(target, prop, unit)：创建高性能写值函数
• gsap.quickTo(target, prop, vars)：创建“追逐式”补间函数

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

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

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

📐 响应式重算 >>>

• gsap.matchMedia()：注册断点级动画
• mm.revert()：清理当前媒体查询中的动画
• gsap.matchMediaRefresh()：重新评估所有 matchMedia 逻辑
• ScrollTrigger.refresh()：重新计算滚动触发器

const mm = gsap.matchMedia();

mm.add("(max-width: 767px)", () => {
  gsap.set(".sidebar", { clearProps: "all" });
});

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

🎚️ 控制与回调 >>>

• tween.pause()：暂停
• tween.resume()：继续
• tween.restart()：重头播放
• tween.progress(0.5)：设置进度
• tween.kill()：销毁 tween
• tween.eventCallback("onComplete", fn)：动态修改回调

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：优先动画的属性
• will-change：只在短时间内为热点元素启用
• ScrollTrigger.refresh()：布局变化后刷新触发器
• ScrollTrigger.getAll().forEach(trigger => trigger.kill())：清理全部触发器
• gsap.defaults({...})：设置全局默认值
• gsap.config({ nullTargetWarn: false })：调整全局行为

// 内容懒加载或手风琴展开后，刷新 ScrollTrigger
document.querySelector(".accordion").addEventListener("transitionend", () => {
  ScrollTrigger.refresh();
});