GSAP Timeline 是 GSAP 官方提供的用于时间线编排的技能，主要解决多步骤动画的排序与协调问题。当需要构建多步动画、按顺序或并行协调多个补间，或用户询问 GSAP 中的时间线、序列编排、关键帧式动画时，可使用本技能。相关技能方面：单个补间与缓动使用 gsap-core；滚动驱动的时间线使用 gsap-scrolltrigger；React 场景使用 gsap-react。
创建时间线
使用 gsap.timeline() 创建时间线，随后通过链式 .to() 添加补间：
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.5s 和 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() —— 杀死时间线，默认连同其子级一起杀死。
官方 GSAP 最佳实践
✅ 优先使用时间线进行序列编排。
✅ 使用位置参数（第三个参数）将补间放置在特定时间或相对于标签的位置。
✅ 使用 addLabel() 添加标签，使序列编排可读、易维护。
✅ 将 defaults 传入时间线构造函数，使子补间继承 duration、ease 等。
✅ 将 ScrollTrigger 放在时间线（或顶层补间）上，而不是时间线内部的补间上。
不要
❌ 当时间线可以完成序列编排时，不要用 delay 链接动画；多步动画优先使用 gsap.timeline() 和位置参数。
❌ 当许多子补间共享相同的 duration 或 ease 时，不要忘记传入 defaults（例如 defaults: { duration: 0.5, ease: "power2.out" }）。
❌ 不要忘记时间线构造函数上的 duration 与补间的 duration 不同；时间线的“duration”由其子级决定。
❌ 不要嵌套包含 ScrollTrigger 的动画；ScrollTrigger 只应放在顶层 Tween/Timeline 上。