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 秒
時間軸預設值
將 default 傳入時間軸，讓所有子補間動畫繼承：
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()新增 標籤，讓序列更具可讀性和可維護性。 - ✅ 在建構子中傳入 defaults，讓子補間動畫繼承持續時間、緩動函式等。
- ✅ 將 ScrollTrigger 放在時間軸（或頂層補間動畫）上，而不是放在時間軸內部的補間動畫上。
應避免的事項
- ❌ 當時間軸可以編排序列時，不要使用 delay 來鏈結動畫；對於多步驟動畫，應優先使用
gsap.timeline()和位置參數。 - ❌ 當許多子補間動畫共用相同的持續時間或緩動函式時，不要忘記傳入 defaults（例如
defaults: { duration: 0.5, ease: "power2.out" }）。 - ❌ 不要忘記時間軸建構子中的 duration 與補間動畫的持續時間不同；時間軸的「duration」由其子補間動畫決定。
- ❌ 不要巢狀包含 ScrollTrigger 的動畫；ScrollTrigger 只能放在頂層的補間動畫/時間軸上。