gsap-timeline

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 });

デフォルトでは、トゥイーンは次々に追加されます。位置パラメーターを使うと、特定の時刻やほかのトゥイーンを基準とする位置にトゥイーンを配置できます。

位置パラメーター

第 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);           // at 0
tl.to(".b", { y: 50 }, "+=0.5");      // 0.5s after last end
tl.to(".c", { opacity: 0 }, "<");     // same start as previous
tl.to(".d", { scale: 2 }, "<0.2");    // 0.2s after previous start

タイムラインのデフォルト値

タイムラインにデフォルト値を渡すと、すべての子トゥイーンに継承されます。

const tl = gsap.timeline({ defaults: { duration: 0.5, ease: "power2.out" } });
tl.to(".a", { x: 100 }).to(".b", { y: 50 }); // both use 0.5s and power2.out

タイムラインのオプション（コンストラクター）

• paused: true — 一時停止した状態で作成します。開始するには .play() を呼び出します。
• repeat、yoyo — トゥイーンと同様のオプションで、タイムライン全体に適用されます。
• onComplete、onStart、onUpdate — タイムラインレベルのコールバックです。
• defaults — すべての子トゥイーンにマージされる vars です。

ラベル

読みやすく保守しやすいシーケンスにするため、ラベルを追加して使用します。

tl.addLabel("intro", 0);
tl.to(".a", { x: 100 }, "intro");
tl.addLabel("outro", "+=0.5");
tl.to(".b", { opacity: 0 }, "outro");
tl.play("outro");  // start from "outro"
tl.tweenFromTo("intro", "outro"); // pauses the timeline and returns a new Tween that animates the timeline's playhead from intro to outro with no ease.

タイムラインのネスト

タイムラインには、ほかのタイムラインを含めることができます。

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 公式のベストプラクティス

• ✅ シーケンスにはタイムラインを優先して使用します。
• ✅ 位置パラメーター（第 3 引数）を使って、特定の時刻やラベルを基準とする位置にトゥイーンを配置します。
• ✅ 読みやすく保守しやすいシーケンスにするため、addLabel() でラベルを追加します。
• ✅ タイムラインのコンストラクターにデフォルト値を渡して、子トゥイーンに duration、ease などを継承させます。
• ✅ ScrollTrigger はタイムライン（またはトップレベルのトゥイーン）に設定し、タイムライン内のトゥイーンには設定しません。

避けること

• ❌ タイムラインでシーケンスを組める場合に、delay を使ってアニメーションを連結しないでください。複数ステップのアニメーションには gsap.timeline() と位置パラメーターを優先してください。
• ❌ 多くの子トゥイーンで同じ duration や ease を使う場合に、デフォルト値（例：defaults: { duration: 0.5, ease: "power2.out" }）を渡し忘れないでください。
• ❌ タイムラインのコンストラクターに指定する duration はトゥイーンの duration と同じではありません。タイムラインの「duration」は、その子によって決まります。
• ❌ ScrollTrigger を含むアニメーションをネストしないでください。ScrollTrigger はトップレベルの Tween／Timeline にのみ設定します。