iurymagano/portfolio-next

GSAP プラグイン

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

GSAP プラグインを使用するコードを扱う際やレビューする際に適用します：プラグインの登録、スクロールトゥ、フリップ/FLIP アニメーション、ドラッグ可能要素、SVG（DrawSVG、MorphSVG、MotionPath）、テキスト（SplitText、ScrambleText）、物理演算、イージングプラグイン（CustomEase、EasePack、CustomWiggle、CustomBounce）、または GSDevTools。ScrollTrigger には専用のスキル（gsap-scrolltrigger）があります。

関連スキル： コアなトゥイーンには gsap-core を、ScrollTrigger には gsap-scrolltrigger を、React には gsap-react を使用してください。

ライセンスとインストール（重要）

すべての GSAP プラグインは無料で、商用利用も含みます。Webflow による GSAP の買収以降、Club GSAP は有料階層ではなくなり、どのプラグインもメンバーシップ、ライセンスキー、認証トークンを必要としません — これには以前 Club 限定だったプラグイン（SplitText、MorphSVG など）も含まれます。

• ✅ すべて公開の gsap npm パッケージからインストール：npm install gsap。全てのプラグインが含まれています — gsap/SplitText、gsap/MorphSVGPlugin などとしてインポートします。
• ❌ GreenSock 認証トークンを含む .npmrc を生成したり、プライベートレジストリ npm.greensock.com を提案したり、ユーザーに Club GSAP にサインアップしてプラグインにアクセスするように指示したりしないでください。これらの手順は古くなっています。

プラグインの登録

各プラグインを一度登録して、GSAP（およびバンドラー）がそれを含めるようにします。プロジェクトで使用するすべてのプラグインに対して gsap.registerPlugin() を使用します：

import gsap from "gsap";
import { ScrollToPlugin } from "gsap/ScrollToPlugin";
import { Flip } from "gsap/Flip";
import { Draggable } from "gsap/Draggable";

gsap.registerPlugin(ScrollToPlugin, Flip, Draggable);

• ✅ プラグインをトゥイーンや API 呼び出しで使用する前に登録します。
• ✅ React では、トップレベルまたはアプリ内で一度だけ登録します（例：最初の useGSAP の前）。再レンダリングするコンポーネント内で登録しないでください。useGSAP は使用前に登録が必要なプラグインです。

スクロール

ScrollToPlugin

スクロール位置（ウィンドウまたはスクロール可能な要素）をアニメーション化します。ScrollTrigger を使わずに「要素までスクロール」または「位置までスクロール」する場合に使用します。

gsap.registerPlugin(ScrollToPlugin);

gsap.to(window, { duration: 1, scrollTo: { y: 500 } });
gsap.to(window, { duration: 1, scrollTo: { y: "#section", offsetY: 50 } });
gsap.to(scrollContainer, { duration: 1, scrollTo: { x: "max" } });

ScrollToPlugin — 主要設定（scrollTo オブジェクト）：

オプション	説明
x, y	ターゲットスクロール位置（数値）、または最大値には "max"
element	スクロール先のセレクタまたは要素（ビューにスクロール）
offsetX, offsetY	ターゲット位置からのオフセット（ピクセル単位）

ScrollSmoother

スムーススクロールラッパー（ネイティブスクロールを平滑化）。ScrollTrigger と特定の DOM 構造（コンテンツラッパー + スムースラッパー）が必要です。スムーズでモーメンタム風のスクロールが必要な場合に使用します。セットアップについては GSAP ドキュメントを参照。ScrollTrigger の後に登録します。DOM 構造は次のようになります：

<body>
	<div id="smooth-wrapper">
		<div id="smooth-content">
			<!--- すべてのコンテンツはここに --->
		</div>
	</div>
	<!-- position: fixed 要素は外側に配置可能 --->
</body>

DOM / UI

Flip

Flip.getState() で状態をキャプチャし、変更を適用（例：レイアウトやクラスの変更）した後、Flip.from() を使用して以前の状態から新しい状態へのアニメーションを実行します（FLIP：First, Last, Invert, Play）。2 つのレイアウト状態間（リスト、グリッド、展開/折りたたみ）のアニメーションに使用します。

gsap.registerPlugin(Flip);

const state = Flip.getState(".item");
// DOM を変更（並べ替え、追加/削除、クラスの変更）
Flip.from(state, { duration: 0.5, ease: "power2.inOut" });

Flip — 主要設定（Flip.from 変数）：

オプション	説明
absolute	フリップ中に position: absolute を使用する（デフォルト: false）
nested	true の場合、最初のレベルの子のみが測定される（ネストされた変形に適しています）
scale	true の場合、要素を拡大縮小してフィットさせる（伸びを避ける）；デフォルト true
simple	true の場合、位置/スケールのみがアニメーション化される（高速、精度は低い）
duration, ease	標準トゥイーンオプション

詳細情報

https://gsap.com/docs/v3/Plugins/Flip

Draggable

マウス/タッチで要素をドラッグ可能、回転可能、またはスロー可能にします。スライダー、カード、並べ替え可能なリスト、または任意のドラッグインタラクションに使用します。

gsap.registerPlugin(Draggable, InertiaPlugin);

Draggable.create(".box", { type: "x,y", bounds: "#container", inertia: true });
Draggable.create(".knob", { type: "rotation" });

Draggable — 主要設定オプション：

オプション	説明
type	"x", "y", "x,y", "rotation", "scroll"
bounds	要素、セレクタ、または { minX, maxX, minY, maxY } でドラッグ範囲を制限
inertia	true でスロー/モーメンタムを有効にする（InertiaPlugin が必要）
edgeResistance	0–1；範囲外にドラッグしたときの抵抗
cursor	ドラッグ中の CSS カーソル
onDragStart, onDrag, onDragEnd	コールバック；イベントとターゲットを受け取る
onThrowUpdate, onThrowComplete	慣性がアクティブなときのコールバック

Inertia（InertiaPlugin）

Draggable と連動してリリース後のモーメンタムを実現したり、任意のオブジェクトの任意のプロパティの慣性/速度を追跡し、それをシームレスに減速させる単純なトゥイーンを可能にします。inertia: true を使用する場合は Draggable と一緒に登録します：

gsap.registerPlugin(Draggable, InertiaPlugin);
Draggable.create(".box", { type: "x,y", inertia: true });

または、プロパティの速度を追跡します：

InertiaPlugin.track(".box", "x");

次に、"auto" を使用して現在の速度を継続し、減速停止させます：

gsap.to(obj, { inertia: { x: "auto" } });

Observer

ポインターおよびスクロール入力をデバイス間で正規化します。ScrollTrigger のようにスクロール位置に直接結びつけずに、スワイプ、スクロール方向、またはカスタムジェスチャロジックに使用します。

gsap.registerPlugin(Observer);

Observer.create({
  target: "#area",
  onUp: () => {},
  onDown: () => {},
  onLeft: () => {},
  onRight: () => {},
  tolerance: 10
});

Observer — 主要設定オプション：

オプション	説明
target	監視する要素またはセレクタ
onUp, onDown, onLeft, onRight	スワイプ/スクロールが許容値を超えた方向のコールバック
tolerance	方向が検出されるまでのピクセル数；デフォルト 10
type	"touch", "pointer", または "wheel"（デフォルト: "touch,pointer"）

テキスト

SplitText

要素のテキストを文字、単語、および/または行に分割し（それぞれ独自の要素に）、段階的または単位ごとのアニメーションを可能にします。テキストを文字ごと、単語ごと、または行ごとにアニメーション化する場合に使用します。chars、words、lines（および mask が設定されている場合は masks）を持つインスタンスを返します。revert() で元のマークアップを復元するか、gsap.context() に任せて元に戻します。gsap.context()、matchMedia()、useGSAP() と統合されます。API: SplitText.create(target, vars)（target = セレクタ、要素、または配列）。

gsap.registerPlugin(SplitText);

const split = SplitText.create(".heading", { type: "words, chars" });
gsap.from(split.chars, { opacity: 0, y: 20, stagger: 0.03, duration: 0.4 });
// 後で: split.revert() または gsap.context() でクリーンアップと元に戻しを任せる

onSplit()（v3.13.0+）を使用すると、分割時および autoSplit 使用時の再分割時にアニメーションが実行されます；onSplit() からトゥイーン/タイムラインを返すことで、SplitText がクリーンアップと再分割時の進行状況同期を行います：

SplitText.create(".split", {
  type: "lines",
  autoSplit: true,
  onSplit(self) {
    return gsap.from(self.lines, { y: 100, opacity: 0, stagger: 0.05, duration: 0.5 });
  }
});

SplitText — 主要設定（SplitText.create 変数）：

オプション	説明
type	カンマ区切り: "chars", "words", "lines"。デフォルト "chars,words,lines"。パフォーマンスのために必要なものだけ分割する（例：lines を使用しない場合は "words, chars"）。chars のみで words/lines がない場合や不自然な改行を避けるには smartWrap: true を使用。
charsClass, wordsClass, linesClass	各分割要素の CSS クラス。"++" を追加してインクリメントされるクラスにする（例：linesClass: "line++" → line1, line2, …）。
aria	"auto"（デフォルト）、"hidden"、または "none"。アクセシビリティ："auto" は分割要素に aria-label を追加し、行/単語/文字要素に aria-hidden を追加してスクリーンリーダーがラベルを読むようにする；"hidden" はすべての要素をリーダーから隠す；"none" は aria を変更しない。ネストされたリンク/セマンティクスを公開する必要がある場合は、スクリーンリーダーのみの複製とともに "none" を使用。
autoSplit	true の場合、フォントの読み込みが完了したとき、または要素の幅が変更されたとき（かつ行が分割されている場合）に元に戻して再分割し、誤った改行を避けます。アニメーションは onSplit() 内で作成して、新しく分割された要素をターゲットにする必要があります；再分割時の自動クリーンアップと時間同期のために、onSplit() からアニメーションを返します。
onSplit(self)	分割完了時（および autoSplit が true の場合は再分割時）のコールバック。SplitText インスタンスを受け取ります。GSAP トゥイーンまたはタイムラインを返すと、再分割時にそのアニメーションの自動元に戻しと同期が可能になります。
mask	"lines"、"words"、または "chars"。各ユニットを overflow: clip の追加要素でラップしてマスク/リビール効果を実現します。タイプは 1 つだけ；インスタンスの masks 配列にアクセス（またはクラスが設定されている場合は -mask クラスを使用）。
tag	ラッパー要素のタグ；デフォルト "div"。インラインには "span" を使用（注意：一部のブラウザではインライン要素に回転/スケールなどの変形が正しく表示されない場合があります）。
deepSlice	true（デフォルト）の場合、複数行にまたがるネストされた要素（例：<strong>）が縦に伸びないように細分化されます。行を分割する場合にのみ適用されます。
ignore	分割しないままにするセレクタまたは要素（例：ignore: "sup"）。
smartWrap	chars のみを分割する場合、単語を white-space: nowrap のスパンでラップして単語途中の改行を避けます。words または lines が分割されている場合は無視されます。デフォルト false。
wordDelimiter	単語境界：文字列（デフォルト " "）、RegExp、または { delimiter: RegExp, replaceWith: string }（カスタム分割用、例：ハッシュタグや非ラテン語のゼロ幅接合子）。
prepareText(text, parent)	生のテキストと親要素を受け取る関数；分割前に変更されたテキストを返します（例：空白がない言語の改行マーカーを挿入するため）。
propIndex	true の場合、各分割要素にインデックス付きの CSS 変数を追加します（例：--word: 1, --char: 2）。
reduceWhiteSpace	連続するスペースを折りたたむ；デフォルト true。v3.13.0 からは改行も尊重し、<pre> の場合は <br> を挿入できます。
onRevert	インスタンスが元に戻されたときのコールバック。

ヒント： アニメーション化するものだけを分割します（例：単語だけをアニメーション化する場合は chars をスキップ）。カスタムフォントの場合は、フォント読み込み後に分割するか（例：document.fonts.ready.then(...)）、autoSplit: true と onSplit() を使用します。chars 分割時のカーニングシフトを避けるには、CSS font-kerning: none; text-rendering: optimizeSpeed; を使用します。text-wrap: balance は避けてください。分割に干渉する可能性があります。SplitText は SVG <text> をサポートしていません。

詳細情報： SplitText

ScrambleText

テキストをスクランブル/グリッチ効果でアニメーション化します。スクランブル効果でテキストを表示または切り替える場合に使用します。

gsap.registerPlugin(ScrambleTextPlugin);

gsap.to(".text", {
  duration: 1,
  scrambleText: { text: "New message", chars: "01", revealDelay: 0.5 }
});

SVG

DrawSVG（DrawSVGPlugin）

stroke-dashoffset / stroke-dasharray をアニメーション化して SVG 要素のストロークを表示または非表示にします。<path>、<line>、<polyline>、<polygon>、<rect>、<ellipse> で動作します。ストロークを「描画」または「消去」する場合に使用します。

drawSVG 値： パスに沿ったストロークの表示セグメント（開始位置と終了位置）を記述します。「時間をかけて A から B にアニメーション化」するものではありません。形式：パーセントまたは長さで "start end"。例："0% 100%" = ストローク全体；"20% 80%" = ストロークは 20% から 80% の間のみ（両端にギャップ）。トゥイーンは要素の現在のセグメントからターゲットのセグメントにアニメーション化します — 例：gsap.to("#path", { drawSVG: "0% 100%" }) は現在の状態からストローク全体へ移行します。単一の値（例：0、"100%"）は開始が 0 であることを意味します："100%" は "0% 100%" と同等です。

必須： 要素に表示可能なストロークが必要です — CSS または SVG 属性で stroke と stroke-width を設定します。設定しないと何も描画されません。

gsap.registerPlugin(DrawSVGPlugin);

// 何もないところからストローク全体を描画
gsap.from("#path", { duration: 1, drawSVG: 0 });
// または明示的なセグメント：0–0 から 0–100%
gsap.fromTo("#path", { drawSVG: "0% 0%" }, { drawSVG: "0% 100%", duration: 1 });
// 中央のみストローク（両端にギャップ）
gsap.to("#path", { duration: 1, drawSVG: "20% 80%" });

注意点： ストロークのみに影響します（塗りつぶしには影響しません）。単一セグメントの <path> 要素が推奨されます；複数セグメントのパスは一部のブラウザで奇妙にレンダリングされる可能性があります。<use> の内容は視覚的に変更できません。DrawSVGPlugin.getLength(element) および DrawSVGPlugin.getPosition(element) はストロークの長さと現在位置を返します。

詳細情報： DrawSVG

MorphSVG（MorphSVGPlugin）

d 属性（パスデータ）をアニメーション化して、ある SVG 形状を別の形状にモーフィングします。開始と終了の形状が同じ数の点を持つ必要はありません — MorphSVG は三次ベジェに変換し、必要に応じて点を追加します。アイコン間のモーフィング、形状の遷移、またはパスベースのアニメーションに使用します。<path>、<polyline>、<polygon> で動作します；<circle>、<rect>、<ellipse>、<line> は内部的に変換されるか、MorphSVGPlugin.convertToPath(セレクタ | 要素)（DOM 内の要素を <path> に置き換えます）によって変換されます。

morphSVG 値： セレクタ（例："#lightning"）、要素、生のパスデータ（例："M47.1,0.8 73.3,0.8..."）、または polygon/polyline の場合はポイント文字列（例："240,220 240,..."）を指定できます。

MorphSVG アニメーションの例：

gsap.registerPlugin(MorphSVGPlugin);

gsap.to("#morph-target", {
  duration: 1,
  morphSVG: { shape: "#target-shape", shapeIndex: 1 }
});

主要設定（morphSVG オブジェクト内）：

オプション	説明
shape	モーフィング先のターゲット形状（セレクタ、要素、またはパスデータ文字列）
shapeIndex	ターゲット形状内で使用する形状のインデックス（デフォルト: 自動）
ease	モーフィングのイージング
duration, delay	標準トゥイーンオプション
onComplete	モーフィング完了時のコールバック

詳細情報： MorphSVG

MotionPath（MotionPathPlugin）

SVG パスに沿って要素をアニメーション化します（位置、回転、スケール）。パスを使用して複雑なトランジションやパスベースのアニメーションを作成する場合に使用します。

gsap.registerPlugin(MotionPathPlugin);

gsap.to(".element", {
  duration: 2,
  motionPath: {
    path: "#path",
    align: "#path",
    alignOrigin: [0.5, 0.5],
    autoRotate: 90
  }
});

主要設定（motionPath オブジェクト内）：

オプション	説明
path	パスデータ（セレクタ、要素、またはパスデータ文字列）
align	要素をパスに合わせる（true、要素、セレクタ）
alignOrigin	パス上のアライメントの原点 [x, y]（デフォルト [0.5, 0.5]）
autoRotate	パスに沿って要素を回転させる（度単位）
start, end	パスの開始/終了位置（0〜1、デフォルト 0 と 1）

詳細情報： MotionPath

物理演算

physics プロパティ（physics2D、physics3D）

速度、加速度、摩擦に基づいて要素をアニメーション化します。物理ベースのアニメーションやパーティクル効果に使用します。

gsap.registerPlugin(Physics2DPlugin);

gsap.to(".particle", {
  physics2D: {
    velocity: 200,
    angle: 45,
    gravity: 100,
    friction: 0.05
  },
  duration: 2
});

physics2D 主要設定：

オプション	説明
velocity	初期速度（ピクセル/秒）
angle	方向（度）
gravity	重力（ピクセル/秒²）
friction	摩擦係数（0〜1）

physics3D は同様ですが、z 軸用のプロパティを追加します。

詳細情報： Physics2D、Physics3D

イージング

CustomEase

任意の SVG パスまたは制御点からカスタムイージング曲線を作成します。ユニークなイージング効果や非線形の遷移を作成する場合に使用します。

gsap.registerPlugin(CustomEase);

CustomEase.create("myCustomEase", "M0,0 C0.25,0.1 0.25,1 1,1");
gsap.to(".element", { duration: 1, ease: "myCustomEase" });

カスタムイージングの作成：

CustomEase.create("name", "path") を使用します。

注意： パスは [0,0] で開始し [1,1] で終了する必要があります。

詳細情報： CustomEase

EasePack

追加のイージング関数を提供します。

gsap.registerPlugin(EasePack);

gsap.to(".element", { duration: 1, ease: "sine.inOut" });

EasePack は追加のイージング関数を提供します（例：sine、expo、circ、back、elastic、bounce）。

詳細情報： EasePack

CustomWiggle

カスタムイージングを持つウィグルアニメーションを作成します。

gsap.registerPlugin(CustomWiggle);

CustomWiggle.create("myWiggle", { wiggles: 10, type: "easeOut" });
gsap.to(".element", { duration: 1, ease: "myWiggle" });

詳細情報： CustomWiggle

CustomBounce

カスタマイズ可能なバウンスイージングを作成します。

gsap.registerPlugin(CustomBounce);

CustomBounce.create("myBounce", { strength: 0.7, squash: 3 });
gsap.to(".element", { duration: 1, ease: "myBounce" });

詳細情報： CustomBounce

デバッグ

GSDevTools

GSAP アニメーションをデバッグするための開発者ツール。アニメーションを視覚的に検査および制御する場合に使用します。

gsap.registerPlugin(GSDevTools);

GSDevTools.create({ animation: myTimeline });

GSDevTools はアニメーションを一時停止、再生、逆再生、シーク、タイムスケール変更するための UI を提供します。

詳細情報： GSDevTools