QueryExecuteOptions

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

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

queryClient.query 的选项：即该查询的 QueryOptions，外加一个 staleTime，用于决定是否返回缓存数据而非发起拉取；以及一个 select，仅对调用所解析的值进行转换。

继承自

WithRequired<QueryOptions<TQueryFnData, TError, TQueryData, TQueryKey, TPageParam>, "queryKey">

类型参数

TQueryFnData

TQueryFnData = unknown

TError

TError = DefaultError

TData

TData = TQueryFnData

TQueryData

TQueryData = TQueryFnData

TQueryKey

TQueryKey extends QueryKey = QueryKey

TPageParam

TPageParam = never

属性

属性	类型	默认值	描述
`gcTime?`	`number`	`undefined`	未使用/非活跃缓存数据在内存中保留的时间（毫秒）。当某个查询的缓存变为未使用或非活跃状态后，该缓存数据将在该时长后被垃圾回收。当指定了不同的垃圾回收时间时，将采用最长的那个。设为 `Infinity` 将禁用垃圾回收。默认为 `5 * 60 * 1000`（5 分钟），服务端渲染（SSR）期间则为 `Infinity`。注意：最大允许时间为约 24 天，这是由 `setTimeout` 的 32 位有符号整数延迟限制所致——参见 `timeoutManager.setTimeoutProvider` 获取变通方案。
`initialData?`	`TQueryData` \| (() => `TQueryData` \| `undefined`)	`undefined`	若设置此值，则将其用作查询缓存的初始数据（前提是该查询尚未创建或缓存）。若设为函数，则该函数将在共享/根查询初始化期间仅调用一次，且需同步返回初始数据。默认情况下，初始数据被视为过期，除非已设置 `staleTime`。`initialData` 会被持久化到缓存中。
`initialDataUpdatedAt?`	`number` \| (() => `number` \| `undefined`)	`undefined`	若设置此值，则将其用作 `initialData` 本身最近一次更新的时间（毫秒）。
`initialPageParam?`	`undefined`	`undefined`	此处不允许设置，因为 `initialPageParam` 仅适用于无限查询。
`maxPages?`	`number`	`undefined`	无限查询的数据中最多存储的页数。
`meta?`	`Record`<`string`, `unknown`>	`undefined`	存储在每个查询上的额外负载。可利用此属性传递可在其他位置使用的附加信息。
`networkMode?`	`"online"` \| `"always"` \| `"offlineFirst"`	`'online'`	控制查询是否允许基于当前网络连接状态运行。详见 Network Mode。
`persister?`	(`queryFn`: (`context`: `QueryFunctionContext`<`NoInfer`<`TQueryKey`>, `TPageParam`>) => `TQueryFnData` \| `Promise`<`TQueryFnData`>, `context`: `object`, `query`: `Query`) => `TQueryFnData` \| `Promise`<`TQueryFnData`>	`undefined`	此选项可用于将查询结果持久化至外部存储，从而绕过实际调用 `queryFn` 的需要。适用于跨服务端/客户端边界持久化查询数据等场景。
`queryFn?`	\| typeof `skipToken` \| ((`context`: `QueryFunctionContext`<`TQueryKey`, `TPageParam`>) => `TQueryFnData` \| `Promise`<`TQueryFnData`>)	`undefined`	查询用于请求数据的函数。除非已通过 `queryClient.setQueryDefaults` 或 `queryClient.setDefaultOptions` 设置了默认查询函数，否则此字段为必需项。接收一个 QueryFunctionContext。必须返回一个 Promise，该 Promise 要么解析出数据，要么抛出错误。数据不能为 `undefined`。
`queryHash?`	`string`	`undefined`	`queryKey` 的哈希形式，使用 `queryKeyHashFn`（或默认哈希函数）计算得出。内部用作实际缓存键。
`queryKey`	`TQueryKey` & `object`	`undefined`	此查询所用的查询键。查询键将被哈希为稳定哈希值。更多信息请参阅 Query Keys。只要 `enabled` 未设为 `false`，该键一旦变更，查询便会自动更新。
`queryKeyHashFn?`	(`queryKey`: `TQueryKey`) => `string`	`undefined`	若指定此函数，则使用它对 `queryKey` 进行哈希并生成字符串。
`retry?`	\| `number` \| `false` \| `true` \| ((`failureCount`: `number`, `error`: `TError`) => `boolean`)	`undefined`	若为 `false`，失败的查询默认不再重试；若为 `true`，失败的查询将无限重试；若设为整数（例如 3），失败的查询将重试直至失败次数达到该数值；若设为函数 `(failureCount, error) => boolean`，失败的查询将重试直至该函数返回 false。客户端默认为 `3`，服务端默认为 `0`。
`retryDelay?`	`number` \| ((`failureCount`: `number`, `error`: `TError`) => `number`)	`undefined`	此函数接收一个 `retryAttempt` 整数和实际 Error，并返回下次尝试前应延迟的毫秒数。类似 `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` 的函数应用指数退避；类似 `attempt => attempt * 1000` 的函数应用线性退避。默认为一个应用指数退避的函数，上限为 30 秒。
`select?`	(`data`: `TQueryData`) => `TData`	`undefined`	此选项可用于转换或选取查询函数返回数据的一部分。它影响该调用所解析的值，但不影响存储在查询缓存中的内容。
`staleTime?`	\| `number` \| `"static"` \| ((`query`: `Query`<`TQueryFnData`, `TError`, `TQueryData`, `TQueryKey`>) => `number` \| `"static"`)	`undefined`	数据被视为过期前的毫秒数。若数据为新鲜状态，则直接从缓存返回。
`structuralSharing?`	`boolean` \| ((`oldData`: `unknown`, `newData`: `unknown`) => `unknown`)	`true`	设为 `false` 可禁用查询结果之间的结构共享。设为一个接受旧数据和新数据并返回同类型已解析数据的函数，可实现自定义结构共享逻辑。