gsap.utils
このスキルを使用するタイミング
アニメーション内で数学、配列/コレクション処理、単位の解析、値のマッピング（例：スクロール位置の値への変換、ランダム化、グリッドへのスナップ、入力の正規化）を伴うコードを作成・レビューする際に、gsap.utils を使用する場合に適用します。
関連スキル: アニメーションを構築する際は gsap-core、gsap-timeline、gsap-scrolltrigger と併用します。CustomEase やその他のイージングユーティリティは gsap-plugins にあります。
概要
gsap.utils は純粋なヘルパー関数を提供します。登録は不要です。トゥイーンのvars（関数ベースの値など）、ScrollTrigger や Observer のコールバック、GSAP を駆動する任意の JavaScript 内で使用できます。すべて gsap.utils 上にあります（例：gsap.utils.clamp()）。
値の省略：関数形式。 多くのユーティリティは、変換する値を 最後 の引数として受け入れます。その引数を省略すると、後で値を受け取る 関数 を返します。同じ設定で多数の値を clamp、map、normalize、snap する必要がある場合（例：mousemove ハンドラやトゥイーンコールバック内）は、関数形式を使用します。例外: random() — 再利用可能な関数を取得するには、最後の引数に true を渡します（値を省略しないでください）。詳細は random() を参照してください。
// 値あり：結果を返す
gsap.utils.clamp(0, 100, 150); // 100
// 値なし：後で値とともに呼び出す関数を返す
let c = gsap.utils.clamp(0, 100);
c(150); // 100
c(-10); // 0
クランプ（値の制限）と範囲
clamp(min, max, value?)
値を min と max の間に制限します。value を省略すると関数を取得します：clamp(min, max)(value)。
gsap.utils.clamp(0, 100, 150); // 100
gsap.utils.clamp(0, 100, -10); // 0
let clampFn = gsap.utils.clamp(0, 100);
clampFn(150); // 100
mapRange(inMin, inMax, outMin, outMax, value?)
ある範囲から別の範囲に値をマッピングします。スクロール位置、進行度（0–1）、入力範囲をアニメーション範囲に変換する際に使用します。value を省略すると関数を取得します：mapRange(inMin, inMax, outMin, outMax)(value)。
gsap.utils.mapRange(0, 100, 0, 500, 50); // 250
gsap.utils.mapRange(0, 1, 0, 360, 0.5); // 180（進行度から角度へ）
let mapFn = gsap.utils.mapRange(0, 100, 0, 500);
mapFn(50); // 250
normalize(min, max, value?)
指定された範囲に対して、値を0–1に正規化した値を返します。対象範囲が0–1の場合のマッピングの逆です。value を省略すると関数を取得します：normalize(min, max)(value)。
gsap.utils.normalize(0, 100, 50); // 0.5
gsap.utils.normalize(100, 300, 200); // 0.5
let normFn = gsap.utils.normalize(0, 100);
normFn(50); // 0.5
interpolate(start, end, progress?)
与えられた進行度（0–1）で2つの値の間を補間します。数値、色、および一致するキーを持つオブジェクトを処理します。progress を省略すると関数を取得します：interpolate(start, end)(progress)。
gsap.utils.interpolate(0, 100, 0.5); // 50
gsap.utils.interpolate("#ff0000", "#0000ff", 0.5); // 中間色
gsap.utils.interpolate({ x: 0, y: 0 }, { x: 100, y: 50 }, 0.5); // { x: 50, y: 25 }
let lerp = gsap.utils.interpolate(0, 100);
lerp(0.5); // 50
ランダムとスナップ
random(minimum, maximum[, snapIncrement, returnFunction]) / random(array[, returnFunction])
範囲 minimum–maximum 内の乱数、または 配列 からランダムな要素を返します。オプションの snapIncrement は結果を最も近い倍数にスナップします（例：5 は5の倍数）。再利用可能な関数を取得するには、最後の引数として true（returnFunction）を渡します。返された関数は引数を取らず、呼び出すたびに新しいランダム値を返します。これが関数形式のために true を使用する唯一のユーティリティです（値を省略する代わりに）。
// 即時値：範囲内の数値
gsap.utils.random(-100, 100); // 例：42.7
gsap.utils.random(0, 500, 5); // 0–500、最も近い5にスナップ
// 再利用可能な関数：最後の引数として true を渡す
let randomFn = gsap.utils.random(-200, 500, 10, true);
randomFn(); // 範囲内のランダム値、10にスナップ
randomFn(); // 別のランダム値
// 配列：ランダムに1つ選択
gsap.utils.random(["red", "blue", "green"]); // "red", "blue", "green" のいずれか
let randomFromArray = gsap.utils.random([0, 100, 200], true);
randomFromArray(); // 0, 100, 200 のいずれか
トゥイーンvars内での文字列形式： "random(-100, 100)"、"random(-100, 100, 5)"、または "random([0, 100, 200])" を使用します。GSAP はターゲットごとに評価します。
gsap.to(".box", { x: "random(-100, 100, 5)", duration: 1 });
gsap.to(".item", { backgroundColor: "random([red, blue, green])" });
snap(snapTo, value?)
値を snapTo の最も近い倍数、または許可された値の配列内の最も近い値にスナップします。value を省略すると関数を取得します：snap(snapTo)(value)（または snap(snapArray)(value)）。
gsap.utils.snap(10, 23); // 20
gsap.utils.snap(0.25, 0.7); // 0.75
gsap.utils.snap([0, 100, 200], 150); // 100 または 200（配列内で最も近い値）
let snapFn = gsap.utils.snap(10);
snapFn(23); // 20
トゥイーンでグリッドやステップベースのアニメーションに使用します：
gsap.to(".x", { x: 200, snap: { x: 20 } });
shuffle(array)
同じ要素をランダムな順序に並べ替えた新しい配列を返します。順序のランダム化に使用します（例：コピーでの "random" からのstagger）。
gsap.utils.shuffle([1, 2, 3, 4]); // 例：[3, 1, 4, 2]
distribute(config)
関数を返します。配列内（またはグリッド内）の位置に基づいて各ターゲットに値を割り当てます。内部的には高度なstaggerに使用されます。多数の要素にまたがって値を分散する必要がある場合（例：scale, opacity, x, delay）に使用します。返される関数は (index, target, targets) を受け取ります。手動で呼び出すか、結果を直接トゥイーンに渡します。GSAP はそれを index, element, array でターゲットごとに呼び出します。
Config（すべてオプション）：
| プロパティ | 型 | 説明 |
|---|---|---|
base | Number | 開始値。デフォルト 0。 |
amount | Number | すべてのターゲットに分散する合計値（baseに加算）。例：100ターゲットで amount: 1 → ターゲット間隔0.01。代わりに each を使用してターゲットごとの固定ステップを設定します。 |
each | Number | 各ターゲット間に追加する量（baseに加算）。例：4ターゲットで each: 1 → 0, 1, 2, 3。代わりに amount を使用して合計を分割します。 |
from | Number | String | Array | 分散の開始位置：インデックス、または "start"、"center"、"edges"、"random"、"end"、または比率 [0.25, 0.75] など。デフォルト 0。 |
grid | String | Array | フラットインデックスの代わりにグリッド位置を使用：[rows, columns]（例：[5, 10]）または検出する場合は "auto"。フラット配列の場合は省略。 |
axis | String | グリッドの場合：1つの軸に制限（"x" または "y"）。 |
ease | Ease | イージングカーブに沿って値を分散（例："power1.inOut"）。デフォルト "none"。 |
トゥイーン内： distribute(config) の結果をプロパティ値として渡します。GSAP は各ターゲットに対して (index, target, targets) で関数を呼び出します。
// スケール：中央の要素0.5、外側の端3（centerからamount 2.5を分散）
gsap.to(".class", {
scale: gsap.utils.distribute({
base: 0.5,
amount: 2.5,
from: "center"
})
});
手動使用： 返された関数を (index, target, targets) で呼び出して、そのインデックスの値を取得します。
const distributor = gsap.utils.distribute({
base: 50,
amount: 100,
from: "center",
ease: "power1.inOut"
});
const targets = gsap.utils.toArray(".box");
const valueForIndex2 = distributor(2, targets[2], targets);
詳細は distribute() を参照してください。
単位と解析
getUnit(value)
値の単位文字列を返します（例："px"、"%"、"deg"）。値の正規化や変換時に使用します。
gsap.utils.getUnit("100px"); // "px"
gsap.utils.getUnit("50%"); // "%"
gsap.utils.getUnit(42); // ""（単位なし）
unitize(value, unit)
数値に単位を追加します。値に既に単位がある場合はそのまま返します。CSS値やトゥイーンの終了値の構築時に使用します。
gsap.utils.unitize(100, "px"); // "100px"
gsap.utils.unitize("2rem", "px"); // "2rem"（変更なし）
splitColor(color, returnHSL?)
色文字列を配列に変換します：[red, green, blue]（0–255）、または [red, green, blue, alpha]（アルファが存在するか必要な場合は4要素のRGBA）。2番目の引数に true（returnHSL）を渡すと、代わりに [hue, saturation, lightness] または [hue, saturation, lightness, alpha]（HSL/HSLA）を取得します。"rgb()"、"rgba()"、"hsl()"、"hsla()"、16進数、および名前付き色（例："red"）で動作します。色コンポーネントのアニメーションやグラデーションの構築時に使用します。詳細は splitColor() を参照してください。
gsap.utils.splitColor("red"); // [255, 0, 0]
gsap.utils.splitColor("#6fb936"); // [111, 185, 54]
gsap.utils.splitColor("rgba(204, 153, 51, 0.5)"); // [204, 153, 51, 0.5]（4要素）
gsap.utils.splitColor("#6fb936", true); // [94, 55, 47]（HSL: 色相, 彩度, 輝度）
配列とコレクション
selector(scope)
与えられた要素（またはref）内の要素のみを見つけるスコープ付きセレクタ関数を返します。コンポーネント内で使用すると、".box" のようなセレクタがドキュメント全体ではなくそのコンポーネントの子孫のみに一致します。DOM要素またはref（例：React ref; .current を処理）を受け入れます。
const q = gsap.utils.selector(containerRef);
q(".box"); // container 内の .box 要素の配列
gsap.to(q(".circle"), { x: 100 });
toArray(value, scope?)
値を配列に変換します：セレクタ文字列（要素にスコープ）、NodeList、HTMLCollection、単一の要素、または配列。GSAPに混在した入力（例：ターゲット）を渡し、真の配列が必要な場合に使用します。
gsap.utils.toArray(".item"); // 要素の配列
gsap.utils.toArray(".item", container); // container にスコープ
gsap.utils.toArray(nodeList); // NodeList から [ ... ]
pipe(...functions)
関数を合成します：pipe(f1, f2, f3)(value) は f3(f2(f1(value))) を返します。トゥイーンやコールバック内で変換のチェーン（例：normalize → mapRange → snap）を適用する際に使用します。
const fn = gsap.utils.pipe(
(v) => gsap.utils.normalize(0, 100, v),
(v) => gsap.utils.snap(0.1, v)
);
fn(50); // 正規化されてからスナップ
wrap(min, max, value?)
値を範囲 min–max 内にラップします（min を含み、max を含まない）。無限スクロールや周期的な値に使用します。value を省略すると関数を取得します：wrap(min, max)(value)。
gsap.utils.wrap(0, 360, 370); // 10
gsap.utils.wrap(0, 360, -10); // 350
let wrapFn = gsap.utils.wrap(0, 360);
wrapFn(370); // 10
wrapYoyo(min, max, value?)
値を範囲内でヨーヨー（両端でバウンス）でラップします。範囲内での行き来に使用します。value を省略すると関数を取得します：wrapYoyo(min, max)(value)。
gsap.utils.wrapYoyo(0, 100, 150); // 50（バウンスバック）
let wrapY = gsap.utils.wrapYoyo(0, 100);
wrapY(150); // 50
ベストプラクティス
- ✅ 同じ範囲/設定を何度も使用する場合（例：スクロールハンドラ、トゥイーンコールバック）は、値引数を省略して再利用可能な関数を取得します：
let mapFn = gsap.utils.mapRange(0, 1, 0, 360); mapFn(progress)。 - ✅ グリッド整列またはステップベースの値には snap を使用します。GSAP やコードがセレクタや NodeList から真の配列を必要とする場合は toArray を使用します。
- ✅ コンポーネント内では、セレクタがコンテナや ref にスコープされるように gsap.utils.selector(scope) を使用します。
してはいけないこと
- ❌ mapRange / normalize が単位を処理すると想定しないでください。これらは数値に対して動作します。単位が重要な場合は getUnit / unitize を使用してください。
- ❌ 文書化されていない動作をオーバーライドしたり依存したりしないでください。文書化されたAPIに従ってください。