译零 TransZero · TanStack Query 中文文档
主站

CreateInfiniteQueryOptions

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

定义于：packages/angular-query-experimental/src/types.ts:126

injectInfiniteQuery 所接受的选项。与 CreateBaseQueryOptions 相同，但不包含 suspense — angular-query-experimental 不支持该选项，而 react-query 支持 — 并扩展了 @tanstack/query-core 中的 InfiniteQueryObserverOptions，以支持无限查询（infinite query）特有的选项（如 getNextPageParam、initialPageParam 等）。

继承自

类型参数

TQueryFnData

TQueryFnData = unknown

单页数据的类型，即你的 queryFn 所解析出的数据类型。

TError

TError = DefaultError

你的 queryFn 可能抛出的错误类型。

TData

TData = TQueryFnData

data 经 select 处理后最终呈现的类型。此处默认为 TQueryFnData；但 injectInfiniteQuery 本身将其默认为 InfiniteData<TQueryFnData> — 即未使用 select 时 data 实际具有的形状。

TQueryKey

TQueryKey extends QueryKey = QueryKey

你的 queryKey 的类型。

TPageParam

TPageParam = unknown

传递给 queryFn 以拉取指定页面的参数类型。

属性 类型 默认值 描述
enabled? | false | true | ((query: Query<TQueryFnData, TError, InfiniteData<TQueryFnData, TPageParam>, TQueryKey>) => boolean) true 将此设为 false 或返回 false 的函数，可禁用查询挂载或查询键变更时的自动重新拉取。要手动重新拉取查询，请使用 refetch 方法（由 useQuery 实例返回）。接受布尔值或返回布尔值的函数。
gcTime? number undefined 未使用/非活跃缓存数据在内存中保留的毫秒数。当某个查询的缓存变为未使用或非活跃状态后，该缓存数据将在该持续时间后被垃圾回收。若指定了多个垃圾回收时间，则采用最长的那个。设为 Infinity 将禁用垃圾回收。默认为 5 * 60 * 1000（5 分钟），服务端渲染（SSR）期间则为 Infinity。注意：受 setTimeout 的 32 位有符号整数延时限制，最大允许时间为约 24 天——参见 timeoutManager.setTimeoutProvider 获取变通方案。
getNextPageParam (lastPage: TQueryFnData, allPages: TQueryFnData[], lastPageParam: TPageParam, allPageParams: TPageParam[]) => TPageParam | null | undefined undefined 可设置此函数以自动获取无限查询的下一页游标。其结果也将用于确定 hasNextPage 的值。
getPreviousPageParam? (firstPage: TQueryFnData, allPages: TQueryFnData[], firstPageParam: TPageParam, allPageParams: TPageParam[]) => TPageParam | null | undefined undefined 可设置此函数以自动获取无限查询的上一页游标。其结果也将用于确定 hasPreviousPage 的值。
initialData? | InfiniteData<TQueryFnData, TPageParam> | (() => | InfiniteData<TQueryFnData, TPageParam> | undefined) undefined 若设置此值，它将作为查询缓存的初始数据（前提是该查询尚未创建或缓存）。若设为函数，该函数将在共享/根查询初始化期间仅执行一次，且需同步返回初始数据。默认情况下，初始数据被视为过期，除非已设置 staleTime。initialData 会被持久化到缓存中。
initialDataUpdatedAt? number | (() => number | undefined) undefined 若设置此值，它将作为 initialData 本身最后更新的时间（毫秒）。
initialPageParam TPageParam undefined 当无限查询尚无任何页时，起始页码参数。它将作为 queryFn 的 pageParam 参数传入第一页；后续每一页则使用 getNextPageParam 或 getPreviousPageParam 返回的值。该参数仅在查询尚无页时生效：一旦存在第一页，重新拉取将从该页自身的参数开始。
maxPages? number undefined 无限查询的数据中最多存储的页数。
meta? Record<string, unknown> undefined 存储在每个查询上的额外负载。可利用此属性传递可在其他位置使用的附加信息。
networkMode? "online" | "always" | "offlineFirst" 'online' 控制查询是否允许基于当前网络连接状态运行。详见 网络模式。
notifyOnChangeProps? | ( | "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" | "fetchNextPage" | "fetchPreviousPage" | "hasNextPage" | "hasPreviousPage" | "isFetchNextPageError" | "isFetchingNextPage" | "isFetchPreviousPageError" | "isFetchingPreviousPage")[] | "all" | (() => | "all" | ( | "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" | "fetchNextPage" | "fetchPreviousPage" | "hasNextPage" | "hasPreviousPage" | "isFetchNextPageError" | "isFetchingNextPage" | "isFetchPreviousPageError" | "isFetchingPreviousPage")[] | undefined) undefined 若设置此值，组件仅在所列属性发生变更时重新渲染。设为 ['data', 'error'] 时，组件仅在 data 或 error 属性变更时重新渲染。设为 'all' 时，组件将在任意查询更新时重新渲染。设为函数时，该函数将被执行以计算属性列表。默认为 undefined，此时会自动追踪属性访问，并仅在被追踪的属性之一发生变化时重新渲染。
persister? (queryFn: (context: QueryFunctionContext<NoInfer<TQueryKey>, TPageParam>) => TQueryFnData | Promise<TQueryFnData>, context: object, query: Query) => TQueryFnData | Promise<TQueryFnData> undefined 此选项可用于将查询结果持久化到外部存储，从而绕过实际调用 queryFn 的需要。适用于跨服务端/客户端边界持久化查询数据等场景。
placeholderData? | InfiniteData<TQueryFnData, TPageParam> | ((previousData: | InfiniteData<TQueryFnData, TPageParam> | undefined, previousQuery: | Query<InfiniteData<TQueryFnData, TPageParam>, TError, InfiniteData<TQueryFnData, TPageParam>, TQueryKey> | undefined) => | InfiniteData<TQueryFnData, TPageParam> | undefined) undefined 若设置此值，它将作为该特定查询观察者在查询仍处于 loading 数据状态且未提供 initialData 时的占位数据。
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 此查询所用的查询键。查询键将被哈希为稳定哈希值。更多信息请参阅 查询键。只要 enabled 未设为 false，该键变更时查询将自动更新。
queryKeyHashFn? (queryKey: TQueryKey) => string undefined 若指定此函数，将使用它对 queryKey 进行哈希并生成字符串。
refetchInterval? | number | false | ((query: Query<TQueryFnData, TError, InfiniteData<TQueryFnData, TPageParam>, TQueryKey>) => number | false | undefined) false 若设为数字，查询将以该毫秒频率持续重新拉取。若设为函数，该函数将使用最新数据和查询来计算频率。
refetchIntervalInBackground? boolean false 若设为 true，查询将在标签页/窗口处于后台时继续重新拉取。
refetchOnMount? | boolean | "always" | ((query: Query<TQueryFnData, TError, InfiniteData<TQueryFnData, TPageParam>, TQueryKey>) => boolean | "always") true 若设为 true，查询在挂载时若数据过期则重新拉取。若设为 false，将禁用额外查询实例触发后台重新拉取。若设为 'always'，查询将在挂载时始终重新拉取（除非使用 staleTime: 'static'）。若设为函数，该函数将使用最新数据和查询来计算该值。
refetchOnReconnect? | boolean | "always" | ((query: Query<TQueryFnData, TError, InfiniteData<TQueryFnData, TPageParam>, TQueryKey>) => boolean | "always") undefined 若设为 true，查询在网络重连时若数据过期则重新拉取。若设为 false，查询在网络重连时不会重新拉取。若设为 'always'，查询将在网络重连时始终重新拉取（除非使用 staleTime: 'static'）。若设为函数，该函数将使用最新数据和查询来计算该值。默认为 true，除非 networkMode 为 'always'。
refetchOnWindowFocus? | boolean | "always" | ((query: Query<TQueryFnData, TError, InfiniteData<TQueryFnData, TPageParam>, TQueryKey>) => boolean | "always") true 若设为 true，查询在窗口获得焦点时若数据过期则重新拉取。若设为 false，查询在窗口获得焦点时不会重新拉取。若设为 'always'，查询将在窗口获得焦点时始终重新拉取（除非使用 staleTime: 'static'）。若设为函数，该函数将使用最新数据和查询来计算该值。
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 整数和实际错误对象，并返回下次尝试前应延迟的毫秒数。类似 attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000) 的函数应用指数退避策略；类似 attempt => attempt * 1000 的函数应用线性退避策略。默认为一个应用指数退避的函数，上限为 30 秒。
retryOnMount? | false | true | ((query: Query<TQueryFnData, TError, InfiniteData<TQueryFnData, TPageParam>, TQueryKey>) => boolean) true 若设为 false，包含错误的查询在挂载时将不会重试。若设为函数，该函数将使用查询来计算该值。
select? (data: InfiniteData) => TData undefined 此选项可用于转换或选取查询函数返回数据的一部分。它会影响返回的 data 值，但不影响存储在查询缓存中的内容。select 函数仅在 data 发生变化或 select 函数自身引用发生变化时执行。为优化性能，请对函数进行记忆化处理，使其引用在多次调用中保持稳定。
staleTime? | number | "static" | ((query: Query<TQueryFnData, TError, InfiniteData<TQueryFnData, TPageParam>, TQueryKey>) => number | "static") 0 数据被视为过期前的毫秒数。若设为 Infinity，数据将永远不会被视为过期。若设为 'static'，数据将永远不会被视为过期。若设为函数，该函数将使用查询来计算 staleTime。
structuralSharing? boolean | ((oldData: unknown, newData: unknown) => unknown) true 将此设为 false 可禁用查询结果之间的结构共享。将此设为一个接收旧数据和新数据并返回同类型已解析数据的函数，可实现自定义结构共享逻辑。
throwOnError? | false | true | ((error: TError, query: Query<TQueryFnData, TError, InfiniteData<TQueryFnData, TPageParam>, TQueryKey>) => boolean) false 是否应抛出错误而非设置 error 属性。若设为 true 或 suspense 为 true，所有错误都将抛出至错误边界。若设为 false 且 suspense 为 false，错误将作为状态返回。若设为函数，该函数将接收错误和查询，并应返回一个布尔值，指示是否在错误边界中显示错误（true）或将错误作为状态返回（false）。

本页为 TanStack Query 文档（Angular 版）的非官方中文翻译，原文由上游团队维护，遵循 MIT 许可。 译文如有偏差，以英文原文为准。

译自上游 59d11de