前言

节流和防抖是前端开发中常用的性能优化手段，防止用户快速重复点击导致多次触发。@pura/harmony-utils 的 ClickUtil 封装了节流防抖方法，保护应用免受重复点击影响。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、ClickUtil核心API

ClickUtil 提供了以下节流防抖方法：

方法	说明	参数	使用场景
throttle(callback, delay)	节流包装	callback, delay	按钮防重复
debounce(callback, delay)	防抖包装	callback, delay	搜索输入

1.1 核心特性

• 简洁易用：封装复杂逻辑为一行调用，降低使用门槛
• 类型安全：完整的TypeScript类型定义，编译期即可发现错误
• 异常处理：内置异常捕获机制，避免运行时崩溃
• 灵活配置：支持自定义延迟时间

1.2 节流与防抖对比

特性	节流(Throttle)	防抖(Debounce)
触发方式	固定间隔执行	停止后执行
首次触发	立即执行	延迟执行
适用场景	按钮点击	搜索输入
典型延迟	500-1000ms	300-500ms

二、完整使用步骤

2.1 安装依赖

ohpm install @pura/harmony-utils

2.2 节流（Throttle）

import { ClickUtil } from '@pura/harmony-utils';

private throttledClick = ClickUtil.throttle(() => {
  this.count++;
  this.result = `节流点击次数: ${this.count}`;
}, 1000);

Button('节流按钮(1秒内只触发一次)')
  .width('100%')
  .onClick(() => {
    this.throttledClick();
  })

2.3 防抖（Debounce）

private debouncedSearch = ClickUtil.debounce((keyword: string) => {
  this.result = `搜索: ${keyword}`;
}, 500);

TextInput()
  .width('100%')
  .onChange((value) => {
    this.debouncedSearch(value);
  })

三、完整页面示例

import { ClickUtil } from '@pura/harmony-utils';

@Entry
@Component
struct ClickDemo {
  @State count: number = 0;
  @State result: string = '';
  @State searchText: string = '';

  build() {
    Column({ space: 12 }) {
      Button('节流按钮').width('100%').onClick(
        ClickUtil.throttle(() => {
          this.count++;
          this.result = `点击${this.count}次`;
        }, 1000)
      );
      TextInput({ text: this.searchText })
        .onChange(ClickUtil.debounce((v: string) => {
          this.result = `搜索: ${v}`;
        }, 500));
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

四、进阶用法

4.1 表单提交防重复

import { ClickUtil, ToastUtil } from '@pura/harmony-utils';

private submitHandler = ClickUtil.throttle(async () => {
  let success = await submitForm(this.formData);
  if (success) {
    ToastUtil.show('提交成功');
  }
}, 2000);

4.2 实时搜索

private searchHandler = ClickUtil.debounce((keyword: string) => {
  if (keyword.length >= 2) {
    this.searchResults = searchApi(keyword);
  }
}, 300);

五、注意事项

1. 延迟设置：节流建议500-1000ms，防抖建议300-500ms
2. 引用稳定：throttle/debounce返回的函数应保持引用稳定
3. 内存泄漏：组件销毁时防抖定时器可能未清除
4. 初始化依赖：使用前需确保 AppUtil.init() 已调用
5. this指向：注意箭头函数的this指向问题

六、常见问题

Q1: 节流后第一次点击无响应？

节流首次触发会立即执行，如果无响应请检查回调函数逻辑。

Q2: 防抖搜索输入延迟太大？

适当减小delay值，搜索场景建议300ms。

Q3: 多个按钮可以共用一个节流函数吗？

不建议，每个按钮应有独立的节流函数。

Q4: 节流和防抖可以嵌套使用吗？

可以但不推荐，通常一个场景选择一种即可。

总结

ClickUtil 的节流防抖方法为防止重复操作提供了便捷支持。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。开发者可以根据场景选择节流或防抖来优化用户交互。

本文基于 @pura/harmony-utils 工具库，更多功能请参考官方文档与后续系列文章。