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; // キーはコンポジションルートの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) — 即座に適用します(duration 0)。
プロパティ名は常にキャメルケースを使用します(例:backgroundColor、rotationX)。
共通vars
- 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
生のtransform文字列よりもGSAPのトランスフォームエイリアスを推奨します:
| 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,
});
イージング
組み込みイージング: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 });
位置パラメータ
第3引数で配置を制御します:
- 絶対:
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 — 各子トゥイーンにマージされるvars。
タイムラインのネスト
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を使用してください。
クリーンアップ
画面外のアニメーションを一時停止または強制終了します。
リファレンス(オンデマンドロード)
- references/effects.md — ドロップインエフェクト:タイプライターテキスト、オーディオビジュアライザー。HyperFrames用の既製エフェクトパターンが必要な場合に参照してください。
ベストプラクティス
- キャメルケースのプロパティ名を使用します。トランスフォームエイリアスとautoAlphaを優先します。
- delayによるチェーンよりもタイムラインを優先します。位置パラメータを使用します。
addLabel()でラベルを追加して、読みやすいシーケンスにします。- デフォルトをタイムラインコンストラクタに渡します。
- 再生制御が必要な場合は、tween/timelineの戻り値を保存します。
禁止事項
- transformで十分な場合にレイアウトプロパティ(width/height/top/left)をアニメーションしないでください。
- 同じSVG要素でsvgOriginとtransformOriginを両方使用しないでください。
- タイムラインでシーケンス化できる場合に、delayでアニメーションをチェーンしないでください。
- DOMが存在する前にトゥイーンを作成しないでください。
- クリーンアップを省略しないでください。不要になったトゥイーンは必ずkillしてください。
- 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/