gsap.utils

このスキルを使うタイミング

gsap.utils を使ってコードを書いたり、レビューしたりする場合に適用します。数学計算、配列/コレクション処理、単位解析、またはアニメーション内の値マッピング（例：スクロール位置を値にマッピングする、値をランダム化する、グリッドにスナップする、入力値を正規化するなど）に使います。

関連スキル: gsap-core、gsap-timeline、gsap-scrolltrigger と組み合わせてアニメーションを構築します。CustomEase など他のイージング機能は gsap-plugins にあります。

概要

gsap.utils は純粋なヘルパーを提供し、登録の必要はありません。トウィーン変数（例：関数ベースの値）、ScrollTrigger や Observer のコールバック、または GSAP を操作する任意の JavaScript で使用できます。すべて gsap.utils 上にあります（例：gsap.utils.clamp()）。

値を省略：関数形式。 多くのユーティリティは、変換する値を 最後 の引数として受け付けます。その引数を省略すると、ユーティリティは値を後で受け付ける 関数 を返します。同じ設定で多くの値をクランプ、マップ、正規化、またはスナップする必要がある場合は、関数形式を使用してください（例：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 の範囲のランダムな数値、または array からのランダムな要素を返します。オプションの snapIncrement は、結果を最も近い倍数にスナップします（例：5 → 5 の倍数）。再利用可能な関数を得るには、最後の引数（returnFunction）として true を渡してください。返された関数は引数を取らず、呼び出すたびに新しいランダム値を返します。これは値を省略する代わりに 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

トウィーン変数の文字列形式： "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)

同じ要素をランダムな順序で含む新しい配列を返します。順序をランダム化するときに使用します（例：「ランダム」スタガーのコピー）。

gsap.utils.shuffle([1, 2, 3, 4]); // 例：[3, 1, 4, 2]

distribute(config)

関数を返します。配列内（またはグリッド内）の位置に基づいて、各ターゲットに値を割り当てます。高度なスタガーの内部で使用されます。多くの要素に値を広げる必要があるときはいつでもこれを使用してください（例：scale、opacity、x、delay）。返された関数は (index, target, targets) を受け取ります — 手動で呼び出すか、結果をトウィーンに直接渡します。GSAP はターゲットごとにインデックス、要素、および配列で呼び出します。

設定（すべてオプション）：

プロパティ	型	説明
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（2.5 の amount が中央から分配）
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?)

色文字列を配列に変換します：[赤、緑、青]（0～255）、または [赤、緑、青、アルファ]（アルファが存在する場合は 4 要素の RGBA）。2 番目の引数（returnHSL）として true を渡して、代わりに [色相、彩度、明度] または [色相、彩度、明度、アルファ]（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");        // コンテナ内の .box 要素の配列
gsap.to(q(".circle"), { x: 100 });

toArray(value, scope?)

値を配列に変換します：セレクタ文字列（要素にスコープ）、NodeList、HTMLCollection、単一要素、または配列。GSAP に混合入力（例：ターゲット）を渡し、真の配列が必要な場合に使用します。

gsap.utils.toArray(".item");           // 要素の配列
gsap.utils.toArray(".item", container); // コンテナにスコープ
gsap.utils.toArray(nodeList);          // NodeList から [ ... ]

pipe(...functions)

関数を構成します：pipe(f1, f2, f3)(value) は f3(f2(f1(value))) を返します。トウィーンやコールバックで変換チェーン（例：正規化 → マップ範囲 → スナップ）を適用する場合に使用します。

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 の範囲内にラップします（最小値を含む、最大値を除く）。無限スクロールまたは循環値に使用します。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 を使用します。セレクタまたは NodeList から実際の配列が必要な場合は toArray を使用します。
• ✅ コンポーネント内では gsap.utils.selector(scope) を使用して、セレクタをコンテナまたは ref にスコープします。

してはいけないこと

• ❌ mapRange / normalize が単位を処理すると想定しないでください。これらは数値に対して機能します。単位が重要な場合は getUnit / unitize を使用します。
• ❌ 文書化されていない動作をオーバーライドまたは依存しないでください。文書化された API に準拠してください。

さらに詳しく

https://gsap.com/docs/v3/HelperFunctions