GSAP
核心補間方法
- gsap.to(targets, vars) — 從當前狀態動畫到
vars所指定的值。最常用。 - gsap.from(targets, vars) — 從
vars所指定的值動畫到當前狀態（入場動畫）。 - gsap.fromTo(targets, fromVars, toVars) — 明確指定起始與結束狀態。
- gsap.set(targets, vars) — 立即套用屬性（持續時間為 0）。
務必使用駝峰式（camelCase） 屬性名稱（例如 backgroundColor、rotationX）。
常見變數
- duration — 持續時間，單位為秒（預設 0.5）。
- delay — 開始前的延遲時間，單位為秒。
- ease —
"power1.out"（預設）、"power3.inOut"、"back.out(1.7)"、"elastic.out(1, 0.3)"、"none"。 - stagger — 可以是數字
0.1或物件：{ amount: 0.3, from: "center" }、{ each: 0.1, from: "random" }。 - overwrite —
false（預設）、true或"auto"。 - repeat — 重複次數，設為
-1表示無限重複。yoyo — 搭配 repeat 使用，會交替動畫方向。 - onComplete、onStart、onUpdate — 回呼函式。
- immediateRender — 對於 from()/fromTo() 預設為
true。若後續有針對相同屬性與元素的補間時，應設為false以避免被覆蓋。
Transform 與 CSS
優先使用 GSAP 的 transform 別名，而非原始的 transform 字串：
| GSAP 屬性 | 等效 CSS 屬性 |
|---|---|
x, y, z | translateX/Y/Z (px) |
xPercent, yPercent | translateX/Y (%) |
scale, scaleX, scaleY | scale |
rotation | rotate (deg) |
rotationX, rotationY | 3D rotate |
skewX, skewY | skew |
transformOrigin | transform-origin |
- autoAlpha — 優先於
opacity使用。設為 0 時，同時會設定visibility: hidden。 - CSS 變數 —
"--hue": 180。 - svgOrigin (僅限 SVG) — 全域 SVG 座標空間的原點。請勿與
transformOrigin同時使用。 - 定向旋轉 —
"360_cw"、"-170_short"、"90_ccw"。 - clearProps —
"all"或逗號分隔的屬性列表；動畫完成時移除內聯樣式。 - 相對值 —
"+=20"、"-=10"、"*=2"。
函數式值
gsap.to(".item", {
x: (i, target, targets) => i * 50,
stagger: 0.1,
});
彈性曲線（Easing）
內建曲線：power1–power4、back、bounce、circ、elastic、expo、sine。每個曲線都有 .in、.out、.inOut 三種變化。
預設值
gsap.defaults({ duration: 0.6, ease: "power2.out" });
控制補間
const tween = gsap.to(".box", { x: 100 });
tween.pause();
tween.play();
tween.reverse();
tween.kill();
tween.progress(0.5);
tween.time(0.2);
gsap.matchMedia()（回應式 + 無障礙）
只在符合媒體查詢時執行設定；當媒體查詢不再符合時會自動還原。
let mm = gsap.matchMedia();
mm.add(
{
isDesktop: "(min-width: 800px)",
reduceMotion: "(prefers-reduced-motion: reduce)",
},
(context) => {
const { isDesktop, reduceMotion } = context.conditions;
gsap.to(".box", {
rotation: isDesktop ? 360 : 180,
duration: reduceMotion ? 0 : 2,
});
},
);
時間軸（Timeline）
建立時間軸
const tl = gsap.timeline({ defaults: { duration: 0.5, ease: "power2.out" } });
tl.to(".a", { x: 100 }).to(".b", { y: 50 }).to(".c", { opacity: 0 });
位置參數
第三個引數控制插入位置：
- 絕對位置：
1— 在 1 秒處 - 相對位置：
"+=0.5"— 在上一動畫結束後；"-=0.2"— 在上一動畫結束前 - 標籤：
"intro"、"intro+=0.3" - 對齊：
"<"— 與上一動畫同時開始；">"— 在上一動畫結束後開始；"<0.2"— 在上一動畫開始後 0.2 秒
tl.to(".a", { x: 100 }, 0);
tl.to(".b", { y: 50 }, "<"); // 與 .a 同時開始
tl.to(".c", { opacity: 0 }, "<0.2"); // 在 .b 開始後 0.2 秒
標籤
tl.addLabel("intro", 0);
tl.to(".a", { x: 100 }, "intro");
tl.addLabel("outro", "+=0.5");
tl.play("outro");
tl.tweenFromTo("intro", "outro");
時間軸選項
- paused: true — 建立暫停的時間軸；呼叫
.play()開始播放。 - repeat、yoyo — 套用至整個時間軸。
- defaults — 合併至每個子補間的變數。
巢狀時間軸
const master = gsap.timeline();
const child = gsap.timeline();
child.to(".a", { x: 100 }).to(".b", { y: 50 });
master.add(child, 0);
播放控制
tl.play()、tl.pause()、tl.reverse()、tl.restart()、tl.time(2)、tl.progress(0.5)、tl.kill()。
效能
優先使用 Transform 和 Opacity
動畫 x、y、scale、rotation、opacity 會停留在合成器層。當 transform 可以達到相同效果時，應避免使用 width、height、top、left。
will-change
will-change: transform;
僅在實際會動畫的元素上使用。
gsap.quickTo() 處理頻繁更新
let xTo = gsap.quickTo("#id", "x", { duration: 0.4, ease: "power3" }),
yTo = gsap.quickTo("#id", "y", { duration: 0.4, ease: "power3" });
container.addEventListener("mousemove", (e) => {
xTo(e.pageX);
yTo(e.pageY);
});
使用 Stagger 而非多個補間
使用 stagger 而非手動設定延遲的多個獨立補間。
清理
暫停或終止螢幕外的動畫。
參考資料（按需求載入）
- references/effects.md — 即用型效果：打字機文字、音訊視覺化效果。當需要為 HyperFrames 準備現成的動畫模式時閱讀。
最佳實踐
- 使用駝峰式屬性名稱；優先使用 transform 別名和 autoAlpha。
- 優先使用時間軸，而非透過 delay 串聯；使用位置參數。
- 使用
addLabel()加入標籤，讓序列更易讀。 - 在時間軸建構子中傳入 defaults。
- 當需要控制播放時，儲存補間或時間軸的回傳值。
禁止事項
- 當 transform 可以達到效果時，不要動畫版面屬性（width/height/top/left）。
- 在同一個 SVG 元素上同時使用 svgOrigin 和 transformOrigin。
- 當時間軸可以安排序列時，不要使用 delay 來串聯動畫。
- 在 DOM 建立之前就建立補間。
- 忽略清理 — 不再需要時務必終止補間。