FxTS

throttle() function

throttle 関数は、指定された期間内に最大 1 回だけ呼び出すことができる関数のスロットル版を作成します。debounce とは異なり、throttle は連続的な呼び出し中でも関数が一定の間隔で呼び出されることを保証し、一時停止を待ちません。これは、スクロールハンドラー、ウィンドウのリサイズ、API 呼び出しなどのコストのかかる操作の頻度を制限するのに役立ちます。

スロットルされた関数は leading および trailing エッジの実行をサポートします:

leading: 最初の呼び出し時に即座に実行
trailing: スロットル期間の終了時に最新の引数で実行

スロットルされた関数には、保留中の trailing 呼び出しをキャンセルできる .cancel() メソッドが含まれています。

Signature:

typescript

declare function throttle<T extends (...args: any[]) => void>(
  func: T,
  wait: number,
  options?: {
    leading: boolean;
    trailing: boolean;
  },
): ((...args: Parameters<T>) => void) & {
  cancel: () => void;
};

Example

// 基本的な使用法（デフォルトオプション - leading と trailing の両方が有効）
const throttled = throttle((val: number) => {
  console.log("val", val);
}, 1000);

throttled(1); // 即座に出力: val 1
throttled(2); // 無視される
throttled(3); // 無視される
// 1000ms 後に出力: val 3 (最新の引数で trailing 呼び出し)

// Leading エッジのみ（急速な繰り返し操作の防止に便利）
const throttled = throttle(
  (val: number) => {
    console.log("val", val);
  },
  1000,
  { leading: true, trailing: false },
);

throttled(1); // 即座に出力: val 1
throttled(2); // 無視される
throttled(3); // 無視される
// 1000ms 後に何も起こらない

// Trailing エッジのみ（バッチ処理に便利）
const throttled = throttle(
  (val: number) => {
    console.log("val", val);
  },
  1000,
  { leading: false, trailing: true },
);

throttled(1); // 遅延される
throttled(2); // 遅延される
throttled(3); // 遅延される
// 1000ms 後に出力: val 3 (最新の値のみ)

// 保留中のスロットル呼び出しをキャンセル
const throttled = throttle((val: number) => {
  console.log("val", val);
}, 1000);

throttled(1); // 即座に出力: val 1
throttled(2);
throttled(3);
throttled.cancel(); // 保留中の trailing 呼び出しをキャンセル
// 1000ms 後に何も起こらない

// 実際の使用例 - スクロールイベントのスロットル
const handleScroll = throttle(() => {
  console.log("Scroll position:", window.scrollY);
}, 200);

window.addEventListener("scroll", handleScroll);

// ハンドラーは最初のスクロール時に即座に実行され、
// 連続的なスクロール中は200msごとに最大1回実行され、
// スクロールが停止した後にもう一度実行されます（trailing エッジ）

Open Source Code

throttle() function ​

Example ​

throttle() function

Example