# pd_cooldown

**Repository Path**: pedro-labs/pd_cooldown

## Basic Information

- **Project Name**: pd_cooldown
- **Description**: 一个专业的Flutter防抖节流插件，提供完整的防抖(Debounce)和节流(Throttle)解决方案。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-06
- **Last Updated**: 2026-07-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PD Cooldown

[中文文档](README_CN.md) | [English Documentation](README.md)

<div align="center">
  <img src="assets/pd_cooldown_logo.svg" alt="PD Cooldown Logo" width="150" height="150">
</div>

<div align="center">
  <strong>一个专业的Flutter防抖节流插件，提供完整的防抖(Debounce)和节流(Throttle)解决方案。</strong>
</div>

<br>

## 特性

- 🚀 **高性能**: 使用同步锁确保线程安全
- 🎯 **易用性**: 简洁的API设计，支持多种使用方式
- 🔧 **可配置**: 支持自定义日志和错误处理
- 🎨 **UI组件**: 内置防抖和节流按钮组件
- 📦 **模块化**: 清晰的代码架构，易于维护和扩展

## 安装

在 `pubspec.yaml` 中添加依赖：

```yaml
dependencies:
  pd_cooldown: ^0.3.1
```

然后运行：

```bash
flutter pub get
```

## 快速开始

### 1. 导入包

```dart
import 'package:pd_cooldown/pd_cooldown.dart';
```

### 2. 基础使用

#### 防抖节流核心功能

```dart
// 创建防抖节流实例
final cooldown = PDCooldown.withDefaults(
  cooldownDuration: const Duration(seconds: 3),
);

// 执行防抖节流操作
final result = await cooldown.execute<String>(() async {
  // 你的异步操作
  await Future.delayed(const Duration(milliseconds: 500));
  return '操作完成';
}, onCooldown: (remaining) {
  print('冷却中，剩余时间: ${remaining.inSeconds}秒');
});

if (result != null) {
  print('执行结果: $result');
} else {
  print('操作被冷却限制');
}
```

#### UI组件使用

```dart
// 节流按钮 - 立即响应第一次点击，冷却期间忽略后续点击
PDThrottleButton(
  buttonType: PDButtonType.elevated,
  debounceDuration: const Duration(seconds: 2),
  onPressed: () {
    print('节流按钮被点击');
  },
  child: const Text('节流按钮'),
)

// 防抖按钮 - 延迟响应，只有在指定时间内没有新点击时才触发
PDDebounceButton(
  buttonType: PDButtonType.elevated,
  debounceDuration: const Duration(milliseconds: 800),
  onPressed: () {
    print('防抖按钮被点击');
  },
  child: const Text('防抖按钮'),
)
```

## 高级用法

### 自定义日志和错误处理

```dart
final cooldown = PDCooldown.withCallbacks(
  cooldownDuration: const Duration(seconds: 5),
  onDebug: (message) => print('调试: $message'),
  onError: (message) => print('错误: $message'),
  onErrorHandler: (error, stackTrace, prefix) {
    // 自定义错误处理逻辑
    print('$prefix: $error');
  },
);
```

### 检查冷却状态

```dart
// 检查是否在冷却中
if (cooldown.isInCooldown()) {
  final remaining = cooldown.getRemainingCooldown();
  print('还需等待 ${remaining.inSeconds} 秒');
}

// 重置冷却状态
cooldown.reset();
```

## API 文档

### PDCooldown

核心防抖节流类，提供以下方法：

#### 构造函数

- `PDCooldown()` - 基础构造函数
- `PDCooldown.withDefaults()` - 使用默认日志和错误处理
- `PDCooldown.withCallbacks()` - 使用自定义回调

#### 主要方法

- `execute<T>()` - 执行防抖节流操作
- `isInCooldown()` - 检查是否在冷却中
- `getRemainingCooldown()` - 获取剩余冷却时间
- `reset()` - 重置冷却状态

### UI组件

#### PDThrottleButton

节流按钮组件，主要属性：

- `onPressed` - 点击回调
- `child` - 子组件
- `debounceDuration` - 冷却时间
- `buttonType` - 按钮类型
- `cooldownOpacity` - 冷却时透明度

#### PDDebounceButton

防抖按钮组件，主要属性：

- `onPressed` - 点击回调
- `child` - 子组件
- `debounceDuration` - 防抖时间
- `buttonType` - 按钮类型
- `debounceOpacity` - 防抖时透明度

## 示例

查看 `example` 目录获取完整的使用示例。

## 贡献

欢迎提交 Issue 和 Pull Request！

## 许可证

本项目采用 MIT 许可证。