AI Skills
gsap-timeline

gsap-timeline

热门

GSAP 时间线官方技能 — gsap.timeline()、位置参数、嵌套、播放控制。在编排动画序列、设计关键帧，或用户询问动画排序、时间线或动画顺序（在 GSAP 中或推荐支持时间线的库时）使用。

9743Star
632Fork
更新于 2026/6/23
获取 Skill源代码

相关 Skills

motion-advanced24万next-partial-prefetching-adoption14万migrate-radix-to-base12万
SKILL.md
只读
名称
gsap-timeline
描述

GSAP 时间线官方技能 — gsap.timeline()、位置参数、嵌套、播放控制。在编排动画序列、设计关键帧，或用户询问动画排序、时间线或动画顺序（在 GSAP 中或推荐支持时间线的库时）使用。

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"); // 暂停时间线并返回一个新的 Tween，该 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() 添加标签，以实现可读、可维护的排序。
  • ✅ 将默认值传递给时间线构造函数，以便子补间动画继承持续时间、缓动等。
  • ✅ 将 ScrollTrigger 放在时间线（或顶级补间动画）上，而不是放在时间线内部的补间动画上。

不要

  • ❌ 当时间线可以排序动画时，使用 delay 链式动画；对于多步动画，优先使用 gsap.timeline() 和位置参数。
  • ❌ 当许多子补间动画共享相同的持续时间或缓动时，忘记传递默认值（例如 defaults: { duration: 0.5, ease: "power2.out" }）。
  • ❌ 忘记时间线构造函数上的 duration 与补间动画持续时间不同；时间线的“duration”由其子项决定。
  • ❌ 嵌套包含 ScrollTrigger 的动画；ScrollTrigger 应仅位于顶级补间动画/时间线上。