gsap

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GSAP

Core Tween Methods

核心补间方法

gsap.to(targets, vars) — animate from current state to
```
vars
```
. Most common.
gsap.from(targets, vars) — animate from
```
vars
```
to current state (entrances).
gsap.fromTo(targets, fromVars, toVars) — explicit start and end.
gsap.set(targets, vars) — apply immediately (duration 0).

Always use camelCase property names (e.g.

backgroundColor

rotationX

gsap.to(targets, vars) — 从当前状态动画到
```
vars
```
定义的状态，最常用的方法。
gsap.from(targets, vars) — 从
```
vars
```
定义的状态动画到当前状态（入场动画）。
gsap.fromTo(targets, fromVars, toVars) — 显式定义动画的起始和结束状态。
gsap.set(targets, vars) — 立即应用样式（动画时长为0）。

请始终使用驼峰命名的属性名（例如

backgroundColor

、

rotationX

）。

Common vars

常用参数

duration — seconds (default 0.5).
delay — seconds before start.

ease —

"power1.out"

(default),

"power3.inOut"

"back.out(1.7)"

"elastic.out(1, 0.3)"

"none"

stagger — number

0.1

or object:

{ amount: 0.3, from: "center" }

{ each: 0.1, from: "random" }

overwrite —
```
false
```
(default),
```
true
```
, or
```
"auto"
```
.
repeat — number or
```
-1
```
for infinite. yoyo — alternates direction with repeat.
onComplete, onStart, onUpdate — callbacks.
immediateRender — default
```
true
```
for from()/fromTo(). Set
```
false
```
on later tweens targeting the same property+element to avoid overwrite.

duration — 动画时长，单位为秒（默认值0.5）。
delay — 动画开始前的延迟时长，单位为秒。

ease — 缓动效果，可选值包括

"power1.out"

（默认）、

"power3.inOut"

、

"back.out(1.7)"

、

"elastic.out(1, 0.3)"

、

"none"

。

stagger — 交错动画间隔，可直接传入数字
```
0.1
```
，或者配置对象：
```
{ amount: 0.3, from: "center" }
```
、
```
{ each: 0.1, from: "random" }
```
。
overwrite — 动画覆盖策略，可选值：
```
false
```
（默认）、
```
true
```
、
```
"auto"
```
。
repeat — 重复次数，传入
```
-1
```
表示无限重复。yoyo — 重复时交替动画方向。
onComplete、onStart、onUpdate — 生命周期回调函数。
immediateRender — from()/fromTo()方法的默认值为
```
true
```
。如果后续有针对相同元素相同属性的补间动画，可设置为
```
false
```
避免样式覆盖。

Transforms and CSS

变换与CSS

Prefer GSAP's transform aliases over raw

transform

string:

GSAP property	Equivalent
`x` , `y` , `z`	translateX/Y/Z (px)
`xPercent` , `yPercent`	translateX/Y in %
`scale` , `scaleX` , `scaleY`	scale
`rotation`	rotate (deg)
`rotationX` , `rotationY`	3D rotate
`skewX` , `skewY`	skew
`transformOrigin`	transform-origin

autoAlpha — prefer over
```
opacity
```
. At 0: also sets
```
visibility: hidden
```
.
CSS variables —
```
"--hue": 180
```
.
svgOrigin (SVG only) — global SVG coordinate space origin. Don't combine with
```
transformOrigin
```
.
Directional rotation —
```
"360_cw"
```
,
```
"-170_short"
```
,
```
"90_ccw"
```
.
clearProps —
```
"all"
```
or comma-separated; removes inline styles on complete.
Relative values —
```
"+=20"
```
,
```
"-=10"
```
,
```
"*=2"
```
.

优先使用GSAP的变换别名，而不是原生的

transform

字符串：

GSAP 属性	等效属性
`x` 、 `y` 、 `z`	translateX/Y/Z (像素)
`xPercent` 、 `yPercent`	百分比形式的translateX/Y
`scale` 、 `scaleX` 、 `scaleY`	缩放
`rotation`	旋转 (角度)
`rotationX` 、 `rotationY`	3D 旋转
`skewX` 、 `skewY`	倾斜
`transformOrigin`	变换原点

autoAlpha — 优先使用该属性代替
```
opacity
```
。当值为0时，会同时设置
```
visibility: hidden
```
。
CSS 变量 — 用法示例：
```
"--hue": 180
```
。
svgOrigin (仅SVG可用) — 全局SVG坐标空间原点，请勿与
```
transformOrigin
```
同时使用。
定向旋转 — 可选值：
```
"360_cw"
```
、
```
"-170_short"
```
、
```
"90_ccw"
```
。
clearProps — 可传入
```
"all"
```
或者逗号分隔的属性名，动画结束后会移除对应的内联样式。
相对值 — 用法示例：
```
"+=20"
```
、
```
"-=10"
```
、
```
"*=2"
```
。

Function-Based Values

函数式传值

javascript

gsap.to(".item", {
  x: (i, target, targets) => i * 50,
  stagger: 0.1,
});

javascript

gsap.to(".item", {
  x: (i, target, targets) => i * 50,
  stagger: 0.1,
});

Easing

缓动效果

Built-in eases:

power1

–

power4

back

bounce

circ

elastic

expo

sine

. Each has

.in

.out

.inOut

. Custom: use CustomEase plugin (see references/plugins.md).

内置缓动函数：

power1

–

power4

、

back

、

bounce

、

circ

、

elastic

、

expo

、

sine

，每个都支持

.in

、

.out

、

.inOut

三种模式。自定义缓动可使用CustomEase插件（参考 references/plugins.md）。

Defaults

默认配置

javascript

gsap.defaults({ duration: 0.6, ease: "power2.out" });

javascript

gsap.defaults({ duration: 0.6, ease: "power2.out" });

Controlling Tweens

补间动画控制

javascript

const tween = gsap.to(".box", { x: 100 });
tween.pause();
tween.play();
tween.reverse();
tween.kill();
tween.progress(0.5);
tween.time(0.2);

javascript

const tween = gsap.to(".box", { x: 100 });
tween.pause();
tween.play();
tween.reverse();
tween.kill();
tween.progress(0.5);
tween.time(0.2);

gsap.matchMedia() (Responsive + Accessibility)

gsap.matchMedia()（响应式+无障碍支持）

Runs setup only when a media query matches; auto-reverts when it stops matching.

javascript

let mm = gsap.matchMedia();
mm.add(
  {
    isDesktop: "(min-width: 800px)",
    reduceMotion: "(prefers-reduced-motion: reduce)",
  },
  (context) => {
    const { isDesktop, reduceMotion } = context.conditions;
    gsap.to(".box", {
      rotation: isDesktop ? 360 : 180,
      duration: reduceMotion ? 0 : 2,
    });
  },
);

仅当媒体查询匹配时执行初始化逻辑，不匹配时自动回滚变更。

javascript

let mm = gsap.matchMedia();
mm.add(
  {
    isDesktop: "(min-width: 800px)",
    reduceMotion: "(prefers-reduced-motion: reduce)",
  },
  (context) => {
    const { isDesktop, reduceMotion } = context.conditions;
    gsap.to(".box", {
      rotation: isDesktop ? 360 : 180,
      duration: reduceMotion ? 0 : 2,
    });
  },
);

Timelines

时间线

Creating a Timeline

创建时间线

javascript

const tl = gsap.timeline({ defaults: { duration: 0.5, ease: "power2.out" } });
tl.to(".a", { x: 100 }).to(".b", { y: 50 }).to(".c", { opacity: 0 });

javascript

const tl = gsap.timeline({ defaults: { duration: 0.5, ease: "power2.out" } });
tl.to(".a", { x: 100 }).to(".b", { y: 50 }).to(".c", { opacity: 0 });

Position Parameter

位置参数

Third argument controls placement:

Absolute:
```
1
```
— at 1s
Relative:
```
"+=0.5"
```
— after end;
```
"-=0.2"
```
— before end
Label:
```
"intro"
```
,
```
"intro+=0.3"
```
Alignment:
```
"<"
```
— same start as previous;
```
">"
```
— after previous ends;
```
"<0.2"
```
— 0.2s after previous starts

javascript

tl.to(".a", { x: 100 }, 0);
tl.to(".b", { y: 50 }, "<"); // same start as .a
tl.to(".c", { opacity: 0 }, "<0.2"); // 0.2s after .b starts

第三个参数用于控制动画在时间线上的位置：

绝对位置：
```
1
```
— 从第1秒开始
相对位置：
```
"+=0.5"
```
— 在上一个动画结束后0.5秒开始；
```
"-=0.2"
```
— 在上一个动画结束前0.2秒开始
标签：
```
"intro"
```
、
```
"intro+=0.3"
```
— 从对应标签位置开始
对齐位置：
```
"<"
```
— 和上一个动画同时开始；
```
">"
```
— 在上一个动画结束后开始；
```
"<0.2"
```
— 在上一个动画开始后0.2秒开始

javascript

tl.to(".a", { x: 100 }, 0);
tl.to(".b", { y: 50 }, "<"); // 和.a同时开始
tl.to(".c", { opacity: 0 }, "<0.2"); // 在.b开始后0.2秒开始

Labels

Timeline Options

时间线配置

paused: true — create paused; call
```
.play()
```
to start.
repeat, yoyo — apply to whole timeline.
defaults — vars merged into every child tween.

paused: true — 创建时处于暂停状态，调用
```
.play()
```
方法启动
repeat、yoyo — 应用到整个时间线的所有动画
defaults — 所有子补间动画都会继承的默认参数

Nesting Timelines

嵌套时间线

javascript

const master = gsap.timeline();
const child = gsap.timeline();
child.to(".a", { x: 100 }).to(".b", { y: 50 });
master.add(child, 0);

javascript

const master = gsap.timeline();
const child = gsap.timeline();
child.to(".a", { x: 100 }).to(".b", { y: 50 });
master.add(child, 0);

Playback Control

播放控制

tl.play()

tl.pause()

tl.reverse()

tl.restart()

tl.time(2)

tl.progress(0.5)

tl.kill()

支持方法：

tl.play()

、

tl.pause()

、

tl.reverse()

、

tl.restart()

、

tl.time(2)

、

tl.progress(0.5)

、

tl.kill()

。

Performance

性能优化

Prefer Transform and Opacity

优先使用变换和透明度属性

Animating

scale

rotation

opacity

stays on the compositor. Avoid

width

height

top

left

when transforms achieve the same effect.

动画属性

、

scale

、

rotation

、

opacity

会在合成线程处理，性能更好。如果变换属性可以实现相同效果，避免使用

width

、

height

、

top

、

left

等布局属性。

will-change

css

will-change: transform;

Only on elements that actually animate.

css

will-change: transform;

仅添加到实际会执行动画的元素上。

gsap.quickTo() for Frequent Updates

高频更新场景使用gsap.quickTo()

javascript

let xTo = gsap.quickTo("#id", "x", { duration: 0.4, ease: "power3" }),
  yTo = gsap.quickTo("#id", "y", { duration: 0.4, ease: "power3" });
container.addEventListener("mousemove", (e) => {
  xTo(e.pageX);
  yTo(e.pageY);
});

javascript

let xTo = gsap.quickTo("#id", "x", { duration: 0.4, ease: "power3" }),
  yTo = gsap.quickTo("#id", "y", { duration: 0.4, ease: "power3" });
container.addEventListener("mousemove", (e) => {
  xTo(e.pageX);
  yTo(e.pageY);
});

Stagger > Many Tweens

优先使用stagger而非多个独立补间

Use

stagger

instead of separate tweens with manual delays.

使用

stagger

配置交错动画，而不是手动给多个补间添加延迟。

Cleanup

资源清理

Pause or kill off-screen animations. In frameworks, revert context on unmount.

暂停或销毁屏幕外的动画。在框架中使用时，组件卸载时要回滚上下文变更。

References (loaded on demand)

参考文档（按需加载）

references/scrolltrigger.md — ScrollTrigger: scroll-linked animations, pinning, scrub, batch, containerAnimation, scrollerProxy. Read when building scroll-driven UI, parallax, or pinned sections.
references/plugins.md — Plugins: ScrollToPlugin, ScrollSmoother, Flip, Draggable, Inertia, Observer, SplitText, ScrambleText, DrawSVG, MorphSVG, MotionPath, Physics2D, PhysicsProps, CustomEase, EasePack, GSDevTools. Read when using any GSAP plugin.
references/utils.md — gsap.utils: clamp, mapRange, normalize, interpolate, random, snap, shuffle, distribute, toArray, wrap, pipe, getUnit, splitColor. Read when using utility helpers.
references/react.md — React: useGSAP hook, refs, gsap.context(), cleanup, contextSafe, SSR. Read when using GSAP in React or Next.js.
references/frameworks.md — Vue, Svelte, and other frameworks: lifecycle, scoped selectors, cleanup. Read when using GSAP in Vue, Nuxt, Svelte, or SvelteKit.
references/effects.md — Drop-in effects: typewriter text, audio visualizer. Read when needing ready-made effect patterns for HyperFrames.

references/scrolltrigger.md — ScrollTrigger：滚动联动动画、固定定位、scrub、批量处理、containerAnimation、scrollerProxy。开发滚动驱动UI、视差效果、固定定位区块时可查阅。
references/plugins.md — 插件：ScrollToPlugin、ScrollSmoother、Flip、Draggable、Inertia、Observer、SplitText、ScrambleText、DrawSVG、MorphSVG、MotionPath、Physics2D、PhysicsProps、CustomEase、EasePack、GSDevTools。使用任意GSAP插件时可查阅。
references/utils.md — gsap.utils工具方法：clamp、mapRange、normalize、interpolate、random、snap、shuffle、distribute、toArray、wrap、pipe、getUnit、splitColor。使用工具辅助函数时可查阅。
references/react.md — React集成：useGSAP钩子、refs、gsap.context()、清理逻辑、contextSafe、SSR。在React或Next.js中使用GSAP时可查阅。
references/frameworks.md — Vue、Svelte等其他框架集成：生命周期、作用域选择器、清理逻辑。在Vue、Nuxt、Svelte或SvelteKit中使用GSAP时可查阅。
references/effects.md — 开箱即用效果：打字机文字、音频可视化。需要为HyperFrames使用现成效果模板时可查阅。

Best Practices

最佳实践

Use camelCase property names; prefer transform aliases and autoAlpha.
Prefer timelines over chaining with delay; use the position parameter.
Add labels with
```
addLabel()
```
for readable sequencing.
Pass defaults into timeline constructor.
Use gsap.matchMedia() for responsive breakpoints and prefers-reduced-motion.
Store tween/timeline return value when controlling playback.
Register every plugin with
```
gsap.registerPlugin()
```
before use.

使用驼峰命名的属性名；优先使用变换别名和autoAlpha属性。
优先使用时间线而非通过delay链式调用动画；使用位置参数控制动画时序。
用
```
addLabel()
```
添加标签提升序列动画的可读性。
将默认配置传入时间线构造函数。
使用gsap.matchMedia()处理响应式断点和减少动效偏好设置。
需要控制播放状态时，存储补间/时间线的返回值。
使用插件前必须通过
```
gsap.registerPlugin()
```
注册。

Do Not

禁止行为

Animate layout properties (width/height/top/left) when transforms suffice.
Use both svgOrigin and transformOrigin on the same SVG element.
Chain animations with delay when a timeline can sequence them.
Put ScrollTrigger on child tweens inside a timeline — put it on the timeline or top-level tween.
Nest ScrollTriggered animations inside a parent timeline.
Use scrub and toggleActions together on the same ScrollTrigger.
Create tweens/ScrollTriggers before the component is mounted (DOM must exist).
Skip cleanup — always revert context or kill tweens on unmount.
Ship GSDevTools to production.

变换属性可以实现需求时，不要动画布局属性（width/height/top/left）。
不要在同一个SVG元素上同时使用svgOrigin和transformOrigin。
可以用时间线编排动画时，不要通过delay链式调用动画。
不要给时间线内的子补间添加ScrollTrigger配置——应该给时间线本身或者顶层补间添加。
不要在父时间线内嵌套带ScrollTrigger的动画。
不要在同一个ScrollTrigger上同时使用scrub和toggleActions。
不要在组件挂载完成前创建补间/ScrollTrigger（必须等待DOM存在）。
不要省略清理逻辑——组件卸载时始终回滚上下文或者销毁补间动画。
不要将GSDevTools部署到生产环境。

gsap

Original

Translation

GSAP

GSAP

Core Tween Methods

核心补间方法

Common vars

常用参数

Transforms and CSS

变换与CSS

Function-Based Values

函数式传值

Easing

缓动效果

Defaults

默认配置

Controlling Tweens

补间动画控制

gsap.matchMedia() (Responsive + Accessibility)

gsap.matchMedia()（响应式+无障碍支持）

Timelines

时间线

Creating a Timeline

创建时间线

Position Parameter

位置参数

Labels

标签

Timeline Options

时间线配置

Nesting Timelines

嵌套时间线

Playback Control

播放控制

Performance

性能优化

Prefer Transform and Opacity

优先使用变换和透明度属性

will-change

will-change

gsap.quickTo() for Frequent Updates

高频更新场景使用gsap.quickTo()

Stagger > Many Tweens

优先使用stagger而非多个独立补间

Cleanup

资源清理

References (loaded on demand)

参考文档（按需加载）

Best Practices

最佳实践

Do Not

禁止行为