gsap-timeline

GSAP 时间轴

何时使用此技能

在构建多步骤动画、按顺序或并行协调多个补间动画，或用户询问 GSAP 中的时间轴、动画排序或关键帧式动画时使用。

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

创建时间轴

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 });

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

位置参数

第三个参数（或 vars 中的位置属性）用于控制位置：

• 绝对位置：1 — 在 1 秒时开始。
• 相对位置（默认）："+=0.5" — 在结束后 0.5 秒开始；"-=0.2" — 在结束前 0.2 秒开始。
• 标签："labelName" — 在该标签处开始；"labelName+=0.3" — 在标签后 0.3 秒开始。
• 定位方式："<" — 在最近添加的动画开始时开始；">" — 在最近添加的动画结束时开始（默认）；"<0.2" — 在最近添加的动画开始后 0.2 秒开始。

示例：

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

时间轴默认值

将默认值传入时间轴，让所有子补间动画继承：

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

时间轴选项（构造函数）

• paused: true — 创建为暂停状态；调用 .play() 开始播放。
• repeat、yoyo — 与补间动画相同；应用于整个时间轴。
• onComplete、onStart、onUpdate — 时间轴级别的回调。
• defaults — 合并到每个子补间动画中的 vars。

标签

添加并使用标签，让动画排序清晰易维护：

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.

嵌套时间轴

时间轴可以包含其他时间轴。

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");

控制播放

• tl.play() / tl.pause()
• tl.reverse() / tl.progress(1) 然后 tl.reverse()
• tl.restart() — 从头开始。
• tl.time(2) — 跳转到 2 秒处。
• tl.progress(0.5) — 跳转到 50% 处。
• tl.kill() — 终止时间轴以及（默认情况下）其子项。

GSAP 官方最佳实践

• ✅ 序列动画优先使用时间轴
• ✅ 使用位置参数（第三个参数）将补间动画放置在特定时间或相对于标签的位置。
• ✅ 使用 addLabel() 添加标签，让动画排序清晰易维护。
• ✅ 将默认值传入时间轴构造函数，让子补间动画继承持续时间、缓动等设置。
• ✅ 将 ScrollTrigger 放在时间轴（或顶层补间动画）上，而不是放在时间轴内部的补间动画上。

避免

• ❌ 当时间轴可以完成动画排序时，不要用 delay 串联动画；多步骤动画优先使用 gsap.timeline() 和位置参数。
• ❌ 当许多子补间动画共用相同的持续时间或缓动时，不要忘记传入默认值（例如 defaults: { duration: 0.5, ease: "power2.out" }）。
• ❌ 不要忘记，时间轴构造函数中的持续时间与补间动画的持续时间不同；时间轴的“持续时间”由其子项决定。
• ❌ 不要嵌套包含 ScrollTrigger 的动画；ScrollTrigger 只能放在顶层 Tween/Timeline 上。