GSAPのUtilsメソッド紹介

はじめに
- この記事の概要
- 対象読者
Utilsの概要
- GSAP Utils 公式概要（日本語翻訳）
Utilsの紹介
さいごに

はじめに

この記事の概要

こんにちは、株式会社TOKOSのスギタです！
今回はGSAPのUtilsの中からおすすめのメソッドを紹介します。
GSAPはCore機能やScrollTriggerが多く使われると思いますが、Utilsもかなり使いやすいメソッドが用意されています。
その中でも使用できそうというものを紹介していきます。

対象読者

JavaScriptを用いたアニメーションに興味のある方

この記事で扱わない内容:

JavaScriptの基本的な仕様方法
GSAPの仕様やインストール方法

Utilsの概要

GSAP Utils 公式概要（日本語翻訳）

gsap.utils は、驚くほど役立つユーティリティ関数にアクセスできます。これらの関数の多くは、オプションで関数を返すことができるため、GSAPの関数ベース機能を活用して、直接Tweenに組み込むことができます。この場合、すべてのターゲットに同じ終了値を使用するのではなく、各ターゲットに対して一度ずつ呼び出されます。

この「関数を返す」という機能が、GSAPのutilsの特徴になります。

JavaScript

// 通常の使い方：全ての要素に同じ値
gsap.to(".box", { x: 100 }); // すべてのボックスが同じ位置に移動

// 関数を返す使い方：各要素に異なる値
gsap.to(".box", { 
  x: () => gsap.utils.random(-200, 200) // 各ボックスが異なるランダム位置に移動
});

// またはこのように
gsap.to(".box", { 
  x: gsap.utils.random(-200, 200, true) // trueで関数として返す
});

このようにUtilsは.to メソッドなどCore機能と相性が良いです！
置き換えれる箇所は積極的に使用して行きたいところです！

Utilsの紹介

clamp() – 値を範囲内に制限する

値が範囲を超えないように制限してくれます！
使いどころ: 要素が画面からはみ出さないようにしたい時など

JavaScript

// 基本的な使い方
gsap.utils.clamp(0, 100, 150); // 結果: 100 (150は大きすぎるので100に)
gsap.utils.clamp(0, 100, -10);  // 結果: 0 (マイナスは0に)
gsap.utils.clamp(0, 100, 50);   // 結果: 50 (そのまま)

// 実用例：ボックスを画面からはみ出させない
gsap.to(".box", {
  x: 500,
  modifiers: {
    x: gsap.utils.clamp(0, 300) // 0〜300pxの範囲内に制限
  }
});

mapRange() – 数値を別の範囲に変換する

ある範囲の数値を、別の範囲の数値に変換します。
使いどころ: スクロール量で何かを動かしたい時

JavaScript

// 基本的な使い方
// 0〜100の範囲の「50」を、0〜360の範囲に変換すると？
gsap.utils.mapRange(0, 100, 0, 360, 50); // 結果: 180

// 実用例：スクロール量を回転角度に変換
window.addEventListener('scroll', () => {
  const scrollY = window.scrollY;
  const rotation = gsap.utils.mapRange(0, 1000, 0, 360, scrollY);
  gsap.set('.wheel', { rotation: rotation });
});

random() – ランダムな値を作る

ランダムな数値や配列の要素を取得します。
使いどころ: パーティクルアニメーションや、バラバラな動きを作りたい時

JavaScript

// 基本的な使い方
gsap.utils.random(0, 100);     // 0〜100のランダムな数
gsap.utils.random(["red", "blue", "green"]); // 配列からランダム選択

// 実用例：複数の要素をランダムな位置に
gsap.to(".box", {
  x: () => gsap.utils.random(-200, 200), // 各要素に異なるランダム値
  y: () => gsap.utils.random(-100, 100),
  duration: 1
});

snap() – 値を決まった単位に合わせる

値を指定した単位や値に「スナップ」（ぴったり合わせる）します。
使いどころ: グリッドに合わせたり、きれいに整列させたい時

JavaScript

// 基本的な使い方
gsap.utils.snap(10, 23);    // 結果: 20 (10の倍数で一番近い値)
gsap.utils.snap(50, 73);    // 結果: 50
gsap.utils.snap([0, 25, 50, 100], 30); // 結果: 25 (配列の中で一番近い値)

// 実用例：ドラッグした要素をグリッドに合わせる
gsap.to(".draggable", {
  x: 123,
  modifiers: {
    x: gsap.utils.snap(50) // 50px単位でスナップ
  }
});

wrap() – 値をループさせる

値が範囲を超えたら、最初に戻ります。
使いどころ: 無限スクロールやカルーセルを作る時

JavaScript

// 基本的な使い方
gsap.utils.wrap(0, 100, 150); // 結果: 50 (100を超えた分は最初から数える)
gsap.utils.wrap(0, 100, -10);  // 結果: 90

// 配列での使用
const colors = ["red", "green", "blue"];
gsap.utils.wrap(colors, 5); // 結果: "blue" (5番目は存在しないので、2番目に戻る)

// 実用例：無限に繰り返すアニメーション
gsap.to(".ball", {
  x: 1000,
  duration: 5,
  ease: "none",
  modifiers: {
    x: gsap.utils.wrap(0, 400) // 0〜400pxの範囲でループ
  }
});

toArray() – いろんな要素を配列にする

CSSセレクターや要素を配列に変換します。
使いどころ: 複数の要素を一度にアニメーションしたい時

JavaScript

// 基本的な使い方
const boxes = gsap.utils.toArray(".box");     // class="box"の要素を全て配列に
const items = gsap.utils.toArray("#item1, #item2"); // 複数のIDを配列に

// 実用例：複数の要素を順番にアニメーション
const elements = gsap.utils.toArray(".item");
gsap.from(elements, {
  y: 50,
  opacity: 0,
  duration: 0.5,
  stagger: 0.2 // 0.2秒ずつずらして実行
});

interpolate() – 2つの値の間を補間する

2つの値の間の中間値を計算します。
使いどころ: 色のグラデーションやプログレスバーを作る時

JavaScript

// 基本的な使い方
gsap.utils.interpolate(0, 100, 0.5);    // 結果: 50 (中間地点)
gsap.utils.interpolate("#ff0000", "#0000ff", 0.5); // 赤と青の中間色

// 実用例：スクロールに合わせて色を変える
const colorChanger = gsap.utils.interpolate("#red", "#blue");
window.addEventListener('scroll', () => {
  const progress = window.scrollY / 1000; // スクロール進行度
  const color = colorChanger(progress);
  document.body.style.backgroundColor = color;
});

shuffle() – 配列をシャッフルする

配列をランダムに並び替えます。
使いどころ: ランダムな順番で何かを表示したい時

JavaScript

// 基本的な使い方
const colors = ["red", "green", "blue"];
gsap.utils.shuffle(colors);
console.log(colors); // ランダムに並び替えられた配列

// 実用例：要素をランダムな順番でアニメーション
const boxes = gsap.utils.toArray(".box");
gsap.utils.shuffle(boxes); // 順番をシャッフル
gsap.from(boxes, {
  scale: 0,
  duration: 0.3,
  stagger: 0.1 // シャッフルされた順番で表示
});

pipe() – 複数の処理を連続で実行

複数の関数を順番に実行します。
使いどころ: 複雑な計算を段階的に処理したい時

JavaScript

// 基本的な使い方
const transform = gsap.utils.pipe(
  gsap.utils.clamp(0, 100),      // まず0〜100に制限
  gsap.utils.mapRange(0, 100, 0, 360) // 次に0〜360度に変換
);

const result = transform(150); // 150 → 100 → 360

// 実用例：マウス位置を色に変換
const mouseToColor = gsap.utils.pipe(
  gsap.utils.clamp(0, window.innerWidth),  // 画面幅に制限
  gsap.utils.mapRange(0, window.innerWidth, 0, 1), // 0〜1に変換
  gsap.utils.interpolate("#ff0000", "#0000ff")      // 色に変換
);

document.addEventListener('mousemove', (e) => {
  document.body.style.backgroundColor = mouseToColor(e.clientX);
});

normalize() – 値を0〜1の範囲に変換

値を0〜1の範囲（パーセンテージ）に変換します。
使いどころ: プログレスバーや進行度を表示したい時

JavaScript

// 基本的な使い方
gsap.utils.normalize(0, 100, 25); // 結果: 0.25 (25%)
gsap.utils.normalize(0, 100, 50); // 結果: 0.5 (50%)

// 実用例：プログレスバー
window.addEventListener('scroll', () => {
  const maxScroll = document.body.scrollHeight - window.innerHeight;
  const progress = gsap.utils.normalize(0, maxScroll, window.scrollY);
  gsap.set('.progress-bar', { scaleX: progress });
});