QueryOptions

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

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

查询自身的选项 —— 包括其 queryKey、queryFn、重试次数、gcTime、initialData、meta 等 —— 由观察者和用于拉取查询的 QueryClient 方法共享。

类型参数

TQueryFnData

TQueryFnData = unknown

TError

TError = DefaultError

TData

TData = 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?`	`TData` \| (() => `TData` \| `undefined`)	`undefined`	若设置该值，它将作为查询缓存的初始数据（前提是该查询尚未创建或缓存）。若设为函数，该函数将在共享/根查询初始化期间仅调用一次，且需同步返回初始数据。默认情况下，初始数据被视为过期，除非已设置 `staleTime`。`initialData` 会被持久化到缓存中。
`initialDataUpdatedAt?`	`number` \| (() => `number` \| `undefined`)	`undefined`	若设置该值，它将作为 `initialData` 本身最近一次更新的时间（毫秒）。
`maxPages?`	`number`	`undefined`	无限查询的数据中最多存储的页数。
`meta?`	`Record`<`string`, `unknown`>	`undefined`	存储在每个查询上的额外负载。可利用此属性传递可在其他位置使用的附加信息。
`networkMode?`	`"online"` \| `"always"` \| `"offlineFirst"`	`'online'`	控制查询是否允许基于当前网络连接状态运行。详见网络模式。
`persister?`	(`queryFn`: (`context`: `QueryFunctionContext`<`NoInfer`<`TQueryKey`>, `TPageParam`>) => `TQueryFnData` \| `Promise`<`TQueryFnData`>, `context`: `object`, `query`: `Query`) => `TQueryFnData` \| `Promise`<`TQueryFnData`>	`undefined`	此选项可用于将查询结果持久化到外部存储，从而绕过实际调用 `queryFn` 的需要。适用于跨服务端/客户端边界持久化查询数据等场景。
`queryFn?`	\| ((`context`: `QueryFunctionContext`<`TQueryKey`, `TPageParam`>) => `TQueryFnData` \| `Promise`<`TQueryFnData`>) \| typeof `skipToken`	`undefined`	查询用于请求数据的函数。必需，除非已通过 `queryClient.setQueryDefaults` 或 `queryClient.setDefaultOptions` 设置了默认查询函数。接收一个 QueryFunctionContext。必须返回一个 Promise，该 Promise 要么解析出数据，要么抛出错误。数据不能为 `undefined`。
`queryHash?`	`string`	`undefined`	`queryKey` 的哈希形式，使用 `queryKeyHashFn`（或默认哈希函数）计算得出。内部用作实际缓存键。
`queryKey?`	`TQueryKey`	`undefined`	此查询所用的查询键。查询键将被哈希为稳定哈希值。详见查询键。只要 `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 秒。
`structuralSharing?`	`boolean` \| ((`oldData`: `unknown`, `newData`: `unknown`) => `unknown`)	`true`	设为 `false` 可禁用查询结果之间的结构共享。设为一个接受旧数据和新数据并返回同类型已解析数据的函数，可实现自定义结构共享逻辑。