译零 TransZero · TanStack Query 中文文档
主站

TimeoutManager

更新于 2026-11-02 Preact 查看英文原文 ↗

定义于:packages/query-core/src/timeoutManager.ts:82

允许自定义超时(timeout)的创建方式。

@tanstack/query-core 大量使用超时机制来实现 staleTime 和 gcTime。默认的 TimeoutManager 提供者使用平台全局的 setTimeout 实现,而该实现已知在事件循环中存在数千个超时时的可扩展性问题。

若你遇到此限制,可考虑提供一个能合并(coalesce)超时的自定义 TimeoutProvider。

实现

方法

clearInterval()

TypeScript
1clearInterval(intervalId: ManagedTimerId | undefined): void;

定义于:packages/query-core/src/timeoutManager.ts:240

clearInterval 可用于取消一个间隔定时器(interval),其行为类似于全局 clearInterval 函数。它应传入由 setInterval 返回的间隔 ID。

参数

intervalId

ManagedTimerId | undefined

由 setInterval 返回的定时器 ID,或 undefined。

返回值

void

示例

TypeScript
1import { timeoutManager } from '@tanstack/query-core'2 3const intervalId = timeoutManager.setInterval(4  () => console.log('ran at:', new Date()),5  1000,6)7 8timeoutManager.clearInterval(intervalId)

实现自

TypeScript
1Omit.clearInterval

clearTimeout()

TypeScript
1clearTimeout(timeoutId: ManagedTimerId | undefined): void;

定义于:packages/query-core/src/timeoutManager.ts:193

clearTimeout 用于取消由 setTimeout 调度的超时回调,其行为类似于全局 clearTimeout 函数。它应传入由 setTimeout 返回的定时器 ID。

参数

timeoutId

ManagedTimerId | undefined

由 setTimeout 返回的定时器 ID,或 undefined。

返回值

void

示例

TypeScript
1import { timeoutManager } from '@tanstack/query-core'2 3const timeoutId = timeoutManager.setTimeout(4  () => console.log('ran at:', new Date()),5  1000,6)7 8timeoutManager.clearTimeout(timeoutId)

实现自

TypeScript
1Omit.clearTimeout

setInterval()

TypeScript
1setInterval(callback: TimeoutCallback, delay: number): ManagedTimerId;

定义于:packages/query-core/src/timeoutManager.ts:216

setInterval 按约 delay 毫秒的间隔调度一个回调函数执行,其行为类似于全局 setInterval 函数。

与 setTimeout 类似,它返回一个定时器 ID,该 ID 可能为数字,也可能为可通过 Symbol.toPrimitive 转换为数字的对象。

参数

callback

TimeoutCallback

每次间隔触发时调用的函数。

delay

number

两次调用之间的毫秒间隔。

返回值

ManagedTimerId

定时器 ID,供传递给 TimeoutManager#clearInterval 使用。

示例

TypeScript
1import { timeoutManager } from '@tanstack/query-core'2 3const intervalId = timeoutManager.setInterval(4  () => console.log('ran at:', new Date()),5  1000,6)

实现自

TypeScript
1Omit.setInterval

setTimeout()

TypeScript
1setTimeout(callback: TimeoutCallback, delay: number): ManagedTimerId;

定义于:packages/query-core/src/timeoutManager.ts:169

setTimeout 在约 delay 毫秒后调度一个回调函数执行,其行为类似于全局 setTimeout 函数。该回调可通过 clearTimeout 取消。

它返回一个定时器 ID,该 ID 可能为数字,也可能为可通过 Symbol.toPrimitive 转换为数字的对象。

参数

callback

TimeoutCallback

超时到期时调用的函数。

delay

number

调用 callback 前需等待的毫秒数。

返回值

ManagedTimerId

定时器 ID,供传递给 TimeoutManager#clearTimeout 使用。

示例

TypeScript
1import { timeoutManager } from '@tanstack/query-core'2 3const timeoutId = timeoutManager.setTimeout(4  () => console.log('ran at:', new Date()),5  1000,6)7 8const timeoutIdNumber: number = Number(timeoutId)

实现自

TypeScript
1Omit.setTimeout

setTimeoutProvider()

TypeScript
1setTimeoutProvider<TTimerId extends ManagedTimerId>(provider: TimeoutProvider<TTimerId>): void;

定义于:packages/query-core/src/timeoutManager.ts:118

setTimeoutProvider 可用于设置 setTimeout、clearTimeout、setInterval、clearInterval 函数的自定义实现,此类实现称为 TimeoutProvider。

若你发现应用中存在数千个查询导致事件循环性能下降,该方法可能很有用。自定义 TimeoutProvider 还可支持超过全局 setTimeout 最大约 24 天的最大延迟值的定时器延迟。

重要的是,必须在创建 QueryClient 或任何查询之前调用 setTimeoutProvider,以确保整个应用中所有定时器均一致使用同一提供者;因为不同 TimeoutProvider 之间无法相互取消对方的定时器。

类型参数

TTimerId

TTimerId extends ManagedTimerId

参数

provider

TimeoutProvider<TTimerId>

此后所有定时器将使用的 TimeoutProvider。

返回值

void

示例

TypeScript
1import { timeoutManager, QueryClient } from '@tanstack/query-core'2import { CustomTimeoutProvider } from './CustomTimeoutProvider'3 4timeoutManager.setTimeoutProvider(new CustomTimeoutProvider())5 6export const queryClient = new QueryClient()

本页为 TanStack Query 文档(Preact 版)的非官方中文翻译,原文由上游团队维护,遵循 MIT 许可。 译文如有偏差,以英文原文为准。

译自上游 59d11de