gsap-timeline

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GSAP Timeline

GSAP 时间轴

When to Use This Skill

适用场景

Apply when building multi-step animations, coordinating several tweens in sequence or parallel, or when the user asks about timelines, sequencing, or keyframe-style animation in GSAP.

Related skills: For single tweens and eases use gsap-core; for scroll-driven timelines use gsap-scrolltrigger; for React use gsap-react.

适用于构建多步骤动画、按顺序或并行协调多个补间动画，或用户询问GSAP中的时间轴、动画序列、关键帧样式动画相关问题时。

相关技能：单个补间动画和缓动效果请使用 gsap-core；滚动驱动时间轴请使用 gsap-scrolltrigger；React环境请使用 gsap-react。

Creating a Timeline

创建时间轴

javascript

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

By default, tweens are appended one after another. Use the position parameter to place tweens at specific times or relative to other tweens.

javascript

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

默认情况下，补间动画会依次追加。使用位置参数可将补间动画放置在特定时间点或相对于其他补间的位置。

Position Parameter

位置参数

Third argument (or position property in vars) controls placement:

Absolute:
```
1
```
— start at 1 second.
Relative (default):
```
"+=0.5"
```
— 0.5s after end;
```
"-=0.2"
```
— 0.2s before end.
Label:
```
"labelName"
```
— at that label;
```
"labelName+=0.3"
```
— 0.3s after label.
Placement:
```
"<"
```
— start when recently-added animation starts;
```
">"
```
— start when recently-added animation ends (default);
```
"<0.2"
```
— 0.2s after recently-added animation start.

Examples:

javascript

tl.to(".a", { x: 100 }, 0);           // at 0
tl.to(".b", { y: 50 }, "+=0.5");      // 0.5s after last end
tl.to(".c", { opacity: 0 }, "<");     // same start as previous
tl.to(".d", { scale: 2 }, "<0.2");    // 0.2s after previous start

第三个参数（或配置对象中的position属性）用于控制补间的位置：

绝对时间：
```
1
```
— 在第1秒开始。
相对位置（默认）：
```
"+=0.5"
```
— 在上一个动画结束后0.5秒开始；
```
"-=0.2"
```
— 在上一个动画结束前0.2秒开始。
标签定位：
```
"labelName"
```
— 在指定标签位置开始；
```
"labelName+=0.3"
```
— 在指定标签后0.3秒开始。
相对参照：
```
"<"
```
— 与最近添加的动画同时开始；
```
">"
```
— 在最近添加的动画结束时开始（默认）；
```
"<0.2"
```
— 在最近添加的动画开始后0.2秒开始。

示例：

javascript

tl.to(".a", { x: 100 }, 0);           // 在第0秒开始
tl.to(".b", { y: 50 }, "+=0.5");      // 在上一个动画结束后0.5秒开始
tl.to(".c", { opacity: 0 }, "<");     // 与上一个动画同时开始
tl.to(".d", { scale: 2 }, "<0.2");    // 在上一个动画开始后0.2秒开始

Timeline Defaults

时间轴默认配置

Pass defaults into the timeline so all child tweens inherit:

javascript

const tl = gsap.timeline({ defaults: { duration: 0.5, ease: "power2.out" } });
tl.to(".a", { x: 100 }).to(".b", { y: 50 }); // both use 0.5s and power2.out

可在时间轴中设置默认配置，所有子补间动画将继承这些配置：

javascript

const tl = gsap.timeline({ defaults: { duration: 0.5, ease: "power2.out" } });
tl.to(".a", { x: 100 }).to(".b", { y: 50 }); // 两个补间均使用0.5秒时长和power2.out缓动

Timeline Options (constructor)

时间轴构造器选项

paused: true — create paused; call
```
.play()
```
to start.
repeat, yoyo — same as tweens; apply to whole timeline.
onComplete, onStart, onUpdate — timeline-level callbacks.
defaults — vars merged into every child tween.

paused: true — 创建时处于暂停状态；调用
```
.play()
```
启动。
repeat, yoyo — 与补间动画用法相同；作用于整个时间轴。
onComplete, onStart, onUpdate — 时间轴级别的回调函数。
defaults — 合并到所有子补间动画的配置项。

Labels

标签功能

Add and use labels for readable, maintainable sequencing:

javascript

tl.addLabel("intro", 0);
tl.to(".a", { x: 100 }, "intro");
tl.addLabel("outro", "+=0.5");
tl.to(".b", { opacity: 0 }, "outro");
tl.play("outro");  // start from "outro"
tl.tweenFromTo("intro", "outro"); // pauses the timeline and returns a new Tween that animates the timeline's playhead from intro to outro with no ease.

添加并使用标签可实现可读性更强、更易维护的动画序列：

javascript

tl.addLabel("intro", 0);
tl.to(".a", { x: 100 }, "intro");
tl.addLabel("outro", "+=0.5");
tl.to(".b", { opacity: 0 }, "outro");
tl.play("outro");  // 从"outro"标签位置开始播放
tl.tweenFromTo("intro", "outro"); // 暂停时间轴并返回一个新的补间动画，该补间会带动时间轴的播放头从intro位置动画到outro位置，无缓动效果。

Nesting Timelines

嵌套时间轴

Timelines can contain other timelines.

javascript

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

时间轴可以嵌套其他时间轴。

javascript

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

Controlling Playback

播放控制

tl.play() / tl.pause()
tl.reverse() / tl.progress(1) then tl.reverse()
tl.restart() — from start.
tl.time(2) — seek to 2 seconds.
tl.progress(0.5) — seek to 50%.
tl.kill() — kill timeline and (by default) its children.

tl.play() / tl.pause() — 播放/暂停
tl.reverse() / tl.progress(1) 后调用 tl.reverse() — 反向播放
tl.restart() — 从开头重新启动
tl.time(2) — 跳转到第2秒位置
tl.progress(0.5) — 跳转到50%进度位置
tl.kill() — 销毁时间轴（默认同时销毁其子元素）

Official GSAP Best practices

官方GSAP最佳实践

✅ Prefer timelines for sequencing
✅ Use the position parameter (third argument) to place tweens at specific times or relative to labels.
✅ Add labels with
```
addLabel()
```
for readable, maintainable sequencing.
✅ Pass defaults into the timeline constructor so child tweens inherit duration, ease, etc.
✅ Put ScrollTrigger on the timeline (or top-level tween), not on tweens inside a timeline.

✅ 优先使用时间轴来编排动画序列
✅ 使用位置参数（第三个参数）将补间动画放置在特定时间点或相对于标签的位置
✅ 使用
```
addLabel()
```
添加标签，实现可读性更强、更易维护的动画序列
✅ 在时间轴构造器中传入默认配置，让子补间动画继承时长、缓动等属性
✅ 将ScrollTrigger绑定到时间轴（或顶级补间动画），而非时间轴内部的补间动画

Do Not

注意事项

❌ Chain animations with delay when a timeline can sequence them; prefer
```
gsap.timeline()
```
and the position parameter for multi-step animation.
❌ Forget to pass defaults (e.g.
```
defaults: { duration: 0.5, ease: "power2.out" }
```
) when many child tweens share the same duration or ease.
❌ Forget that duration on the timeline constructor is not the same as tween duration; timeline “duration” is determined by its children.
❌ Nest animations that contain a ScrollTrigger; ScrollTriggers should only be on top-level Tweens/Timelines.

❌ 当时间轴可实现动画序列编排时，避免使用delay来链式调用动画；多步骤动画优先使用
```
gsap.timeline()
```
和位置参数
❌ 当多个子补间动画共享相同时长或缓动效果时，不要忘记传入默认配置（例如
```
defaults: { duration: 0.5, ease: "power2.out" }
```
）
❌ 不要混淆时间轴构造器中的duration与补间动画的duration；时间轴的“时长”由其子元素决定
❌ 不要嵌套包含ScrollTrigger的动画；ScrollTrigger应仅绑定到顶级补间/时间轴