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）。

请始终使用camelCase命名属性（例如

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 — 配合repeat使用，使动画交替反向播放。
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（px）
`xPercent` , `yPercent`	translateX/Y（百分比）
`scale` , `scaleX` , `scaleY`	scale
`rotation`	rotate（角度）
`rotationX` , `rotationY`	3D旋转
`skewX` , `skewY`	skew
`transformOrigin`	transform-origin

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

内置缓动函数包括：

power1

–

power4

、

back

、

bounce

、

circ

、

elastic

、

expo

、

sine

。每个缓动函数都有

.in

、

.out

、

.inOut

变体。

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.

暂停或销毁屏幕外的动画。

References (loaded on demand)

参考文档（按需加载）

references/effects.md — Drop-in effects: typewriter text, audio visualizer. Read when needing ready-made effect patterns for HyperFrames.

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.
Store tween/timeline return value when controlling playback.

使用camelCase命名属性；优先使用变换别名和autoAlpha。
优先使用时间线而非通过delay链式调用；使用位置参数。
使用
```
addLabel()
```
添加标签，提升序列可读性。
将默认参数传入时间线构造函数。
保存补间/时间线的返回值以便控制播放。

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.
Create tweens before the DOM exists.
Skip cleanup — always kill tweens when no longer needed.

当变换属性可实现相同效果时，请勿动画布局属性（width/height/top/left）。
请勿在同一SVG元素上同时使用svgOrigin和transformOrigin。
当时间线可实现序列编排时，请勿通过delay链式调用动画。
请勿在DOM未加载前创建补间。
务必清理动画——不再需要时始终销毁补间。

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

注意事项