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); // 0秒時点
tl.to(".b", { y: 50 }, "+=0.5"); // 最後のアニメーション終了から0.5秒後
tl.to(".c", { opacity: 0 }, "<"); // 直前のアニメーションと同時開始
tl.to(".d", { scale: 2 }, "<0.2"); // 直前のアニメーション開始から0.2秒後
タイムラインのデフォルト値
タイムラインにデフォルト値を渡すと、すべての子トゥイーンが継承します:
const tl = gsap.timeline({ defaults: { duration: 0.5, ease: "power2.out" } });
tl.to(".a", { x: 100 }).to(".b", { y: 50 }); // 両方とも0.5秒、power2.outを使用
タイムラインオプション（コンストラクタ）
- paused: true — 一時停止状態で作成; 再生するには
.play()を呼び出します。 - repeat, yoyo — トゥイーンと同じ; タイムライン全体に適用されます。
- onComplete, onStart, onUpdate — タイムラインレベルのコールバック。
- defaults — すべての子トゥイーンにマージされる変数。
ラベル
ラベルを追加して使用することで、可読性が高く保守しやすいシーケンスを作成できます:
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ベストプラクティス
- ✅ シーケンスにはタイムラインを優先して使用する
- ✅ 位置パラメータ（第3引数）を使用してトゥイーンを特定の時間やラベルに相対的に配置する
- ✅
addLabel()でラベルを追加し、可読性が高く保守しやすいシーケンスにする - ✅ デフォルト値をタイムラインコンストラクタに渡し、子トゥイーンにdurationやeaseを継承させる
- ✅ ScrollTriggerはタイムライン（またはトップレベルのトゥイーン）に設定し、タイムライン内部のトゥイーンには設定しない
禁止事項
- ❌ アニメーションの連続実行にdelayを使わないでください。タイムラインでシーケンスを組める場合は、マルチステップアニメーションには
gsap.timeline()と位置パラメータを使用してください。 - ❌ 多くの子トゥイーンが同じdurationやeaseを共有する場合に、デフォルト値（例:
defaults: { duration: 0.5, ease: "power2.out" }）を渡すのを忘れないでください。 - ❌ タイムラインコンストラクタのdurationはトゥイーンのdurationと同じではないことを忘れないでください。タイムラインの「duration」は子によって決定されます。
- ❌ ScrollTriggerを含むアニメーションをネストしないでください。ScrollTriggerはトップレベルのトゥイーン/タイムラインにのみ設定する必要があります。