GSAP 使用指南：从 Tween 到 ScrollTrigger（v3+）

GSAP（GreenSock Animation Platform）是常用的 JavaScript 动画库，适合做页面动效、过渡、交互动画以及滚动驱动动画。

GSAP 动画演示：点击播放/重置

安装

CDN（适合快速测试）

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>

npm（推荐在项目中使用）

npm install gsap

import gsap from "gsap";

注册插件（以 ScrollTrigger 为例）：

import { ScrollTrigger } from "gsap/ScrollTrigger";
gsap.registerPlugin(ScrollTrigger);

核心概念

Tween（单个动画）

最常用三种写法：

gsap.to(target, { vars }); // 动画到目标值
gsap.from(target, { vars }); // 从指定值动画到当前状态
gsap.fromTo(target, { fromVars }, { toVars });

示例：

gsap.to(".box", {
  x: 500,
  y: 200,
  rotation: 360,
  scale: 1.5,
  duration: 2,
  ease: "power2.out",
  delay: 0.5,
});

Timeline（时间线：组织序列动画）

const tl = gsap.timeline({
  repeat: 2,
  yoyo: true,
  onComplete: () => console.log("完成"),
});

tl.to(".box1", { x: 300, duration: 1 })
  .to(".box2", { y: 200, rotation: 180 }, "-=0.5")
  .from(".title", { opacity: 0, y: 50 }, "+=0.3");

常用参数（Vars）

Transform 快捷属性

GSAP 属性	对应 CSS
`x`, `y`	`translateX`, `translateY`
`xPercent`, `yPercent`	百分比移动
`scale`, `scaleX`, `scaleY`	缩放
`rotation`	`rotate`
`skewX`, `skewY`	斜切

其他常用属性：

opacity
backgroundColor, color
width, height
borderRadius
任意 CSS 属性（使用 camelCase）

相对值写法：

gsap.to(".box", {
  x: "+=300",
  scale: "-=0.5",
});

常用特殊属性（Special Properties）

duration: 1.5
delay: 0.3
repeat: 3（-1 = 无限循环）
yoyo: true（往返播放）
ease: "power2.inOut"（常用：power1~4, elastic, bounce, back）
stagger: 0.1（多个元素错开动画）
回调：onComplete, onStart, onUpdate, onRepeat

插件

ScrollTrigger（滚动驱动动画）

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

gsap.registerPlugin(ScrollTrigger);

const sections = gsap.utils.toArray(".panel");

gsap.to(sections, {
  xPercent: -100 * (sections.length - 1),
  ease: "none",
  scrollTrigger: {
    trigger: ".container",
    pin: true,
    scrub: 1,
    snap: 1 / (sections.length - 1),
    end: () => "+=" + document.querySelector(".container").offsetWidth,
  },
});

常用 ScrollTrigger 配置：

trigger: ".element"
start: "top top" / "center center"
end: "+=1000"（相对值）
scrub: true（跟随滚动）
pin: true（固定元素）
markers: true（调试标记）

最小可运行示例（HTML）

<!DOCTYPE html>
<html lang="zh-CN">
  <head>
    <meta charset="UTF-8" />
    <title>GSAP Demo</title>
    <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
    <style>
      .box {
        width: 100px;
        height: 100px;
        background: #e91e63;
        margin: 50px;
      }
    </style>
  </head>
  <body>
    <div class="box"></div>

    <script>
      gsap.fromTo(
        ".box",
        { x: -200, rotation: -45, opacity: 0 },
        { x: 400, rotation: 360, opacity: 1, duration: 2.5, ease: "power3.out" }
      );
    </script>
  </body>
</html>