gsap-timeline

GSAP 时间线

整理自 GreenSock 官方 GSAP 技能：https://github.com/greensock/gsap-skills

何时使用此技能

在构建多步骤动画、按顺序或并行协调多个补间动画，或用户询问 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" }）。
• ❌ 勿忘记，时间线构造函数中的 duration 与补间动画时长不同；时间线的“时长”由其子项决定。
• ❌ 勿嵌套包含 ScrollTrigger 的动画；ScrollTrigger 只能添加到顶层 Tweens/Timelines 上。