Skip to content

throttle — Throttle ​

17:43

Description ​

$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 ​

ParameterDescriptionTypeDefaultVersion
funcThe callback to execute() => void--
waitThrottle interval in msnumber500-
immediateWhether to run at the start of the windowbooleantrue-

Returns ​

TypeDescription
() => voidThe throttled function; it takes no arguments and returns nothing

Notes ​

  • When immediate is true, the first call runs at the start of the window, calls within wait are ignored, and the window resumes afterwards.
  • When immediate is false, 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.throttle call keeps its own throttle state.
  • The returned function has no cancel method, so the timer still fires its callback after leaving the page.