Skip to content

useThrottle 节流 Hook ​

17:43

说明 ​

useThrottle 创建一个可复用的节流函数:首次调用立即执行,间隔内的后续调用被忽略;间隔取 Hook 初始化时的默认值,也可在单次调用时临时指定。

示例 ​

默认间隔(1000ms) ​

第二参数传 null 时使用 Hook 初始化时的 1000ms 间隔,首次点击立即执行,间隔内的后续点击被丢弃。

查看源码
vue
<template>
    <ux-cell-group :border="false">
        <ux-cell-item
            v-for="(item, index) in defaultRows"
            :key="index"
            :title="item.title"
            :value="item.value"
            :arrow="false"
            :border-bottom="!item.last"
        />
    </ux-cell-group>
    <ux-gap :height="12" />
    <ux-button size="small" type="primary" block text="默认间隔(1000ms)" @click="handleThrottleClick()" />
</template>

<script setup lang="ts">
import { useThrottle } from '@/uni_modules/uview-pro-x';

// 解构方式使用:const { throttle } = useThrottle(delay)
const { throttle } = useThrottle(1000);

type CellRow = {
    title: string;
    value: string;
    last: boolean;
};

const clickCount = ref(0);
const executeCount = ref(0);
const lastExecuteTime = ref('');

const defaultRows = computed((): CellRow[] => [
    { title: '点击次数', value: clickCount.value.toString(), last: false },
    { title: '实际执行次数', value: executeCount.value.toString(), last: false },
    { title: '最近执行时间', value: lastExecuteTime.value.length > 0 ? lastExecuteTime.value : '-', last: true }
]);

// 第二个参数传 null 表示使用 Hook 初始化时的默认间隔
function handleThrottleClick(): void {
    clickCount.value++;
    throttle((): void => {
        executeCount.value++;
        lastExecuteTime.value = new Date().toLocaleTimeString();
    }, null);
}
</script>

自定义间隔(2000ms) ​

单次调用把第二参数传为 2000ms,本次触发改用该间隔,覆盖 Hook 初始化时的 1000ms。

查看源码
vue
<template>
    <ux-cell-group :border="false">
        <ux-cell-item
            v-for="(item, index) in customRows"
            :key="index"
            :title="item.title"
            :value="item.value"
            :arrow="false"
            :border-bottom="!item.last"
        />
    </ux-cell-group>
    <ux-gap :height="12" />
    <ux-button size="small" type="primary" block text="自定义间隔(2000ms)" @click="handleCustomThrottle()" />
</template>

<script setup lang="ts">
import { useThrottle } from '@/uni_modules/uview-pro-x';

const { throttle } = useThrottle(1000);

type CellRow = {
    title: string;
    value: string;
    last: boolean;
};

const customClickCount = ref(0);
const customExecuteCount = ref(0);

const customRows = computed((): CellRow[] => [
    { title: '点击次数', value: customClickCount.value.toString(), last: false },
    { title: '实际执行次数', value: customExecuteCount.value.toString(), last: true }
]);

// 本次调用临时指定 2000ms
function handleCustomThrottle(): void {
    customClickCount.value++;
    throttle((): void => {
        customExecuteCount.value++;
    }, 2000);
}
</script>

临时指定间隔(3000ms) ​

在单次调用中传入 3000ms,同一实例每次调用都可以切换间隔值。

查看源码
vue
<template>
    <ux-cell-group :border="false">
        <ux-cell-item
            v-for="(item, index) in dynamicRows"
            :key="index"
            :title="item.title"
            :value="item.value"
            :arrow="false"
            :border-bottom="!item.last"
        />
    </ux-cell-group>
    <ux-gap :height="12" />
    <ux-button size="small" type="primary" block text="临时指定间隔(3000ms)" @click="handleDynamicThrottle()" />
</template>

<script setup lang="ts">
import { useThrottle } from '@/uni_modules/uview-pro-x';

const { throttle } = useThrottle(1000);

type CellRow = {
    title: string;
    value: string;
    last: boolean;
};

const dynamicClickCount = ref(0);
const dynamicExecuteCount = ref(0);

const dynamicRows = computed((): CellRow[] => [
    { title: '点击次数', value: dynamicClickCount.value.toString(), last: false },
    { title: '实际执行次数', value: dynamicExecuteCount.value.toString(), last: true }
]);

// 本次调用临时指定 3000ms
function handleDynamicThrottle(): void {
    dynamicClickCount.value++;
    throttle((): void => {
        dynamicExecuteCount.value++;
    }, 3000);
}
</script>

使用说明 ​

以提示条列出 useThrottle(delay) 的签名与 delay、throttle、callback、throttleTime 各参数的含义。

查看源码
vue
<template>
    <ux-alert-tips type="primary" :show-icon="true" title="const { throttle } = useThrottle(delay)" />
    <ux-gap :height="8" />
    <ux-alert-tips type="primary" :show-icon="true" title="delay:Hook 初始化时的默认间隔,单位 ms,省略时为 500" />
    <ux-gap :height="8" />
    <ux-alert-tips type="primary" :show-icon="true" title="throttle:返回值,调用即触发一次节流(首触即执行)" />
    <ux-gap :height="8" />
    <ux-alert-tips type="primary" :show-icon="true" title="callback:窗口内首次触发时执行的回调" />
    <ux-gap :height="8" />
    <ux-alert-tips type="primary" :show-icon="true" title="throttleTime:本次调用的间隔,传 null 用默认值" />
</template>

<script setup lang="ts">
import { useThrottle } from '@/uni_modules/uview-pro-x';

const { throttle } = useThrottle(1000);
</script>

API ​

参数 ​

参数说明类型默认值版本
delayHook 初始化时的默认间隔(ms)number500-

返回值 ​

字段说明类型
throttle触发一次节流;第二参数传 null 时使用默认间隔(callback: () => void, throttleTime: number | null) => void

注意事项 ​

  • 首触即执行:间隔内的后续调用被直接丢弃,不会排队延后补执行。
  • 单次调用传入不同间隔会重建实例,旧实例尚未结束的间隔窗口不会再触发旧回调。
  • 第二参数传 null 使用 Hook 初始化时的 delay,传数字则把本次间隔切换为该值。
  • 返回值只提供触发方法,没有暴露取消或改为延迟执行的配置。