gsap-timeline

GSAP タイムライン

GreenSock の公式 GSAP スキルから厳選：https://github.com/greensock/gsap-skills

このスキルを使用するタイミング

複数ステップのアニメーションを作成するとき、複数のトゥイーンを順番または並行して連携させるとき、あるいはユーザーが 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() でラベルを追加してください。
• ✅ タイムラインのコンストラクターに defaults を渡し、子トゥイーンに duration や ease などを継承させてください。
• ✅ ScrollTrigger はタイムライン（またはトップレベルのトゥイーン）に設定し、タイムライン内のトゥイーンには設定しないでください。

避けること

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