GSAP Timeline

このスキルを使うとき

複数ステップのアニメーションを構築する、複数の tween をシーケンスまたは並列で調整する、またはユーザーが GSAP でのタイムライン、シーケンス、またはキーフレーム形式のアニメーションについて質問するときに適用します。

関連スキル: 単一の tween とイージングには 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 });

デフォルトでは、tween は 順序を追って 1 つずつ追加されます。position パラメータ を使用して、特定の時間または他の tween との相対的な位置に tween を配置します。

Position パラメータ

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);           // 0 秒で開始
tl.to(".b", { y: 50 }, "+=0.5");      // 最後の終了後 0.5 秒
tl.to(".c", { opacity: 0 }, "<");     // 前の開始と同時
tl.to(".d", { scale: 2 }, "<0.2");    // 前の開始後 0.2 秒

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

タイムラインにデフォルト値を渡して、すべての子 tween に継承させます:

const tl = gsap.timeline({ defaults: { duration: 0.5, ease: "power2.out" } });
tl.to(".a", { x: 100 }).to(".b", { y: 50 }); // 両方とも 0.5s と power2.out を使用

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

• paused: true — 一時停止状態で作成; .play() を呼び出して開始します
• repeat, yoyo — tween と同じ; タイムライン全体に適用
• onComplete, onStart, onUpdate — タイムラインレベルのコールバック
• defaults — すべての子 tween にマージされる 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");  // "outro" から開始
tl.tweenFromTo("intro", "outro"); // タイムラインを一時停止し、タイムラインの再生ヘッドを intro から outro までアニメーションする新しい Tween を返します（イージングなし）

タイムラインのネスト

タイムラインは他のタイムラインを含むことができます。

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

• ✅ シーケンスにはタイムラインを優先
• ✅ position パラメータ（3 番目の引数）を使用して tween を特定の時間またはラベルに対する相対的な位置に配置
• ✅ addLabel() で ラベル を追加し、読みやすく保守しやすいシーケンスにする
• ✅ タイムラインコンストラクタに defaults を渡して、子 tween が duration、ease などを継承するようにする
• ✅ ScrollTrigger をタイムライン（またはトップレベル tween）に配置し、タイムライン内の tween には配置しない

してはいけないこと

• ❌ delay を使用してアニメーションをチェーンしない場合でも、timeline を使用できるとき; マルチステップアニメーションには gsap.timeline() と position パラメータを優先
• ❌ 多くの子 tween が同じ duration または ease を共有する場合、defaults（例: defaults: { duration: 0.5, ease: "power2.out" }）を渡すことを忘れない
• ❌ タイムラインコンストラクタの duration が tween の duration と同じではないことを忘れない; タイムラインの「duration」は子によって決定される
• ❌ ScrollTrigger を含むアニメーションをネストしない; ScrollTrigger はトップレベルの Tweens/Timelines にのみ配置する