gsap-timeline

用途

GSAP Timeline 是一个官方 GSAP 技能，用于在 GSAP 中构建多步动画、协调多个补间（tween）的顺序或并行播放，以及按关键帧式的节奏编排动画。当用户需要把多个动画串联起来、安排先后与重叠时机，或询问时间线、时序、排序、关键帧式动画时，适合使用该技能。

相关技能分工：单个补间与缓动使用 gsap-core；滚动驱动的时间线使用 gsap-scrolltrigger；React 场景使用 gsap-react。

主要能力

创建时间线

使用 gsap.timeline() 创建时间线，并通过链式调用追加补间：

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 中的 position 属性）控制补间的放置位置：

绝对时间：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);           // 在 0 秒处
tl.to(".b", { y: 50 }, "+=0.5");      // 在上一个结束之后 0.5 秒
tl.to(".c", { opacity: 0 }, "<");     // 与上一个同时开始
tl.to(".d", { scale: 2 }, "<0.2");    // 在上一个开始后 0.2 秒

时间线默认值

可以在时间线构造时传入 defaults，让所有子补间继承：

const tl = gsap.timeline({ defaults: { duration: 0.5, ease: "power2.out" } });
tl.to(".a", { x: 100 }).to(".b", { y: 50 }); // 两者都使用 0.5 秒与 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");  // 从 "outro" 开始
tl.tweenFromTo("intro", "outro"); // 暂停时间线，并返回一个新的 Tween，将时间线的播放头从 intro 动画到 outro，不带缓动。

嵌套时间线

时间线可以包含其它时间线：

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()：终止时间线及其子项（默认）。

官方最佳实践与注意事项

推荐做法：

优先用时间线做时序编排。
用位置参数（第三个参数）把补间放到指定时间或相对于标签的位置。
用 addLabel() 添加标签，便于阅读与维护。
在时间线构造函数中传入 defaults，让子补间继承 duration、ease 等。
把 ScrollTrigger 放在时间线（或顶层补间）上，而不是时间线内部的补间上。

不要这样做：

能用时间线排序时，不要用 delay 链式堆叠动画；多步动画优先用 gsap.timeline() 与位置参数。
当多个子补间共享相同 duration 或 ease 时，不要忘记传 defaults。
不要忘记：时间线构造函数上的 duration 与补间的 duration 不是一回事，时间线的“时长”由子补间决定。
不要嵌套含 ScrollTrigger 的动画；ScrollTrigger 只应放在顶层 Tween 或 Timeline 上。

适用场景

需要把多个动画串联、安排先后与重叠、按标签组织节奏、构建主从嵌套动画，或需要对整段时间线做播放、暂停、反向、跳转控制时，适合使用该技能。涉及滚动触发时，应结合 gsap-scrolltrigger，并遵循上述 ScrollTrigger 放置限制。

限制

该技能仅覆盖 GSAP 时间线相关内容；ease、单个补间、滚动触发、React 集成等需参考对应的其它技能。资料未提供版本要求、浏览器兼容性或性能数据，暂未提供。