异步防抖指南

异步防抖指南

防抖指南中的所有核心概念同样适用于异步防抖。

何时使用异步防抖

通常情况下，你可以直接使用普通的同步防抖器，它也能与异步函数一起工作。但是，对于一些高级用例，例如希望使用防抖函数的返回值（而不仅仅是调用 setState 副作用），或者将错误处理逻辑放在防抖器中，你可以使用异步防抖器。

TanStack Pacer 中的异步防抖

TanStack Pacer 通过 AsyncDebouncer 类和 asyncDebounce 函数提供异步防抖功能。

基本用法示例

以下是一个基本示例，展示了如何将异步防抖器用于搜索操作：

const debouncedSearch = asyncDebounce(
  async (searchTerm: string) => {
    const results = await fetchSearchResults(searchTerm)
    return results
  },
  {
    wait: 500,
    onSuccess: (results, debouncer) => {
      console.log('搜索成功：', results)
    },
    onError: (error, debouncer) => {
      console.error('搜索失败：', error)
    }
  }
)

// 用法
try {
  const results = await debouncedSearch('query')
  // 处理成功的结果
} catch (error) {
  // 如果未提供 onError 处理程序，则处理错误
  console.error('搜索失败：', error)
}

const debouncedSearch = asyncDebounce(
  async (searchTerm: string) => {
    const results = await fetchSearchResults(searchTerm)
    return results
  },
  {
    wait: 500,
    onSuccess: (results, debouncer) => {
      console.log('搜索成功：', results)
    },
    onError: (error, debouncer) => {
      console.error('搜索失败：', error)
    }
  }
)

// 用法
try {
  const results = await debouncedSearch('query')
  // 处理成功的结果
} catch (error) {
  // 如果未提供 onError 处理程序，则处理错误
  console.error('搜索失败：', error)
}

与同步防抖的主要区别

1. 返回值处理

与返回 void 的同步防抖器不同，异步版本允许你捕获和使用防抖函数的返回值。maybeExecute 方法返回一个 Promise，该 Promise 会解析为函数的返回值，从而允许你等待结果并适当地处理它。

2. 错误处理

异步防抖器提供了强大的错误处理功能：

如果你的防抖函数抛出错误并且未提供 onError 处理程序，则该错误将被抛出并向上传播给调用者
如果你提供了 onError 处理程序，错误将被捕获并传递给处理程序，而不是被抛出
throwOnError 选项可用于控制错误抛出行为：
- 当为 true 时（如果未提供 onError 处理程序，则为默认值），将抛出错误
- 当为 false 时（如果提供了 onError 处理程序，则为默认值），错误将被忽略
- 可以显式设置以覆盖这些默认值
你可以使用 getErrorCount() 跟踪错误计数，并使用 getIsExecuting() 检查执行状态
防抖器会维护其状态，并且在发生错误后可以继续使用

3. 不同的回调

AsyncDebouncer 支持以下回调：

onSuccess：每次成功执行后调用，提供结果和防抖器实例
onSettled：每次执行（成功或失败）后调用，提供防抖器实例
onError：如果异步函数抛出错误，则调用，同时提供错误和防抖器实例

示例：

const asyncDebouncer = new AsyncDebouncer(async (value) => {
  await saveToAPI(value)
}, {
  wait: 500,
  onSuccess: (result, debouncer) => {
    // 每次成功执行后调用
    console.log('异步函数已执行', debouncer.getSuccessCount())
  },
  onSettled: (debouncer) => {
    // 每次执行尝试后调用
    console.log('异步函数已完成', debouncer.getSettledCount())
  },
  onError: (error) => {
    // 如果异步函数抛出错误，则调用
    console.error('异步函数失败：', error)
  }
})

const asyncDebouncer = new AsyncDebouncer(async (value) => {
  await saveToAPI(value)
}, {
  wait: 500,
  onSuccess: (result, debouncer) => {
    // 每次成功执行后调用
    console.log('异步函数已执行', debouncer.getSuccessCount())
  },
  onSettled: (debouncer) => {
    // 每次执行尝试后调用
    console.log('异步函数已完成', debouncer.getSettledCount())
  },
  onError: (error) => {
    // 如果异步函数抛出错误，则调用
    console.error('异步函数失败：', error)
  }
})