useDebounce — Debounce Hook
17:43Description
useDebounce creates a reusable debounce function: every call restarts the timer and only the last callback runs after the delay window ends. The delay comes from the hook default or can be overridden per call.
Examples
Default delay (500ms)
Passing null as the second argument uses the hook's default 500ms delay, so only the last click in a burst runs the callback.
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="默认延迟(500ms)" @click="handleDebounceClick()" />
</template>
<script setup lang="ts">
import { useDebounce } from '@/uni_modules/uview-pro-x';
// 解构方式使用:const { debounce } = useDebounce(delay)
const { debounce } = useDebounce(500);
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 handleDebounceClick(): void {
clickCount.value++;
debounce((): void => {
executeCount.value++;
lastExecuteTime.value = new Date().toLocaleTimeString();
}, null);
}
</script>Custom delay (1000ms)
Passing 1000ms as the second argument overrides the hook's 500ms 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="自定义延迟(1000ms)" @click="handleCustomDebounce()" />
</template>
<script setup lang="ts">
import { useDebounce } from '@/uni_modules/uview-pro-x';
const { debounce } = useDebounce(500);
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 }
]);
// 本次调用临时指定 1000ms
function handleCustomDebounce(): void {
customClickCount.value++;
debounce((): void => {
customExecuteCount.value++;
}, 1000);
}
</script>Temporary delay (2000ms)
Passing 2000ms on each call shows that the same instance can switch delay 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="临时指定延迟(2000ms)" @click="handleDynamicDebounce()" />
</template>
<script setup lang="ts">
import { useDebounce } from '@/uni_modules/uview-pro-x';
const { debounce } = useDebounce(500);
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 }
]);
// 本次调用临时指定 2000ms
function handleDynamicDebounce(): void {
dynamicClickCount.value++;
debounce((): void => {
dynamicExecuteCount.value++;
}, 2000);
}
</script>Usage
Lists the useDebounce(delay) signature and the meaning of delay, debounce, callback and debounceTime.
View source
vue
<template>
<ux-alert-tips type="primary" :show-icon="true" title="const { debounce } = useDebounce(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="debounce:返回值,调用即触发一次防抖" />
<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="debounceTime:本次调用的延迟,传 null 用默认值" />
</template>
<script setup lang="ts">
import { useDebounce } from '@/uni_modules/uview-pro-x';
const { debounce } = useDebounce(500);
</script>API
Parameters
| Parameter | Description | Type | Default | Version |
|---|---|---|---|---|
| delay | Default delay (ms) set when the hook is created | number | 500 | - |
Returns
| Field | Description | Type |
|---|---|---|
| debounce | Triggers one debounce; pass null as the second argument to use the default delay | (callback: () => void, debounceTime: number | null) => void |
Notes
- Repeated calls share one
debounceinstance, so the debounce state accumulates; passing a different delay on a single call rebuilds the instance and pending timers from the old instance no longer fire the callback. - Passing
nullas the second argument uses thedelaygiven to the hook, while a number switches the delay for that call. - The callback executed when the window ends is the last one passed in, since every call replaces the stored callback reference.
- Only the trigger method is returned; no cancel or immediate-execution API is exposed.