useThrottle — Throttle Hook
17:43Description
useThrottle creates a reusable throttle function: the first call runs immediately and later calls within the interval are ignored. The interval comes from the hook default or can be overridden per call.
Examples
Default interval (1000ms)
Passing null as the second argument uses the hook's default 1000ms interval: the first click runs immediately and later clicks within the interval are dropped.
View source
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>Custom interval (2000ms)
Passing 2000ms as the second argument overrides the hook's 1000ms default for this call.
View source
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>Temporary interval (3000ms)
Passing 3000ms on each call shows that the same instance can switch interval values per invocation.
View source
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>Usage
Lists the useThrottle(delay) signature and the meaning of delay, throttle, callback and throttleTime.
View source
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
Parameters
| Parameter | Description | Type | Default | Version |
|---|---|---|---|---|
| delay | Default interval (ms) set when the hook is created | number | 500 | - |
Returns
| Field | Description | Type |
|---|---|---|
| throttle | Triggers one throttle; pass null as the second argument to use the default interval | (callback: () => void, throttleTime: number | null) => void |
Notes
- Leading-edge execution: later calls within the interval are dropped and never queued for a trailing run.
- Passing a different interval on a single call rebuilds the instance, so the old instance's pending interval window no longer fires its callback.
- Passing
nullas the second argument uses thedelaygiven to the hook, while a number switches the interval for that call. - Only the trigger method is returned; no cancel API or delayed (trailing) mode is exposed.