elite-gsap

Elite GSAP

Web 上最强大的动画库。所有插件现已 100% 免费。

2026 年更新：GSAP 免费开放

自 Webflow 收购 GSAP 后，所有 GSAP 插件（包括此前的“Club”插件）均可完全免费用于商业用途：

• ScrollTrigger
• SplitText
• Flip
• MorphSVG
• DrawSVG
• MotionPathPlugin
• Physics2D
• Inertia
• CustomEase

不再有许可限制。

---

快速参考

主题	参考文件
ScrollTrigger	scrolltrigger.md
SplitText	splittext.md
Flip 插件	flip-plugin.md
MorphSVG 和 DrawSVG	morphsvg-drawsvg.md
时间轴	timelines.md
框架集成	framework-integration.md
工具库	utility-library.md
平滑滚动（Lenis）	smooth-scroll.md

---

核心设置

安装

npm install gsap

插件注册

在应用入口处只注册一次插件：

import gsap from "gsap";
import { ScrollTrigger } from "gsap/ScrollTrigger";
import { SplitText } from "gsap/SplitText";
import { Flip } from "gsap/Flip";
import { DrawSVGPlugin } from "gsap/DrawSVGPlugin";
import { MorphSVGPlugin } from "gsap/MorphSVGPlugin";
import { MotionPathPlugin } from "gsap/MotionPathPlugin";

gsap.registerPlugin(
  ScrollTrigger,
  SplitText,
  Flip,
  DrawSVGPlugin,
  MorphSVGPlugin,
  MotionPathPlugin,
);

---

上下文与清理（重要）

始终使用 gsap.context() 为动画限定作用域。这可以防止 SPA 和基于组件的框架出现内存泄漏。

原生 JavaScript

// Create context scoped to a container
const ctx = gsap.context(() => {
  // All animations and ScrollTriggers created here
  // are automatically tracked
  gsap.from(".hero-title", { opacity: 0, y: 50 });
  gsap.from(".hero-description", { opacity: 0, y: 30, delay: 0.3 });

  ScrollTrigger.create({
    trigger: ".section",
    start: "top center",
    onEnter: () => console.log("entered"),
  });
}, containerElement); // Scope to container

// Later: Clean up everything
ctx.revert(); // Reverts all animations and kills ScrollTriggers

这样做的重要性

不使用上下文：

• 组件卸载后动画仍会继续
• ScrollTrigger 会继续监听已移除的元素
• 内存泄漏不断累积
• SPA 导航会导致动画失效

使用上下文：

• 调用一次 revert() 即可清理所有内容
• 适用于 React/Vue/Svelte 组件
• 不会留下过时的引用

---

必备动画模式

基础补间动画

// Animate TO a state
gsap.to(".element", {
  x: 100,
  opacity: 0.5,
  duration: 1,
  ease: "power2.out",
});

// Animate FROM a state
gsap.from(".element", {
  opacity: 0,
  y: 50,
  duration: 0.8,
  ease: "power3.out",
});

// FROM-TO for full control
gsap.fromTo(
  ".element",
  { opacity: 0, y: 50 },
  { opacity: 1, y: 0, duration: 0.8 },
);

// Set immediately (no animation)
gsap.set(".element", { opacity: 1, y: 0 });

交错动画

// Basic stagger
gsap.from(".card", {
  opacity: 0,
  y: 30,
  duration: 0.6,
  stagger: 0.1, // 100ms between each
});

// Advanced stagger
gsap.from(".grid-item", {
  opacity: 0,
  scale: 0.8,
  duration: 0.5,
  stagger: {
    each: 0.1,
    from: "center", // 'start', 'end', 'center', 'edges', 'random', or index
    grid: [4, 6], // For grid layouts
    axis: "x", // 'x', 'y', or null for both
  },
});

缓动

// Power eases (most common)
gsap.to(".el", { x: 100, ease: "power1.out" }); // Subtle
gsap.to(".el", { x: 100, ease: "power2.out" }); // Balanced (recommended)
gsap.to(".el", { x: 100, ease: "power3.out" }); // Snappy
gsap.to(".el", { x: 100, ease: "power4.out" }); // Dramatic

// Ease directions
// .in - starts slow, accelerates
// .out - starts fast, decelerates (default)
// .inOut - slow at both ends

// Special eases
gsap.to(".el", { x: 100, ease: "elastic.out(1, 0.3)" });
gsap.to(".el", { x: 100, ease: "back.out(1.7)" });
gsap.to(".el", { x: 100, ease: "bounce.out" });

// Custom ease
gsap.to(".el", { x: 100, ease: "M0,0 C0.7,0 0.3,1 1,1" }); // Bezier

回调

gsap.to(".element", {
  x: 100,
  duration: 1,
  onStart: () => console.log("Animation started"),
  onUpdate: () => console.log("Frame update"),
  onComplete: () => console.log("Animation complete"),
  onReverseComplete: () => console.log("Reversed to start"),
});

---

prefers-reduced-motion（重要）

始终尊重用户的动态效果偏好：

const mm = gsap.matchMedia();

mm.add("(prefers-reduced-motion: no-preference)", () => {
  // Full animations
  gsap.from(".hero", {
    opacity: 0,
    y: 50,
    duration: 1,
    ease: "power3.out",
  });
});

mm.add("(prefers-reduced-motion: reduce)", () => {
  // Instant or simple fade
  gsap.set(".hero", { opacity: 1, y: 0 });
  // Or: gsap.from('.hero', { opacity: 0, duration: 0.3 });
});

有关完整的模式，请参阅 elite-accessibility 技能。

---

GPU 加速属性

为实现 60fps 的性能，只为以下属性添加动画：

• x、y（translateX、translateY）
• xPercent、yPercent
• scale、scaleX、scaleY
• rotation、rotationX、rotationY
• opacity

绝不要为以下属性添加动画：

• width、height
• top、left、right、bottom
• margin、padding
• border-width

// GOOD - GPU accelerated
gsap.to(".card", { x: 100, y: 50, scale: 1.1, rotation: 5, opacity: 0.8 });

// BAD - Causes reflows
gsap.to(".card", { width: 200, height: 200, marginLeft: 50 });

---

ScrollTrigger 快速入门

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

// Basic scroll-triggered animation
gsap.from(".section-content", {
  opacity: 0,
  y: 50,
  duration: 1,
  scrollTrigger: {
    trigger: ".section",
    start: "top 80%", // When top of trigger hits 80% of viewport
    end: "bottom 20%",
    toggleActions: "play none none none",
    // markers: true  // Dev only
  },
});

// Pinned section
ScrollTrigger.create({
  trigger: ".sticky-section",
  start: "top top",
  end: "+=100%",
  pin: true,
  pinSpacing: true,
});

// Scrub animation (tied to scroll position)
gsap.to(".parallax-element", {
  y: -100,
  ease: "none",
  scrollTrigger: {
    trigger: ".parallax-section",
    start: "top bottom",
    end: "bottom top",
    scrub: true,
  },
});

完整的模式请参阅 scrolltrigger.md。

---

SplitText 快速入门

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

// Split text into characters
const split = new SplitText(".headline", {
  type: "chars,words,lines",
  linesClass: "line",
});

// Animate characters
gsap.from(split.chars, {
  opacity: 0,
  y: 50,
  rotationX: -90,
  stagger: 0.02,
  duration: 0.8,
  ease: "power4.out",
});

// IMPORTANT: Revert when done (or on cleanup)
// split.revert();

文本动画模式请参阅 splittext.md。

---

Flip 插件快速入门

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

// Capture current state
const state = Flip.getState(".cards");

// Make DOM changes
container.appendChild(newCard);
// or
card.classList.toggle("expanded");
// or
filterCards();

// Animate the change
Flip.from(state, {
  duration: 0.6,
  ease: "power2.inOut",
  stagger: 0.05,
  absolute: true, // Prevents layout shift during animation
  onEnter: (elements) => gsap.from(elements, { opacity: 0, scale: 0.8 }),
  onLeave: (elements) => gsap.to(elements, { opacity: 0, scale: 0.8 }),
});

布局动画模式请参阅 flip-plugin.md。

---

时间轴快速入门

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

tl.from(".hero-title", { opacity: 0, y: 50 })
  .from(".hero-description", { opacity: 0, y: 30 }, "-=0.5") // Overlap
  .from(".hero-cta", { opacity: 0, y: 20 }, "-=0.3")
  .from(".hero-image", { opacity: 0, scale: 0.9 }, "<"); // Same time as previous

// Control
tl.play();
tl.pause();
tl.reverse();
tl.seek(0.5); // Jump to 0.5 seconds
tl.progress(0.5); // Jump to 50%

编排模式请参阅 timelines.md。

---

常见模式

滚动时显示

const mm = gsap.matchMedia();

mm.add("(prefers-reduced-motion: no-preference)", () => {
  gsap.utils.toArray(".reveal").forEach((element) => {
    gsap.from(element, {
      opacity: 0,
      y: 40,
      duration: 0.8,
      ease: "power3.out",
      scrollTrigger: {
        trigger: element,
        start: "top 85%",
        toggleActions: "play none none none",
      },
    });
  });
});

水平滚动区块

const mm = gsap.matchMedia();

mm.add("(prefers-reduced-motion: no-preference)", () => {
  const panels = gsap.utils.toArray(".panel");
  const wrapper = document.querySelector(".horizontal-wrapper");

  gsap.to(panels, {
    xPercent: -100 * (panels.length - 1),
    ease: "none",
    scrollTrigger: {
      trigger: wrapper,
      pin: true,
      scrub: 1,
      snap: 1 / (panels.length - 1),
      end: () => "+=" + wrapper.scrollWidth,
    },
  });
});

磁吸按钮

const button = document.querySelector(".magnetic-btn");

button.addEventListener("mousemove", (e) => {
  const rect = button.getBoundingClientRect();
  const x = e.clientX - rect.left - rect.width / 2;
  const y = e.clientY - rect.top - rect.height / 2;

  gsap.to(button, {
    x: x * 0.3,
    y: y * 0.3,
    duration: 0.3,
    ease: "power2.out",
  });
});

button.addEventListener("mouseleave", () => {
  gsap.to(button, {
    x: 0,
    y: 0,
    duration: 0.5,
    ease: "elastic.out(1, 0.3)",
  });
});

遮罩文本显示

const split = new SplitText(".headline", { type: "lines", linesClass: "line" });

// Wrap each line in a mask container
split.lines.forEach((line) => {
  const wrapper = document.createElement("div");
  wrapper.style.overflow = "hidden";
  line.parentNode.insertBefore(wrapper, line);
  wrapper.appendChild(line);
});

gsap.from(split.lines, {
  yPercent: 100,
  opacity: 0,
  duration: 1,
  stagger: 0.1,
  ease: "power4.out",
});

---

调试

// Enable dev warnings
gsap.config({
  nullTargetWarn: true,
});

// ScrollTrigger markers (dev only)
ScrollTrigger.defaults({
  markers: process.env.NODE_ENV === "development",
});

// Log animation state
gsap.to(".el", {
  x: 100,
  onUpdate: function () {
    console.log("Progress:", this.progress());
  },
});

---

框架集成

有关以下内容，请参阅 framework-integration.md：

• 使用 @gsap/react 的 React
• Vue 组合式 API 模式
• Svelte 生命周期模式
• 原生 JavaScript 模块模式

---

相关技能

• elite-accessibility - 动态效果无障碍访问和 prefers-reduced-motion 模式
• elite-performance - 构建优化和 Core Web Vitals
• elite-css-animations - CSS 原生动画替代方案
• elite-layouts - 布局模式（便当网格、水平滚动、粘性区块）
• elite-brand-design - 品牌形象和视觉系统

---

Resources

• GSAP Docs
• GSAP Eases Visualizer
• ScrollTrigger Demos
• GreenSock Forums