gsap

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GSAP (GreenSock) — Web Animation Skill

GSAP (GreenSock) — 网页动画技能指南

When to use

适用场景

High-quality UI/motion design: entrances, micro-interactions, page transitions
Timeline-based sequences (vs. scattered CSS transitions)
Scroll-driven storytelling (with ScrollTrigger)
Complex easing, staggering, orchestration across many elements

高品质UI/动效设计：入场动画、微交互、页面过渡
基于时间轴的序列动画（对比零散的CSS过渡动画）
滚动驱动的叙事效果（搭配ScrollTrigger）
多元素复杂缓动、stagger动画、协同编排

Key concepts & APIs

核心概念与API

Tweens:

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

Timelines:

const tl = gsap.timeline({ defaults, repeat, yoyo, paused })

Chain:

tl.to(...).from(...).addLabel('x').add(() => ...)

Position parameter: absolute
```
1.2
```
, relative
```
"+=0.5"
```
, overlap
```
"-=0.3"
```
, label
```
"intro"
```

Eases:

ease: "power2.out"

"expo.inOut"

"elastic.out(1, 0.3)"

Staggers:

stagger: 0.05

{ each, from: "start|center|end|random", grid }

Performance-friendly properties:
- Prefer transforms (
```
x
```
  ,
```
y
```
  ,
```
scale
```
  ,
```
rotation
```
  ) and opacity (
```
autoAlpha
```
  )

ScrollTrigger (plugin):

```
gsap.registerPlugin(ScrollTrigger)
```

Inline:

gsap.to(".box", { scrollTrigger: ".box", x: 500 })

Advanced:

scrollTrigger: { trigger, start, end, scrub, pin, snap, markers }

Standalone:

ScrollTrigger.create({ trigger, start, end, onUpdate, onToggle })

补间动画（Tweens）：

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

时间轴（Timelines）：

const tl = gsap.timeline({ defaults, repeat, yoyo, paused })

链式调用：

tl.to(...).from(...).addLabel('x').add(() => ...)

位置参数：绝对时间
```
1.2
```
、相对时间
```
"+=0.5"
```
、重叠时间
```
"-=0.3"
```
、标签定位
```
"intro"
```

缓动函数（Eases）：

ease: "power2.out"

"expo.inOut"

"elastic.out(1, 0.3)"

Stagger动画：

stagger: 0.05

或

{ each, from: "start|center|end|random", grid }

性能友好的属性：
- 优先使用transform属性（
```
x
```
  ,
```
y
```
  ,
```
scale
```
  ,
```
rotation
```
  ）和透明度（
```
autoAlpha
```
  ）

ScrollTrigger（插件）：

```
gsap.registerPlugin(ScrollTrigger)
```

内联使用：

gsap.to(".box", { scrollTrigger: ".box", x: 500 })

高级配置：

scrollTrigger: { trigger, start, end, scrub, pin, snap, markers }

独立创建：

ScrollTrigger.create({ trigger, start, end, onUpdate, onToggle })

Common pitfalls (and fixes)

常见陷阱及解决方法

Animating layout properties (top/left/width/height) → jank
- Use transforms, add
```
will-change: transform
```
  , avoid forced reflow.
ScrollTrigger “not firing” due to wrong trigger sizing/overflow containers
- Ensure trigger exists, has height, and check scroll container (nested scrolling needs config).
Not cleaning up in SPA/React
- Use
```
gsap.context()
```
  and revert on unmount; kill triggers (
```
ScrollTrigger.getAll().forEach(t => t.kill())
```
  ) if needed.
FOUC / measuring before fonts/images load
- Initialize after layout is stable; run
```
ScrollTrigger.refresh()
```
  after images load.

动画布局属性（top/left/width/height）→ 卡顿
- 使用transform属性，添加
```
will-change: transform
```
  ，避免强制重排。
ScrollTrigger“未触发”，原因是触发器尺寸错误/溢出容器
- 确保触发器存在、有高度，并检查滚动容器（嵌套滚动需要特殊配置）。
在SPA/React中未清理动画
- 使用
```
gsap.context()
```
  并在组件卸载时恢复；必要时销毁触发器（
```
ScrollTrigger.getAll().forEach(t => t.kill())
```
  ）。
FOUC（无样式内容闪烁）/ 在字体/图片加载前测量元素
- 在布局稳定后初始化；图片加载完成后调用
```
ScrollTrigger.refresh()
```
  。

Quick recipes

快速示例

1) Hero entrance (stagger)

1) 首页英雄区入场动画（stagger效果）

gsap.from(".hero [data-anim]", {
  y: 24,
  autoAlpha: 0,
  duration: 0.8,
  ease: "power2.out",
  stagger: 0.06,
});

gsap.from(".hero [data-anim]", {
  y: 24,
  autoAlpha: 0,
  duration: 0.8,
  ease: "power2.out",
  stagger: 0.06,
});

2) Sequenced timeline

2) 序列时间轴动画

const tl = gsap.timeline({ defaults: { ease: "power2.out", duration: 0.6 } });
tl.from(".nav", { y: -20, autoAlpha: 0 })
  .from(".hero-title", { y: 30, autoAlpha: 0 }, "-=0.2")
  .from(".hero-cta", { scale: 0.95, autoAlpha: 0 }, "-=0.2");

const tl = gsap.timeline({ defaults: { ease: "power2.out", duration: 0.6 } });
tl.from(".nav", { y: -20, autoAlpha: 0 })
  .from(".hero-title", { y: 30, autoAlpha: 0 }, "-=0.2")
  .from(".hero-cta", { scale: 0.95, autoAlpha: 0 }, "-=0.2");

3) Scroll-scrub pinned section

3) 滚动scrub固定区域动画

gsap.registerPlugin(ScrollTrigger);

gsap.timeline({
  scrollTrigger: {
    trigger: ".story",
    start: "top top",
    end: "+=800",
    scrub: 1,
    pin: true,
  },
}).to(".story .panel", { xPercent: -200 });

gsap.registerPlugin(ScrollTrigger);

gsap.timeline({
  scrollTrigger: {
    trigger: ".story",
    start: "top top",
    end: "+=800",
    scrub: 1,
    pin: true,
  },
}).to(".story .panel", { xPercent: -200 });

What to ask the user (if requirements unclear)

若需求不明确，可询问用户以下问题

Is this a static site or SPA (React/Next/Vue)? Any page transitions?
Do we need scroll-driven sections (pin/scrub/snap)?
Performance constraints (mobile support, reduced motion)?

这是静态网站还是SPA（React/Next/Vue）？是否需要页面过渡动画？
是否需要滚动驱动的区域（固定/scrub/吸附）？
性能约束（移动端支持、减少动效模式）？