useDebounce 防抖 Hook
17:43说明
useDebounce 创建一个可复用的防抖函数:每次调用重新计时,延迟窗口结束后只执行最后一次回调;延迟取 Hook 初始化时的默认值,也可在单次调用时临时指定。
示例
默认延迟(500ms)
第二参数传 null 时使用 Hook 初始化时的 500ms 延迟,连续点击只在最后一次点击后执行回调。
查看源码
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>自定义延迟(1000ms)
单次调用把第二参数传为 1000ms,本次触发改用该延迟,覆盖 Hook 初始化时的 500ms。
查看源码
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>临时指定延迟(2000ms)
在单次调用中传入 2000ms,同一实例每次调用都可以切换延迟值。
查看源码
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>使用说明
以提示条列出 useDebounce(delay) 的签名与 delay、debounce、callback、debounceTime 各参数的含义。
查看源码
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
参数
| 参数 | 说明 | 类型 | 默认值 | 版本 |
|---|---|---|---|---|
| delay | Hook 初始化时的默认延迟(ms) | number | 500 | - |
返回值
| 字段 | 说明 | 类型 |
|---|---|---|
| debounce | 触发一次防抖;第二参数传 null 时使用默认延迟 | (callback: () => void, debounceTime: number | null) => void |
注意事项
- 连续调用共用同一个
debounce实例时防抖状态会累计;单次调用传入不同延迟会重建实例,旧实例中尚未触发的定时器不再执行回调。 - 第二参数传
null使用 Hook 初始化时的delay,传数字则把本次延迟切换为该值。 - 窗口结束时执行的是最后一次调用传入的
callback,每次调用都会更新回调引用。 - 返回值只提供触发方法,没有暴露主动取消或立即执行的接口。