gsap-utils

gsap.utils

GreenSock の公式 GSAP スキルから厳選：https://github.com/greensock/gsap-skills

このスキルを使用する場面

アニメーションで数学的な処理、配列やコレクションの操作、単位の解析、値のマッピング（スクロール値を別の値にマッピングする、ランダム化する、グリッドにスナップする、入力値を正規化するなど）に gsap.utils を使用するコードを作成またはレビューする場合に適用します。

関連スキル： アニメーションを構築する際は gsap-core、gsap-timeline、gsap-scrolltrigger と併用してください。CustomEase などのイージングユーティリティは gsap-plugins にあります。

概要

gsap.utils は純粋なヘルパーを提供するため、登録は不要です。トゥイーンの変数（関数ベースの値など）、ScrollTrigger や Observer のコールバック、または GSAP を制御する任意の JS で使用できます。すべて gsap.utils にあります（例：gsap.utils.clamp()）。

値を省略する関数形式。 多くのユーティリティでは、変換する値を最後の引数として受け取ります。この引数を省略すると、後から値を受け取る 関数 が返されます。同じ設定で複数の値をクランプ、マッピング、正規化、スナップする必要がある場合（例：mousemove ハンドラーやトゥイーンのコールバック内）は、関数形式を使用してください。例外：random() — 再利用可能な関数を取得するには、値を省略せず、最後の引数として true を渡します。random() を参照してください。

// With value: returns the result
gsap.utils.clamp(0, 100, 150); // 100

// Without value: returns a function you call with the value later
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 (progress to degrees)

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); // mid color
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 を関数形式に使用するのは、このユーティリティだけです。

// immediate value: number in range
gsap.utils.random(-100, 100);        // e.g. 42.7
gsap.utils.random(0, 500, 5);        // 0–500, snapped to nearest 5

// reusable function: pass true as last argument
let randomFn = gsap.utils.random(-200, 500, 10, true);
randomFn();  // random value in range, snapped to 10
randomFn();  // another random value

// array: pick one value at random
gsap.utils.random(["red", "blue", "green"]);  // "red", "blue", or "green"
let randomFromArray = gsap.utils.random([0, 100, 200], true);
randomFromArray();  // 0, 100, or 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 or 200 (nearest in array)

let snapFn = gsap.utils.snap(10);
snapFn(23); // 20

グリッドやステップ単位のアニメーションでトゥイーンに使用します：

gsap.to(".x", { x: 200, snap: { x: 20 } });

shuffle(array)

要素はそのままで、ランダムな順序に並べ替えた新しい配列を返します。順序をランダム化する場合（例：コピーを使って stagger を "random" にする場合）に使用します。

gsap.utils.shuffle([1, 2, 3, 4]); // e.g. [3, 1, 4, 2]

distribute(config)

関数を返します。配列内（またはグリッド内）の位置に基づいて、各ターゲットに値を割り当てます。高度なスタガーで内部的に使用されます。多くの要素に値（例：スケール、不透明度、x、遅延）を分配する必要がある場合に使用してください。返される関数は (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) を渡して関数を呼び出します。

// Scale: middle elements 0.5, outer edges 3 (amount 2.5 distributed from center)
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);        // "" (unitless)

unitize(value, unit)

数値に単位を追加します。すでに単位が付いている場合は、値をそのまま返します。CSS 値やトゥイーンの終了値を作成する際に使用します。

gsap.utils.unitize(100, "px");  // "100px"
gsap.utils.unitize("2rem", "px"); // "2rem" (unchanged)

splitColor(color, returnHSL?)

色文字列を配列に変換します。[red, green, blue]（0～255）、またはアルファ値が存在する場合や必要な場合は [red, green, blue, alpha]（RGBA の4要素）を返します。2番目の引数（returnHSL）に true を渡すと、代わりに [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 elements)
gsap.utils.splitColor("#6fb936", true);          // [94, 55, 47] (HSL: hue, saturation, lightness)

配列とコレクション

selector(scope)

指定された要素（または ref）の内側だけを検索する、スコープ付きセレクター関数を返します。コンポーネント内で使用すると、".box" のようなセレクターがドキュメント全体ではなく、そのコンポーネントの子孫要素だけに一致します。DOM 要素または ref（例：React ref）を受け取り、.current を処理します。

const q = gsap.utils.selector(containerRef);
q(".box");        // array of .box elements inside container
gsap.to(q(".circle"), { x: 100 });

toArray(value, scope?)

値を配列に変換します。対象は、セレクター文字列（要素にスコープされます）、NodeList、HTMLCollection、単一の要素、または配列です。GSAP に複数種類の入力（例：ターゲット）を渡す際に、通常の配列が必要な場合に使用します。

gsap.utils.toArray(".item");           // array of elements
gsap.utils.toArray(".item", container); // scoped to container
gsap.utils.toArray(nodeList);          // [ ... ] from NodeList

pipe(...functions)

関数を合成します。pipe(f1, f2, f3)(value) は f3(f2(f1(value))) を返します。トゥイーンやコールバックで変換を連続して適用する（例：正規化 → mapRange → snap）際に使用します。

const fn = gsap.utils.pipe(
  (v) => gsap.utils.normalize(0, 100, v),
  (v) => gsap.utils.snap(0.1, v)
);
fn(50); // normalized then snapped

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 (bounces back)

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 を使います。
• ✅ コンポーネント内では gsap.utils.selector(scope) を使い、セレクターの対象をコンテナーまたは ref の範囲に限定します。

禁止事項

• ❌ mapRange ／ normalize が単位を処理すると想定しないでください。これらが扱うのは数値です。単位が重要な場合は getUnit ／ unitize を使います。
• ❌ ドキュメントに記載されていない動作を上書きしたり、当てにしたりしないでください。ドキュメントに記載された API を使ってください。

詳細はこちら

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