Skip to content

debounce — Debounce ​

17:43

Description ​

$u.debounce takes a callback and a wait time and returns a debounced function. In delayed mode each call restarts the timer and the last call runs after wait milliseconds of silence; in immediate mode the first call runs at once and calls within the wait window are ignored.

Examples ​

Normal click (no debounce) ​

Baseline: every click increments the counter and records the time immediately, for comparison with the debounced execution count.

View source
vue
<template>
    <ux-cell-group :border="false">
        <ux-cell-item title="点击次数" :value="clickCount" :arrow="false" />
        <ux-cell-item title="最近点击时间" :value="lastClickTime.length > 0 ? lastClickTime : '-'" :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);
const lastClickTime = ref('');

function onClick(): void {
    clickCount.value++;
    lastClickTime.value = new Date().toLocaleTimeString();
}
</script>

Debounced click (delayed execution) ​

With immediate set to false, repeated clicks keep resetting the timer, and the callback runs once 500ms after the last click.

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="防抖点击(500ms)" @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('');

// 防抖函数只创建一次,跨点击复用
const debouncedFn = $u.debounce((): void => {
    executeCount.value++;
    lastExecuteTime.value = new Date().toLocaleTimeString();
}, 500, false);

function onClick(): void {
    clickCount.value++;
    debouncedFn();
}
</script>

Debounced click (immediate execution) ​

With immediate set to true, the first click runs at once and further clicks within 500ms are dropped, so the execution count stays well below the click count.

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="立即执行(500ms)" @click="onClick()" />
</template>

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

const executeCount = ref(0);

// immediate 为 true:首次点击立即执行,等待期内的后续点击被丢弃
const immediateFn = $u.debounce((): void => {
    executeCount.value++;
}, 500, true);

function onClick(): void {
    immediateFn();
}
</script>

API ​

Parameters ​

ParameterDescriptionTypeDefaultVersion
funcThe callback to execute() => void--
waitWait time in msnumber500-
immediateWhether to run on the first callbooleanfalse-

Returns ​

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

Notes ​

  • When immediate is false, every call clears the previous timer and only the last callback runs after the window ends.
  • When immediate is true, the first call runs immediately and all calls within the wait window are ignored.
  • The returned function should be stored and reused; each $u.debounce call creates its own timers.
  • The returned function has no cancel method, so the timer still fires its callback after leaving the page.