InfiniteQueryObserver

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

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

InfiniteQueryObserver InfiniteQueryObserver 继承自 QueryObserver，用于观察和切换无限查询（infinite queries）。它在基础 QueryObserverResult 上扩展了无限查询专属的字段与方法，例如 hasNextPage 和 fetchNextPage，是框架适配器（如 useInfiniteQuery）构建其 Hook 的底层原语。

示例

TypeScript

1const observer = new InfiniteQueryObserver(queryClient, {2  queryKey: ['projects'],3  queryFn: ({ pageParam }) => fetchProjects(pageParam),4  initialPageParam: 0,5  getNextPageParam: (lastPage) => lastPage.nextCursor,6})7 8const unsubscribe = observer.subscribe((result) => console.log(result))

继承自

QueryObserver<TQueryFnData, TError, TData, InfiniteData<TQueryFnData, TPageParam>, TQueryKey>

类型参数

TQueryFnData

TQueryFnData = unknown

TError

TError = DefaultError

TData

TData = InfiniteData<TQueryFnData>

TQueryKey

TQueryKey extends QueryKey = QueryKey

TPageParam

TPageParam = unknown

构造函数

TypeScript

1new InfiniteQueryObserver<TQueryFnData = unknown, TError = Error, TData = InfiniteData<TQueryFnData, unknown>, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = unknown>(client: QueryClient, options: InfiniteQueryObserverOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>): InfiniteQueryObserver<TQueryFnData, TError, TData, TQueryKey, TPageParam>;

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

参数

client

QueryClient

options

InfiniteQueryObserverOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>

返回值

InfiniteQueryObserver<TQueryFnData, TError, TData, TQueryKey, TPageParam>

重写自

QueryObserver.constructor

属性

getCurrentResult

TypeScript

1getCurrentResult: ReplaceReturnType<() => QueryObserverResult<TData, TError>, InfiniteQueryObserverResult<TData, TError>>;

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

返回被观察查询最近计算出的 QueryObserverResult。这是某一时刻的快照读取；若需在更新发生时实时获知，请改为订阅该观察者（通过其继承的 subscribe 方法）。

返回值

观察者的最新结果。

示例

TypeScript

1const result = observer.getCurrentResult()2console.log(result.status, result.data)

重写自

TypeScript

1QueryObserver.getCurrentResult

options

TypeScript

1options: QueryObserverOptions<TQueryFnData, TError, TData, InfiniteData<TQueryFnData, TPageParam>, TQueryKey>;

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

继承自

QueryObserver.options

TypeScript

1subscribe: (listener: InfiniteQueryObserverListener) => () => void;

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

注册一个监听器，在该对象通知每次更新时调用。返回一个用于移除该监听器的函数——调用它即可停止监听。基类自身永远不会主动丢弃监听器，但某些子类会在 destroy() 中清空全部监听器。

参数

listener

InfiniteQueryObserverListener

每次更新时被调用，接收子类传递给其订阅者的任意参数。

返回值

一个用于移除监听器的函数。

() => void

示例

TypeScript

1const unsubscribe = subscribable.subscribe(() => {2  // react to the update3})4 5unsubscribe()

重写自

TypeScript

1QueryObserver.subscribe

方法

destroy()

TypeScript

1destroy(): void;

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

停止观察当前查询：清除所有监听器、取消过期及重新拉取（refetch）定时器，并将该观察者从其所观察的查询中移除。

返回值

void

继承自

QueryObserver.destroy

fetchNextPage()

TypeScript

1fetchNextPage(options?: FetchNextPageOptions): Promise<InfiniteQueryObserverResult<TData, TError>>;

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

拉取无限查询的下一页，并返回一个 Promise，该 Promise 在拉取成功后解析为对应的 InfiniteQueryObserverResult。本次拉取所用的页参数（page param）由 getNextPageParam 决定，该函数接收当前页数据/页参数，并且其返回值也决定了 hasNextPage。

参数

options?

FetchNextPageOptions

将 cancelRefetch 设为 false 可在拉取进行中忽略本次调用；将 throwOnError 设为 true 可在拉取失败时拒绝该 Promise。

返回值

Promise<InfiniteQueryObserverResult<TData, TError>>

一个 Promise，将在下一页拉取完成后解析为对应结果。启用 cancelRefetch: false 后，会复用正在运行的拉取任务，因此下一页可能不会被实际拉取。

参见

InfiniteQueryObserver#fetchPreviousPage

示例

TypeScript

1const { hasNextPage } = observer.getCurrentResult()2 3if (hasNextPage) {4  await observer.fetchNextPage()5}

fetchOptimistic()

TypeScript

1fetchOptimistic(options: QueryObserverOptions<TQueryFnData, TError, TData, InfiniteData<TQueryFnData, TPageParam>, TQueryKey>): Promise<QueryObserverResult<TData, TError>>;

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

使用给定选项拉取一个查询，但不影响本观察者自身跟踪的查询或结果，并返回一个 Promise，该 Promise 解析为此次拉取的 QueryObserverResult。这适用于预先拉取另一观察者（例如即将导航到的查询）所需的数据。

参数

options

QueryObserverOptions<TQueryFnData, TError, TData, InfiniteData<TQueryFnData, TPageParam>, TQueryKey>

待拉取查询的观察者选项。

返回值

Promise<QueryObserverResult<TData, TError>>

一个 Promise，将在拉取完成后解析为对应结果。

示例

TypeScript

1const result = await observer.fetchOptimistic({2  queryKey: ['posts', 2],3  queryFn: () => fetchPost(2),4})5console.log(result.data)

继承自

QueryObserver.fetchOptimistic

fetchPreviousPage()

TypeScript

1fetchPreviousPage(options?: FetchPreviousPageOptions): Promise<InfiniteQueryObserverResult<TData, TError>>;

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

拉取无限查询的上一页，并返回一个 Promise，该 Promise 在拉取成功后解析为对应的 InfiniteQueryObserverResult。本次拉取所用的页参数（page param）由 getPreviousPageParam 决定，该函数接收当前页数据/页参数，并且其返回值也决定了 hasPreviousPage。

参数

options?

FetchPreviousPageOptions

将 cancelRefetch 设为 false 可在拉取进行中忽略本次调用；将 throwOnError 设为 true 可在拉取失败时拒绝该 Promise。

返回值

Promise<InfiniteQueryObserverResult<TData, TError>>

一个 Promise，将在上一页拉取完成后解析为对应结果。启用 cancelRefetch: false 后，会复用正在运行的拉取任务，因此上一页可能不会被实际拉取。

参见

InfiniteQueryObserver#fetchNextPage

示例

TypeScript

1const { hasPreviousPage } = observer.getCurrentResult()2 3if (hasPreviousPage) {4  await observer.fetchPreviousPage()5}

getCurrentQuery()

TypeScript

1getCurrentQuery(): Query<TQueryFnData, TError, InfiniteData<TQueryFnData, TPageParam>, TQueryKey>;

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

返回该观察者当前正在观察的 Query 实例。

返回值

Query<TQueryFnData, TError, InfiniteData<TQueryFnData, TPageParam>, TQueryKey>

被观察的查询。

继承自

QueryObserver.getCurrentQuery

getOptimisticResult()

TypeScript

1getOptimisticResult(options: DefaultedInfiniteQueryObserverOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>): InfiniteQueryObserverResult<TData, TError>;

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

InfiniteQueryObserver 对应 QueryObserver#getOptimisticResult QueryObserver.md#getoptimisticresult 的实现，先将选项标记为无限查询再委托调用。框架适配器（如 useInfiniteQuery）在订阅前调用此方法，以同步计算当前 InfiniteQueryObserverResult。

参数

options

DefaultedInfiniteQueryObserverOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>

用于计算结果的已默认化的无限查询观察者选项。

返回值

InfiniteQueryObserverResult<TData, TError>

对应选项的结果。

重写自

QueryObserver.getOptimisticResult

hasListeners()

TypeScript

1hasListeners(): boolean;

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

至少存在一个已注册监听器时返回 true；所有监听器均已注销后返回 false。

返回值

boolean

至少存在一个监听器时返回 true。

继承自

QueryObserver.hasListeners

refetch()

TypeScript

1refetch(options?: RefetchOptions): Promise<QueryObserverResult<TData, TError>>;

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

重新拉取被观察的查询，并返回一个 Promise，该 Promise 解析为重新拉取后的 QueryObserverResult。

参数

options?

RefetchOptions = {}

将 cancelRefetch 设为 false 可保留正在运行的拉取任务而非取消它；将 throwOnError 设为 true 可在重新拉取失败时拒绝该 Promise。

返回值

Promise<QueryObserverResult<TData, TError>>

一个 Promise，将在重新拉取完成后解析为对应结果。

示例

TypeScript

1const result = await observer.refetch({ cancelRefetch: false })2console.log(result.data)

继承自

QueryObserver.refetch

setOptions()

TypeScript

1setOptions(options: InfiniteQueryObserverOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>): void;

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

更新观察者的选项。行为与 QueryObserver.setOptions 相同，额外在委托至基类实现前将选项标记为属于无限查询。

参数

options

InfiniteQueryObserverOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>

新的无限查询观察者选项。

返回值

void

重写自

QueryObserver.setOptions

shouldFetchOnReconnect()

TypeScript

1shouldFetchOnReconnect(): boolean;

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

返回被观察查询当前是否处于过期状态，且是否已通过 refetchOnReconnect 选项配置为在网络重连时重新拉取。

返回值

boolean

若观察者应在重连时重新拉取查询，则返回 true。

继承自

QueryObserver.shouldFetchOnReconnect

shouldFetchOnWindowFocus()

TypeScript

1shouldFetchOnWindowFocus(): boolean;

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

返回被观察查询当前是否处于过期状态，且是否已通过 refetchOnWindowFocus 选项配置为在窗口获得焦点时重新拉取。

返回值

boolean

若观察者应在窗口获得焦点时重新拉取查询，则返回 true。

继承自

QueryObserver.shouldFetchOnWindowFocus

trackProp()

TypeScript

1trackProp(key: 2  | "error"3  | "data"4  | "isError"5  | "isPending"6  | "isLoading"7  | "isLoadingError"8  | "isRefetchError"9  | "isSuccess"10  | "isPlaceholderData"11  | "status"12  | "dataUpdatedAt"13  | "errorUpdatedAt"14  | "failureCount"15  | "failureReason"16  | "errorUpdateCount"17  | "isFetched"18  | "isFetchedAfterMount"19  | "isFetching"20  | "isInitialLoading"21  | "isPaused"22  | "isRefetching"23  | "isStale"24  | "isEnabled"25  | "refetch"26  | "fetchStatus"): void;

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

记录指定 QueryObserverResult 属性已被读取，以便后续更新仅在被追踪属性实际变更时才通知该观察者。通常通过 [QueryObserver#trackResult](QueryObserver.md#trackresult) 的代理间接调用；直接暴露此方法供那些自行追踪属性访问（例如通过其自身的响应式系统）而非依赖代理的适配器使用。

参数

key

被读取的属性名称。

返回值

void

继承自

QueryObserver.trackProp

trackResult()

TypeScript

1trackResult(result: QueryObserverResult<TData, TError>, onPropTracked?: (key: 2  | "error"3  | "data"4  | "isError"5  | "isPending"6  | "isLoading"7  | "isLoadingError"8  | "isRefetchError"9  | "isSuccess"10  | "isPlaceholderData"11  | "status"12  | "dataUpdatedAt"13  | "errorUpdatedAt"14  | "failureCount"15  | "failureReason"16  | "errorUpdateCount"17  | "isFetched"18  | "isFetchedAfterMount"19  | "isFetching"20  | "isInitialLoading"21  | "isPaused"22  | "isRefetching"23  | "isStale"24  | "isEnabled"25  | "refetch"26| "fetchStatus") => void): QueryObserverResult<TData, TError>;

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

将一个 QueryObserverResult 包裹在 Proxy 中，通过 [QueryObserver#trackProp](QueryObserver.md#trackprop)（以及可选的 onPropTracked 回调）记录哪些属性被读取。当 notifyOnChangeProps 未设置时，框架适配器使用此方法实现其默认行为：“仅在你实际读取的属性发生变化时才重新渲染”。