接口定义

DebounceOptions

防抖函数的配置选项接口：

• delay: 延迟时间（毫秒），默认300ms
• immediate: 是否在首次调用时立即执行，默认false
• maxWait: 最大等待时间（毫秒），防止长时间不执行，默认为delay的3倍

DebouncedFunction<T>

防抖函数返回值类型：

• 防抖后的函数本身
• flush: 立即执行函数，忽略防抖
• cancel: 取消当前的防抖等待
• isPending: 当前是否正在等待执行

---

核心方法

useDebounce<T>(fn, options)

功能：通用防抖函数，用于任意函数的防抖处理

参数：

• fn: 要进行防抖处理的函数
• options: 防抖配置选项

返回值：包含防抖函数和控制方法的对象

内部机制：

1. 使用 setTimeout 实现延迟执行
2. 支持立即执行选项（immediate）
3. 设置最大等待时间（maxWait）防止长时间不执行
4. 提供清理定时器、立即执行和取消执行的方法

使用场景：搜索输入、窗口调整、按钮点击等需要避免频繁触发的场景

---

响应式相关方法

useDebouncedWatch<T>(source, fn, options)

功能：响应式值的防抖组合式函数，专门用于监听响应式数据的变化

参数：

• source: 要监听的响应式值（Ref）
• fn: 值变化时执行的回调函数
• options: 防抖配置选项

返回值：

• stop: 停止监听函数
• flush: 立即执行当前等待的函数
• cancel: 取消当前等待的执行
• isPending: 当前是否正在等待执行

使用场景：监听搜索框、筛选条件等响应式数据的变化

---

useDebouncedRef<T>(initialValue, callback, options)

功能：用于表单输入的防抖组合式函数，专门为搜索和表单场景优化

参数：

• initialValue: 初始值
• callback: 值变化时的回调函数
• options: 防抖配置选项

返回值：

• value: 响应式值，可直接在模板中使用 v-model 绑定
• stop: 停止监听
• flush: 立即执行当前等待的函数
• cancel: 取消当前等待的执行
• isPending: 当前是否正在等待执行

使用场景：搜索框输入防抖、表单输入验证防抖

---

异步处理相关方法

useDebouncedAsync<T>(asyncFn, options)

功能：异步函数的防抖处理，专门用于处理API调用等异步操作

参数：

• asyncFn: 异步函数
• options: 防抖配置选项

返回值：

• execute: 执行防抖后的异步函数
• flush: 立即执行
• cancel: 取消执行
• isPending: 是否正在等待执行
• isLoading: 是否正在加载（异步操作执行中）
• error: 错误信息
• data: 最后一次成功的结果

内部机制：

1. 包装异步函数以处理加载状态和错误处理
2. 提供完整的异步操作状态管理
3. 支持防抖控制和状态查询

使用场景：API搜索调用、异步数据获取、需要防抖的异步操作

---

技术特点

1. 类型安全：完整的TypeScript类型定义
2. 响应式集成：与Vue的响应式系统完美集成
3. 灵活配置：支持多种防抖选项配置
4. 状态管理：提供完整的执行状态信息
5. 错误处理：异步版本包含错误处理机制
6. 内存安全：自动清理定时器，避免内存泄漏

---

使用建议

• 搜索场景：使用 useDebouncedRef 或 useDebouncedAsync
• 事件处理：使用 useDebounce 包装事件处理函数
• 数据监听：使用 useDebouncedWatch 监听响应式数据变化
• API调用：使用 useDebouncedAsync 处理异步请求

版权所有

版权归属：Evoliant

许可证：MIT