首页
指南
Hooks
GitHub
首页
指南
Hooks
GitHub

useThrottle

用于限制函数执行频率的 Hook，在指定间隔内最多按规则执行一次（或 leading + trailing 各一次）。

基本信息

  • 引入：import { useThrottle } from '@resin-hooks/core';
  • 类型：useThrottle<T>(fn: T, options?: UseThrottleOptions): { throttleFn: ThrottleFn<T>; cancel: () => void }

参数

参数 类型 默认值 说明
fn (...args) => R - 需要节流的函数
options UseThrottleOptions 见下表 可选配置项

UseThrottleOptions

属性 类型 默认值 说明
interval number 1000 节流间隔（毫秒）
leading boolean true 是否在首次满足条件时立即执行
trailing boolean false 是否在间隔结束后用最后一次参数补执行一次
resultCallback (res: R) => void - fn 执行后的回调，可获取返回值

返回值

属性 类型 说明
throttleFn (...args) => R | undefined 节流后的函数，调用时传入与 fn 相同的参数
cancel () => void 取消未执行的 trailing 定时器，并重置状态

使用示例

基本用法

1import { useState } from 'react';
2import { useThrottle } from '@resin-hooks/core';
3
4function SearchInput() {
5  const [value, setValue] = useState('');
6  const [throttledValue, setThrottledValue] = useState('');
7
8  const { throttleFn, cancel } = useThrottle(
9    (val: string) => setThrottledValue(val),
10    { interval: 500, leading: true, trailing: true },
11  );
12
13  return (
14    <div>
15      <input
16        value={value}
17        onChange={(e) => {
18          const val = e.target.value;
19          setValue(val);
20          throttleFn(val);
21        }}
22      />
23      <p>节流后的值: {throttledValue}</p>
24      <button onClick={cancel}>取消未执行</button>
25    </div>
26  );
27}

使用 resultCallback 获取执行结果

1const { throttleFn } = useThrottle((id: number) => fetchUser(id), {
2  interval: 1000,
3  resultCallback: (user) => {
4    console.log('获取到用户:', user);
5  },
6});
7
8throttleFn(1);

leading 与 trailing 组合

1// leading: true, trailing: true - 首次立即执行，间隔末再执行一次（最多两次）
2const { throttleFn } = useThrottle(fn, {
3  interval: 300,
4  leading: true,
5  trailing: true,
6});
7
8// leading: false, trailing: true - 仅间隔末执行一次
9const { throttleFn } = useThrottle(fn, {
10  interval: 300,
11  leading: false,
12  trailing: true,
13});
14
15// leading: true, trailing: false - 仅首次或满足间隔时执行，无 trailing 补执行
16const { throttleFn } = useThrottle(fn, {
17  interval: 300,
18  leading: true,
19  trailing: false,
20});

使用场景

  • 搜索输入：用户输入时限制请求频率，减少接口调用
  • 滚动/resize 监听：限制 scroll、resize 等高频事件的回调执行
  • 按钮防重复点击：在间隔内只响应一次点击
  • 实时统计/埋点：限制上报频率，避免过于频繁

注意事项

  • 组件卸载时会自动清理 trailing 定时器，无需手动处理
  • throttleFn 在 interval、leading、trailing、resultCallback 变化时会重新创建
  • cancel 会清空未执行的 trailing，并将内部状态重置，下次调用会重新开始节流周期
目录