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

Query

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

定义于：packages/query-core/src/query.ts:283

表示一个已缓存的单个查询。Query 保存该查询的查询键、选项、状态（数据/错误/状态）以及当前订阅它的观察者。

实例由 QueryCache 内部创建和管理；应用代码通常通过 QueryClient 或框架 Hook（例如 useQuery）间接与查询交互。你可通过 queryCache.find()/findAll() 直接访问 Query 实例，以检查缓存状态。

示例

TypeScript
1const queryCache = queryClient.getQueryCache()2const query = queryCache.find({ queryKey: ['posts'] })3 4if (query) {5  console.log(query.state.dataUpdatedAt)6}

继承自

  • Removable

类型参数

TQueryFnData

TQueryFnData = unknown

TError

TError = DefaultError

TData

TData = TQueryFnData

TQueryKey

TQueryKey extends QueryKey = QueryKey

构造函数

构造函数

TypeScript
1new Query<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(config: QueryConfig<TQueryFnData, TError, TData, TQueryKey>): Query<TQueryFnData, TError, TData, TQueryKey>;

定义于：packages/query-core/src/query.ts:304

参数

config

QueryConfig<TQueryFnData, TError, TData, TQueryKey>

返回值

Query<TQueryFnData, TError, TData, TQueryKey>

覆盖

TypeScript
1Removable.constructor

属性

gcTime

TypeScript
1gcTime: number;

定义于：packages/query-core/src/removable.ts:11

继承自

TypeScript
1Removable.gcTime

observers

TypeScript
1observers: QueryObserver<any, any, any, any, any>[];

定义于：packages/query-core/src/query.ts:300

options

TypeScript
1options: QueryOptions<TQueryFnData, TError, TData, TQueryKey>;

定义于：packages/query-core/src/query.ts:291

queryHash

TypeScript
1queryHash: string;

定义于：packages/query-core/src/query.ts:290

queryKey

TypeScript
1queryKey: TQueryKey;

定义于：packages/query-core/src/query.ts:289

state

TypeScript
1state: QueryState<TData, TError>;

定义于：packages/query-core/src/query.ts:292

访问器

meta

获取签名

TypeScript
1get meta(): Record<string, unknown> | undefined;

定义于：packages/query-core/src/query.ts:323

查询选项中传入的 meta 对象（如果存在）。

返回值

Record<string, unknown> | undefined

查询的 meta，若未设置则返回 undefined。

promise

获取签名

TypeScript
1get promise(): Promise<TData> | undefined;

定义于：packages/query-core/src/query.ts:341

当前正在进行的拉取操作所对应的 Promise（如果查询正处于拉取中）。若查询未在拉取，则返回 undefined。

返回值

Promise<TData> | undefined

正在进行的拉取操作的 Promise，或 undefined。

方法

cancel()

TypeScript
1cancel(options?: CancelOptions): Promise<void>;

定义于：packages/query-core/src/query.ts:427

取消查询当前正在进行的拉取操作（如果存在）。

  • 返回一个 Promise，该 Promise 在取消操作完成时解析。
  • 若当前无拉取操作进行中，则立即解析。

参数

options?

CancelOptions

设置 revert 可在拉取开始前恢复之前的状态；设置 silent 可在新拉取操作替代已取消拉取时抑制取消错误。

返回值

Promise<void>

一个在取消操作完成时解析的 Promise。

示例

TypeScript
1await query.cancel()

destroy()

TypeScript
1destroy(): void;

定义于：packages/query-core/src/query.ts:439

清除查询的垃圾回收超时，并静默取消任何正在进行的拉取操作。当 QueryCache 将查询从缓存中移除时，会调用此方法。

返回值

void

参见

Query#cancel

覆盖

TypeScript
1Removable.destroy

fetch()

TypeScript
1fetch(options?: QueryOptions<TQueryFnData, TError, TData, TQueryKey, never>, fetchOptions?: FetchOptions<TQueryFnData>): Promise<TData>;

定义于：packages/query-core/src/query.ts:703

拉取查询，即运行其 queryFn（经由任何已配置的重试器/行为），并使用结果更新查询的状态。

  • 如果已有拉取操作正在进行，则直接返回其 Promise，而非启动新的拉取操作；但若设置了 fetchOptions.cancelRefetch 且查询已拥有数据，则会先静默取消当前拉取操作。
  • 若传入 options，则会在拉取前替换查询当前的选项。

参数

options?

QueryOptions<TQueryFnData, TError, TData, TQueryKey, never>

用于在拉取前替换查询当前选项的查询选项。当复用正在进行的拉取操作时，这些选项不会被应用。

fetchOptions?

FetchOptions<TQueryFnData>

设置 cancelRefetch 可先取消正在进行的拉取操作（仅当查询已拥有数据时）；设置 meta 可向查询的行为传递额外信息。

返回值

Promise<TData>

一个 Promise，成功时解析为拉取到的数据，失败时拒绝并返回拉取错误。若在查询已有数据时使用 revert 取消拉取，则该 Promise 将解析为恢复后的数据。

getObserversCount()

TypeScript
1getObserversCount(): number;

定义于：packages/query-core/src/query.ts:667

返回当前订阅该查询的观察者数量。

返回值

number

观察者数量。

示例

TypeScript
1if (query.getObserversCount() === 0) {2  // no component is currently watching this query3}

invalidate()

TypeScript
1invalidate(): void;

定义于：packages/query-core/src/query.ts:680

将查询标记为失效（除非它已被标记为失效）。这会更新 state.isInvalidated 并通知观察者，但本身不会触发重新拉取。

返回值

void

示例

TypeScript
1query.invalidate()

isActive()

TypeScript
1isActive(): boolean;

定义于：packages/query-core/src/query.ts:469

若查询至少有一个观察者，且该观察者的 enabled 不解析为 false，则返回 true。

返回值

boolean

若查询拥有启用的观察者，则返回 true。

isDisabled()

TypeScript
1isDisabled(): boolean;

定义于：packages/query-core/src/query.ts:484

若查询被禁用（即不会自动拉取），则返回 true。

  • 若查询拥有观察者，则当其中无一处于启用状态时（参见 isActive），该查询被视为禁用。
  • 若查询无任何观察者，则当其 queryFn 为 skipToken 或从未被拉取过时，该查询被视为禁用。

返回值

boolean

若查询被禁用，则返回 true。

isFetched()

TypeScript
1isFetched(): boolean;

定义于：packages/query-core/src/query.ts:497

若查询已被拉取（即至少一次成功解析出数据或错误），则返回 true。

返回值

boolean

若查询已被拉取，则返回 true。

isStale()

TypeScript
1isStale(): boolean;

定义于：packages/query-core/src/query.ts:533

若查询处于过期状态，则返回 true。

  • 若查询拥有观察者，则取决于任一观察者当前结果是否报告 isStale（该判断考虑了每个观察者自身的 staleTime 和 enabled 状态）。
  • 若查询无观察者，则当其无数据或已被标记为失效时，即视为过期。

返回值

boolean

若查询处于过期状态，则返回 true。

参见

Query#isStaleByTime

示例

TypeScript
1if (query.isStale()) {2  // refetch or otherwise treat the cached data as outdated3}

isStaleByTime()

TypeScript
1isStaleByTime(staleTime?: number | "static"): boolean;

定义于：packages/query-core/src/query.ts:561

若查询的数据相对于给定 staleTime（默认为 0）而言已过期，则返回 true。

  • 无数据的查询始终被视为过期。
  • staleTime: 'static' 永远不会被视为过期。
  • 已被标记为失效的查询始终被视为过期。
  • 其余情况下，过期性基于自 dataUpdatedAt 以来经过的时间。

参数

staleTime?

number | "static" = 0

数据被视为过期所需的时间（毫秒），或设为 'static' 表示永不将现有数据视为过期。无数据的查询无论如何均被视为过期。

返回值

boolean

若查询的数据已过期，则返回 true。

参见

Query#isStale

示例

TypeScript
1const isStale = query.isStaleByTime(60 * 1000)

isStatic()

TypeScript
1isStatic(): boolean;

定义于：packages/query-core/src/query.ts:506

若查询至少有一个配置了 staleTime: 'static' 的观察者（即该查询被视为永不处于过期状态），则返回 true。

返回值

boolean

若查询为静态，则返回 true。

reset()

TypeScript
1reset(): void;

定义于：packages/query-core/src/query.ts:459

将查询重置为其初始状态（即首次创建时的状态，例如任何 initialData），并首先销毁查询以取消任何正在进行的拉取操作。

返回值

void

setState()

TypeScript
1setState(state: Partial<QueryState<TData, TError>>): void;

定义于：packages/query-core/src/query.ts:411

将给定的部分状态直接合并进该查询的状态，并通知观察者。持久化插件和广播插件使用此方法恢复状态快照；开发者工具使用此方法允许用户手动触发加载/错误状态或编辑缓存数据。

参数

state

Partial<QueryState<TData, TError>>

要合并进查询状态的部分状态。

返回值

void

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

译自上游 59d11de