debounceClick 防抖点击指令

用于对点击事件进行防抖处理，避免用户快速连续点击导致重复触发。支持领先/尾随触发、阻止默认行为、阻止冒泡等配置。

安装与引入

按需导入（推荐）

import { VDebounceClick } from '@cuixingjian/cui-utils'

全局注册

import { createApp } from 'vue'
import { VDebounceClick } from '@cuixingjian/cui-utils'

const app = createApp(App)
app.directive('debounce-click', VDebounceClick)
app.mount('#app')

局部注册

<script setup lang="ts">
import { VDebounceClick as vDebounceClick } from '@cuixingjian/cui-utils'
</script>

<template>
  <button v-debounce-click="handler">点击</button>
</template>

---

效果演示

基础用法

快速连续点击按钮，只会在停止点击后触发一次。

使用代码

直接传入函数（默认 200ms）：

<template>
  <button v-debounce-click="onSubmit">提交</button>
</template>

<script setup lang="ts">
function onSubmit(e: Event) {
  console.log('提交表单')
}
</script>

自定义等待时间：

<template>
  <button v-debounce-click="{ wait: 500, onClick: onSearch }">搜索</button>
</template>

领先触发（第一次点击立即执行）：

<template>
  <button v-debounce-click="{ leading: true, trailing: false, onClick: onSave }">
    保存
  </button>
</template>

---

API 说明

指令值类型

类型	说明	示例
Function	直接传入处理函数	v-debounce-click="handler"
Object	传入配置对象	v-debounce-click="{ wait: 500, onClick: handler }"

配置选项 (DebounceClickOptions)

参数	类型	默认值	说明
wait	number	200	防抖等待时间（毫秒）
leading	boolean	false	是否在首次点击时立即触发
trailing	boolean	true	是否在等待结束后触发
enabled	boolean	true	是否启用防抖
prevent	boolean	false	是否阻止默认行为
stop	boolean	false	是否阻止事件冒泡
capture	boolean	false	是否在捕获阶段监听
onClick	(event: Event) => void	—	防抖后执行的处理函数

---

注意事项

触发模式

尾随触发（默认）：

• 每次点击重置计时器
• 停止点击后等待 wait 毫秒触发一次
• 适合表单提交、搜索等场景

领先触发：

• 第一次点击立即触发
• 后续点击在 wait 窗口内被抑制
• 适合需要即时反馈的场景（如收藏）

组合模式：

• leading: true, trailing: true：首次立即触发，窗口结束后再触发一次
• leading: true, trailing: false：仅首次触发，窗口内点击被忽略

常见场景

• 表单提交：防止重复提交（wait: 300-500ms）
• 搜索按钮：避免频繁请求（wait: 300ms）
• 保存/收藏：防止多次API调用（leading: true）

最佳实践

• 写入操作建议 wait >= 300ms
• 即时反馈操作使用 leading: true
• 与路由跳转配合时开启 prevent

---

源码展示

展开查看完整源码

import type { Directive } from 'vue'
import { withInstallDirective } from '../install'

export interface DebounceClickOptions {
  wait?: number
  leading?: boolean
  trailing?: boolean
  enabled?: boolean
  prevent?: boolean
  stop?: boolean
  capture?: boolean
  onClick?: (event: Event) => void
}

// 详见 packages/utils/directives/debounceClick.ts
export const VDebounceClick = withInstallDirective(debounceClick, 'debounce-click')