EnlightenCode

GSAP 常见case ​

一、ScrollTrigger 核心 API 分类速查表 ​

1️⃣ 触发与区间类 ​

参数类型示例含义
triggerselector/Element".box"触发参考元素
startstring/number"top center"开始滚动点
endstring/number/function"+=500"结束滚动点
endTriggerselector".end"用另一个元素计算 end

start/end 语法

js
"elementPosition viewportPosition"

elementPosition:

css
top center bottom

viewportPosition:

css
top center bottom
百分比 80%

数值：

js
300 = scrollTop 300px
"+=500" = 相对 start

2️⃣ 映射控制 ​

参数类型示例作用
scrubboolean/numbertrue / 1滚动同步
toggleActionsstring"play pause resume reset"非 scrub 模式播放控制

3️⃣ 固定与布局 ​

参数类型示例说明
pinboolean/Elementtrue固定元素
pinSpacingbooleanfalse是否保留占位空间
anticipatePinnumber1提前补偿滚动抖动

4️⃣ 调试与生命周期 ​

参数类型示例用途
markersbooleantrue显示 start/end
onEnterfunction()=>{}进入回调
onLeavefunction()=>{}离开回调
onUpdatefunctionself=>{}滚动更新

二、工业级常见 Case 分类 ​

Case用途
1️⃣ 元素变形动画
2️⃣ 时间轴分段动画
3️⃣ Pin 固定叙事区
4️⃣ 横向滚动面板
5️⃣ 进入播放型动画
6️⃣ 滚动进度监听

三、完整版 HTML（直接复制可跑） ​

html
<!DOCTYPE html>
<html lang="en">

<head>
<meta charset="UTF-8">
<title>GSAP ScrollTrigger Cookbook</title>

<script src="https://unpkg.com/gsap@3/dist/gsap.min.js"></script>
<script src="https://unpkg.com/gsap@3/dist/ScrollTrigger.min.js"></script>

<style>
body {
  margin: 0;
  font-family: sans-serif;
}

section {
  height: 100vh;
  display: flex;
  align-items: center;
  justify-content: center;
  font-size: 40px;
}

/* demo blocks */

.box {
  width: 150px;
  height: 150px;
  background: #4f46e5;
}

.panel {
  background: #111;
  color: #fff;
}

.horizontal-wrapper {
  height: 100vh;
  overflow: hidden;
}

.horizontal {
  display: flex;
}

.slide {
  min-width: 100vw;
  height: 100vh;
  display: flex;
  justify-content: center;
  align-items: center;
}

.one { background: #0ea5e9; }
.two { background: #22c55e; }
.three { background: #f97316; }

.spacer {
  height: 100vh;
}
</style>
</head>

<body>

<!-- CASE 1 -->
<section>
  <div class="box" id="shapeBox"></div>
</section>

<!-- CASE 2 -->
<section class="panel">
  <div id="timelineBox" class="box"></div>
</section>

<!-- CASE 3 -->
<section class="panel" id="pinSection">
  PIN SECTION
</section>

<div class="spacer"></div>

<!-- CASE 4 -->
<div class="horizontal-wrapper">
  <div class="horizontal">
    <div class="slide one">ONE</div>
    <div class="slide two">TWO</div>
    <div class="slide three">THREE</div>
  </div>
</div>

<!-- CASE 5 -->
<section>
  <div class="box" id="fadeBox"></div>
</section>

<!-- CASE 6 -->
<section class="panel">
  Scroll Progress: <span id="progressText">0%</span>
</section>

<script>

gsap.registerPlugin(ScrollTrigger);

/* =====================================================
CASE 1 — 滚动变形动画 (scrub)
用途：官网视觉过渡、Hero 动画
===================================================== */

gsap.to("#shapeBox", {
  scrollTrigger: {
    trigger: "#shapeBox",
    start: "top 80%",
    end: "top 30%",
    scrub: true,
    markers: true
  },
  scale: 1.8,
  rotation: 180,
  borderRadius: "50%"
});


/* =====================================================
CASE 2 — Timeline 分段动画
用途：产品故事演示
===================================================== */

const tl = gsap.timeline({
  scrollTrigger: {
    trigger: "#timelineBox",
    start: "top center",
    end: "bottom center",
    scrub: true
  }
});

tl.to("#timelineBox", {
  x: 400,
  rotation: 90,
  duration: 1
})
.to("#timelineBox", {
  y: -200,
  scale: 0.5,
  backgroundColor: "#22c55e",
  duration: 1
});


/* =====================================================
CASE 3 — Pin 固定区域
用途：苹果官网叙事
===================================================== */

ScrollTrigger.create({
  trigger: "#pinSection",
  start: "top top",
  end: "+=100%",
  pin: true,
  scrub: true,
  anticipatePin: 1
});


/* =====================================================
CASE 4 — 横向滚动
用途：横向画廊
===================================================== */

const horizontal = document.querySelector(".horizontal");

gsap.to(horizontal, {
  x: () => -(horizontal.scrollWidth - window.innerWidth),
  ease: "none",
  scrollTrigger: {
    trigger: ".horizontal-wrapper",
    start: "top top",
    end: () => "+=" + horizontal.scrollWidth,
    pin: true,
    scrub: true
  }
});


/* =====================================================
CASE 5 — 进入播放动画 (非 scrub)
用途：进入视口播放一次
===================================================== */

gsap.from("#fadeBox", {
  scrollTrigger: {
    trigger: "#fadeBox",
    start: "top 80%",
    toggleActions: "play none none reverse"
  },
  opacity: 0,
  y: 100,
  duration: 1
});


/* =====================================================
CASE 6 — 滚动进度监听
用途：进度条 / 数字反馈
===================================================== */

ScrollTrigger.create({
  trigger: document.body,
  start: "top top",
  end: "bottom bottom",
  onUpdate(self) {
    document.getElementById("progressText").innerText =
      Math.round(self.progress * 100) + "%";
  }
});

</script>

</body>
</html>

四、你以后写 ScrollTrigger 的“万能模板” ​

js
ScrollTrigger.create({
  trigger: "",
  start: "",
  end: "",
  scrub: true,
  pin: false,
  markers: false,
  onUpdate: self => {}
});

五、工程级最佳实践（非常重要） ​

  1. ✅ transform 优先
css
x y scale rotate opacity
  1. ❌ 避免 layout
css
top left width height

  1. pin 不要嵌套

  2. React/Vue 中必须：

js
ScrollTrigger.refresh()