throttle — Throttle
17:43Description
$u.throttle takes a callback and an interval and returns a throttled function that runs at most once per wait window. Immediate mode runs at the start of the window, delayed mode at the end.
Examples
Normal click (no throttle)
Baseline: every click is counted with no interval limit.
View source
vue
<template>
<ux-cell-group :border="false">
<ux-cell-item title="点击次数" :value="clickCount" :arrow="false" :border-bottom="false" />
</ux-cell-group>
<ux-gap :height="8" />
<ux-button size="small" type="primary" block text="普通点击" @click="onClick()" />
</template>
<script setup lang="ts">
const clickCount = ref(0);
function onClick(): void {
clickCount.value++;
}
</script>Throttled click (immediate execution)
With immediate set to true, the callback runs at the start of the window and later clicks within 1000ms are ignored.
View source
vue
<template>
<ux-cell-group :border="false">
<ux-cell-item title="触发次数" :value="clickCount" :arrow="false" />
<ux-cell-item title="实际执行次数" :value="executeCount" :arrow="false" />
<ux-cell-item title="最近执行时间" :value="lastExecuteTime.length > 0 ? lastExecuteTime : '-'" :arrow="false" :border-bottom="false" />
</ux-cell-group>
<ux-gap :height="8" />
<ux-button size="small" type="primary" block text="节流点击(1000ms)" @click="onClick()" />
</template>
<script setup lang="ts">
import { $u } from '@/uni_modules/uview-pro-x';
const clickCount = ref(0);
const executeCount = ref(0);
const lastExecuteTime = ref('');
// 节流函数只创建一次,跨点击复用;immediate 为 true 表示窗口起点先执行
const throttledFn = $u.throttle((): void => {
executeCount.value++;
lastExecuteTime.value = new Date().toLocaleTimeString();
}, 1000, true);
function onClick(): void {
clickCount.value++;
throttledFn();
}
</script>Throttled click (delayed execution)
With immediate set to false, the callback runs once at the end of the window using the first trigger in that window.
View source
vue
<template>
<ux-cell-group :border="false">
<ux-cell-item title="实际执行次数" :value="executeCount" :arrow="false" :border-bottom="false" />
</ux-cell-group>
<ux-gap :height="8" />
<ux-button size="small" type="primary" block text="延迟执行(1000ms)" @click="onClick()" />
</template>
<script setup lang="ts">
import { $u } from '@/uni_modules/uview-pro-x';
const executeCount = ref(0);
// immediate 为 false:窗口结束时执行一次
const delayFn = $u.throttle((): void => {
executeCount.value++;
}, 1000, false);
function onClick(): void {
delayFn();
}
</script>API
Parameters
| Parameter | Description | Type | Default | Version |
|---|---|---|---|---|
| func | The callback to execute | () => void | - | - |
| wait | Throttle interval in ms | number | 500 | - |
| immediate | Whether to run at the start of the window | boolean | true | - |
Returns
| Type | Description |
|---|---|
() => void | The throttled function; it takes no arguments and returns nothing |
Notes
- When
immediateistrue, the first call runs at the start of the window, calls withinwaitare ignored, and the window resumes afterwards. - When
immediateisfalse, the callback runs at the end of the window and only the first trigger in that window is kept; later triggers are not queued. - The returned function should be stored and reused; each
$u.throttlecall keeps its own throttle state. - The returned function has no cancel method, so the timer still fires its callback after leaving the page.