QueryObserver

定义位置：packages/query-core/src/queryObserver.ts:56

QueryObserver 会监听 QueryCache 中的单个查询，并根据其状态计算出一个 QueryObserverResult；每当底层查询（或观察者自身的选项）发生变化时，它都会重新计算并通知所有订阅者。它是各类框架适配器（例如 useQuery）构建其 Hook 的基础原语，但你也可以直接使用它，在任何框架之外观察和切换查询。

示例

1const observer = new QueryObserver(queryClient, {2  queryKey: ['posts'],3  queryFn: fetchPosts,4})5 6const unsubscribe = observer.subscribe((result) => {7  console.log(result.data)8})

继承自

• Subscribable<QueryObserverListener<TData, TError>>

被以下类型继承

• InfiniteQueryObserver

类型参数

TQueryFnData

TQueryFnData = unknown

TError

TError = DefaultError

TData

TData = TQueryFnData

TQueryData

TQueryData = TQueryFnData

TQueryKey

TQueryKey extends QueryKey = QueryKey

构造函数

构造函数

1new QueryObserver<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(client: QueryClient, options: QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>): QueryObserver<TQueryFnData, TError, TData, TQueryData, TQueryKey>;

定义位置：packages/query-core/src/queryObserver.ts:86

参数

client

QueryClient

options

QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>

返回值

QueryObserver<TQueryFnData, TError, TData, TQueryData, TQueryKey>

重写自

1Subscribable<QueryObserverListener<TData, TError>>.constructor

属性

options

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

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

方法

destroy()

1destroy(): void;

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

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

返回值

void

fetchOptimistic()

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

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

使用给定选项拉取一个查询，该操作不会影响当前观察者自身所跟踪的查询或结果，并返回一个 Promise，该 Promise 将以该拉取操作对应的 QueryObserverResult 作为解析值。这在预取另一观察者（例如即将导航到的查询）所需数据时非常有用。

参数

options

QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>

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

返回值

Promise<QueryObserverResult<TData, TError>>

一个 Promise，其解析值为所拉取查询的结果。

示例

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

getCurrentQuery()

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

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

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

返回值

Query<TQueryFnData, TError, TQueryData, TQueryKey>

被监听的查询。

getCurrentResult()

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

定义位置：packages/query-core/src/queryObserver.ts:330

返回被监听查询最近一次计算出的 QueryObserverResult。这是一个瞬时读取操作；若需在更新发生时实时获知，请改为订阅该观察者（通过其继承而来的 subscribe 方法）。

返回值

QueryObserverResult<TData, TError>

观察者的最新结果。

示例

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

getOptimisticResult()

1getOptimisticResult(options: DefaultedQueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>): QueryObserverResult<TData, TError>;

定义位置：packages/query-core/src/queryObserver.ts:281

立即基于给定（已默认化）的选项计算该观察者当前会生成的结果，若底层 Query 尚未创建则先构建之，且不等待订阅回调触发。框架适配器（例如 useQuery）会在每次渲染时调用此方法，以便同步获得返回值，早于 setOptions 触发实际拉取。

参数

options

DefaultedQueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>

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

返回值

QueryObserverResult<TData, TError>

对应选项所生成的结果。

hasListeners()

1hasListeners(): boolean;

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

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

返回值

boolean

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

继承自

1Subscribable.hasListeners

refetch()

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，其解析值为重新拉取完成后的结果。

示例

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

setOptions()

1setOptions(options: QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>): void;

定义位置：packages/query-core/src/queryObserver.ts:189

更新观察者的选项。这将重新解析当前被监听的查询（若 queryKey 发生变化，则可能切换至另一个查询），并在观察者拥有订阅者且新选项要求拉取时触发拉取，重新计算当前结果，并按需重新调度过期与重新拉取间隔定时器。

参数

options

QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>

新的观察者选项。在应用前会先通过 QueryClient#defaultQueryOptions 进行默认化。

返回值

void

抛出异常

若 enabled 既不是布尔值也不是函数，则抛出异常。

示例

1observer.setOptions({ queryKey: ['posts', 1], queryFn: () => fetchPost(1) })2// later: switch to a different query, reusing the same observer3observer.setOptions({ queryKey: ['posts', 2], queryFn: () => fetchPost(2) })

shouldFetchOnReconnect()

1shouldFetchOnReconnect(): boolean;

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

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

返回值

boolean

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

shouldFetchOnWindowFocus()

1shouldFetchOnWindowFocus(): boolean;

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

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

返回值

boolean

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

subscribe()

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

定义位置：packages/query-core/src/subscribable.ts:28

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

参数

listener

QueryObserverListener

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

返回值

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

() => void

示例

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

继承自

1Subscribable.subscribe

trackProp()

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 的代理间接调用；此处直接暴露，供那些自行追踪属性访问（例如通过其自身的响应式系统）而非依赖代理的框架适配器使用。

参数

key

| "error" | "data" | "isError" | "isPending" | "isLoading" | "isLoadingError" | "isRefetchError" | "isSuccess" | "isPlaceholderData" | "status" | "dataUpdatedAt" | "errorUpdatedAt" | "failureCount" | "failureReason" | "errorUpdateCount" | "isFetched" | "isFetchedAfterMount" | "isFetching" | "isInitialLoading" | "isPaused" | "isRefetching" | "isStale" | "isEnabled" | "refetch" | "fetchStatus"

被读取的属性名称。

返回值

void

trackResult()

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（及可选的 onPropTracked 回调）记录哪些属性被读取。当 notifyOnChangeProps 未设置时，框架适配器使用此方法实现其默认行为：“仅在你实际读取的属性发生变化时才重新渲染”。

参数

result

QueryObserverResult<TData, TError>

待包裹的结果。

onPropTracked?

(key: | "error" | "data" | "isError" | "isPending" | "isLoading" | "isLoadingError" | "isRefetchError" | "isSuccess" | "isPlaceholderData" | "status" | "dataUpdatedAt" | "errorUpdatedAt" | "failureCount" | "failureReason" | "errorUpdateCount" | "isFetched" | "isFetchedAfterMount" | "isFetching" | "isInitialLoading" | "isPaused" | "isRefetching" | "isStale" | "isEnabled" | "refetch" | "fetchStatus") => void

每次读取属性时，以该属性名称作为参数调用。

返回值

QueryObserverResult<TData, TError>

一个追踪属性读取行为的 result 代理。

updateResult()

1updateResult(): void;

定义位置：packages/query-core/src/queryObserver.ts:765

基于当前查询/选项重新计算并存储当前结果，并在结果发生变化时通知监听器。框架适配器在完成订阅后立即调用此方法，以确保不会遗漏从创建观察者到订阅之间发生的任何查询更新。

返回值

void