译零 TransZero · TanStack Query 中文文档

主站

FetchQueryOptions

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

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

已弃用

继承自

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

被以下类型扩展

EnsureQueryDataOptions

类型参数

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` 上次更新的时间戳（毫秒）。
~~`initialPageParam?`~~	`undefined`	`undefined`	此处不允许设置，因为 `initialPageParam` 仅适用于无限查询（infinite queries）。
~~`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 秒。
~~`staleTime?`~~	\| `number` \| `"static"` \| ((`query`: `Query`<`TQueryFnData`, `TError`, `TData`, `TQueryKey`>) => `number` \| `"static"`)	`undefined`	数据被视为过期的时间（毫秒）。若数据仍为新鲜状态，则直接从缓存返回。
~~`structuralSharing?`~~	`boolean` \| ((`oldData`: `unknown`, `newData`: `unknown`) => `unknown`)	`true`	设为 `false` 可禁用查询结果间的结构共享；设为一个接受旧数据与新数据并返回同类型解析后数据的函数，可实现自定义结构共享逻辑。