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 中的 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 秒
时间线默认值
将默认值传递给时间线，以便所有子补间接继承：
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 — 合并到每个子补间中的变量。
标签
添加和使用标签以实现清晰可维护的序列编排：
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，无缓动效果。
嵌套时间线
时间线可以包含其他时间线。
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 应仅位于顶层补间/时间线上。