GSAP
HyperFrames 合約
HyperFrames 透過其 gsap 運行時轉接器來控制 GSAP。你應該同步建立一個暫停的時間軸,並使用確切的 data-composition-id 將其註冊到 window.__timelines 上,讓 HyperFrames 可以驅動它。
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
<script>
window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });
tl.from(".title", { y: 48, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
tl.to(".accent", { scaleX: 1, duration: 0.5, ease: "power2.out" }, 0.25);
window.__timelines["main"] = tl; // key 必須等於組合根元素的 data-composition-id
</script>
- 註冊表的鍵須與組合根元素的
data-composition-id完全相符。 - 對於渲染關鍵的動畫,請勿調用
tl.play()。 - 請勿在非同步程式碼、計時器或事件處理器中建立時間軸。
- 保持迴圈為有限的。HyperFrames 只會渲染有限的影片長度。
核心補間方法
- gsap.to(targets, vars) — 從當前狀態動畫到
vars指定的狀態。最常用。 - gsap.from(targets, vars) — 從
vars指定的狀態動畫到當前狀態(入場效果)。 - gsap.fromTo(targets, fromVars, toVars) — 明確指定起始和結束狀態。
- gsap.set(targets, vars) — 立即套用(持續時間為 0)。
始終使用小駝峰式命名的屬性名稱(例如 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 — 有限的數字;在 HyperFrames 中永遠不要設為
-1。根據可見時長計算重複次數。yoyo — 與 repeat 一起使用,使動畫交替進行。 - onComplete、onStart、onUpdate — 回調函數。
- immediateRender —
from()/fromTo()的預設值為true。如果後續的補間動畫針對的是相同元素與屬性,請設為false以避免蓋寫。
變形與 CSS
偏好使用 GSAP 的變形別名,而非直接操作原始的 transform 字串:
| GSAP 屬性 | 等效屬性 |
|---|---|
x、y、z | translateX/Y/Z (px) |
xPercent、yPercent | translateX/Y (百分比) |
scale、scaleX、scaleY | scale |
rotation | rotate (度數) |
rotationX、rotationY | 3D 旋轉 |
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,
});
緩動函數
內建緩動函數: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,
});
},
);
時間軸
建立時間軸
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 會停留在合成器層上。當變形可以達到相同效果時,應避免使用 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 的即用型效果模式時請閱讀此文件。
最佳實踐
- 使用小駝峰式命名的屬性名稱;優先使用變形別名和 autoAlpha。
- 優先使用時間軸而非透過 delay 進行鏈式調用;善用位置參數。
- 使用
addLabel()添加標籤,使序列更易讀。 - 在時間軸建構函數中傳入 defaults。
- 當需要控制播放時,請儲存補間動畫/時間軸的回傳值。
不應做的事項
- 當變形可以達到相同效果時,避免對佈局屬性(width/height/top/left)進行動畫。
- 在同一 SVG 元素上同時使用 svgOrigin 和 transformOrigin。
- 當時間軸可以編排動畫順序時,不要使用 delay 進行鏈式調用。
- 在 DOM 尚未存在時建立補間動畫。
- 忽略清理動作 — 不再需要時務必終止所有補間動畫。
- 在 HyperFrames 組合中使用無限重複值。應使用根據可見時長計算得出的有限重複次數。
歸功與參考
- HyperFrames 轉接器原始碼:
packages/core/src/runtime/adapters/gsap.ts。 - GSAP 文件:https://gsap.com/docs/v3/
- GSAP 時間軸暫停與驅動行為:https://gsap.com/docs/v3/GSAP/Timeline/pause%28%29/