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

injectInfiniteQuery

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

概述

TypeScript
1function injectInfiniteQuery<TQueryFnData, TError = Error, TData = InfiniteData<TQueryFnData, unknown>, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = unknown>(injectInfiniteQueryFn: () => DefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, options?: InjectInfiniteQueryOptions): DefinedCreateInfiniteQueryResult<TData, TError>;2function injectInfiniteQuery<TQueryFnData, TError = Error, TData = InfiniteData<TQueryFnData, unknown>, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = unknown>(injectInfiniteQueryFn: () => UndefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, options?: InjectInfiniteQueryOptions): CreateInfiniteQueryResult<TData, TError>;3function injectInfiniteQuery<TQueryFnData, TError = Error, TData = InfiniteData<TQueryFnData, unknown>, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = unknown>(injectInfiniteQueryFn: () => CreateInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, options?: InjectInfiniteQueryOptions): CreateInfiniteQueryResult<TData, TError>;

另请参阅：参数 · 返回值

调用签名

TypeScript
1function injectInfiniteQuery<TQueryFnData, TError = Error, TData = InfiniteData<TQueryFnData, unknown>, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = unknown>(injectInfiniteQueryFn: () => DefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, options?: InjectInfiniteQueryOptions): DefinedCreateInfiniteQueryResult<TData, TError>;

定义于：packages/angular-query-experimental/src/inject-infinite-query.ts:87

injectInfiniteQuery 的选项与 injectQuery 完全相同，额外增加了 initialPageParam、getNextPageParam、getPreviousPageParam 和 maxPages。无限查询可增量式地向现有数据集“加载更多”数据，或实现“无限滚动”。

当 initialData 已知在 injectInfiniteQueryFn 返回的选项中被定义时，将选择此重载；因此生成的 data 信号永远不会是 undefined（除非某个 select 将 TData 更改为包含 undefined 的类型）。

类型参数

TQueryFnData

TQueryFnData

TError

TError = Error

TData

TData = InfiniteData<TQueryFnData, unknown>

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

TPageParam

TPageParam = unknown

参数

injectInfiniteQueryFn

() => DefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>

一个返回要使用的 DefinedInitialDataInfiniteOptions 的函数——即所有可传给 injectInfiniteQuery 的选项，且 initialData 已知已被定义。与 Angular 中的 computed 类似，该函数在响应式上下文中运行，因此其中读取的信号会驱动查询。

options?

InjectInfiniteQueryOptions

附加配置。

返回值

DefinedCreateInfiniteQueryResult<TData, TError>

与 injectQuery 返回的信号相同，额外增加了 fetchNextPage、fetchPreviousPage、hasNextPage、hasPreviousPage、isFetchingNextPage 和 isFetchingPreviousPage。只要 select 不将 TData 改为偏离其默认 InfiniteData<TQueryFnData> 形状的类型，也会添加 data().pages 和 data().pageParams。

备注

请注意，命令式拉取调用（例如 fetchNextPage）可能会干扰默认的重新拉取行为，导致数据过期。请确保仅在响应用户操作时调用这些函数，或添加类似 hasNextPage() && !isFetching() 的条件判断。

参阅

infiniteQueryOptions，用于在 injectInfiniteQuery 和 queryClient.fetchInfiniteQuery 等命令式 API 之间共享这些选项。

示例

angular-ts
1@Component({2  selector: 'projects',3  template: `4    <!-- `projectsQuery.data()` is never `undefined`, thanks to `initialData` — even if a5    refetch fails, so the list stays visible alongside the error. -->6    <ul>7      @for (page of projectsQuery.data().pages; track $index) {8        @for (project of page.projects; track project.id) {9          <li>{{ project.name }}</li>10        }11      }12    </ul>13  `,14})15export class Projects {16  readonly projectsQuery = injectInfiniteQuery(() => ({17    queryKey: ['projects'],18    queryFn: ({ pageParam }) => fetchProjects(pageParam),19    initialPageParam: 0,20    getNextPageParam: (lastPage) => lastPage.nextId,21    initialData: { pages: [], pageParams: [] },22  }))23}

调用签名

TypeScript
1function injectInfiniteQuery<TQueryFnData, TError = Error, TData = InfiniteData<TQueryFnData, unknown>, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = unknown>(injectInfiniteQueryFn: () => UndefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, options?: InjectInfiniteQueryOptions): CreateInfiniteQueryResult<TData, TError>;

定义于：packages/angular-query-experimental/src/inject-infinite-query.ts:239

注入一个无限查询：一种声明式依赖，绑定到某个异步数据源，并由唯一查询键标识。无限查询可增量式地向现有数据集“加载更多”数据，或实现“无限滚动”。

类型参数

TQueryFnData

TQueryFnData

TError

TError = Error

TData

TData = InfiniteData<TQueryFnData, unknown>

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

TPageParam

TPageParam = unknown

参数

injectInfiniteQueryFn

() => UndefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>

一个返回要使用的 UndefinedInitialDataInfiniteOptions 的函数——即所有可传给 injectInfiniteQuery 的选项。与 Angular 中的 computed 类似，该函数在响应式上下文中运行，因此其中读取的信号会驱动查询。

options?

InjectInfiniteQueryOptions

附加配置。

返回值

CreateInfiniteQueryResult<TData, TError>

与 injectQuery 返回的信号相同，额外增加了 fetchNextPage、fetchPreviousPage、hasNextPage、hasPreviousPage、isFetchingNextPage 和 isFetchingPreviousPage。只要 select 不将 TData 改为偏离其默认 InfiniteData<TQueryFnData> 形状的类型，也会添加 data().pages 和 data().pageParams。

备注

请注意，命令式拉取调用（例如 fetchNextPage）可能会干扰默认的重新拉取行为，导致数据过期。请确保仅在响应用户操作时调用这些函数，或添加类似 hasNextPage() && !isFetching() 的条件判断。这是唯一支持 queryFn: skipToken 的重载，如下所示。

参阅

infiniteQueryOptions，用于在 injectInfiniteQuery 和 queryClient.fetchInfiniteQuery 等命令式 API 之间共享这些选项。

示例

通过按钮点击拉取下一页：

angular-ts
1@Component({2  selector: 'projects-list',3  template: `4    <ul>5      @for (page of projectsQuery.data()?.pages; track $index) {6        @for (project of page.projects; track project.id) {7          <li>{{ project.name }}</li>8        }9      }10    </ul>11    <button12      [disabled]="!projectsQuery.hasNextPage() || projectsQuery.isFetching()"13      (click)="projectsQuery.fetchNextPage()"14    >15      Load More16    </button>17  `,18})19export class ProjectsList {20  readonly projectsQuery = injectInfiniteQuery(() => ({21    queryKey: ['projects'],22    queryFn: ({ pageParam }) => fetchProjects(pageParam),23    initialPageParam: 0,24    getNextPageParam: (lastPage) => lastPage.nextId,25  }))26}

利用列表末尾的哨兵元素上的 IntersectionObserver，在用户滚动时自动拉取下一页：

angular-ts
1@Component({2  selector: 'projects-list',3  template: `4    <ul>5      @for (page of projectsQuery.data()?.pages; track $index) {6        @for (project of page.projects; track project.id) {7          <li>{{ project.name }}</li>8        }9      }10    </ul>11    <div #sentinel>{{ projectsQuery.isFetchingNextPage() ? 'Loading more...' : '' }}</div>12  `,13})14export class ProjectsList {15  readonly sentinel = viewChild<ElementRef<HTMLElement>>('sentinel')16 17  readonly projectsQuery = injectInfiniteQuery(() => ({18    queryKey: ['projects'],19    queryFn: ({ pageParam }) => fetchProjects(pageParam),20    initialPageParam: 0,21    getNextPageParam: (lastPage) => lastPage.nextId,22  }))23 24  constructor() {25    effect((onCleanup) => {26      const sentinel = this.sentinel()?.nativeElement27      if (28        sentinel == null ||29        !this.projectsQuery.hasNextPage() ||30        this.projectsQuery.isFetching()31      ) {32        return33      }34 35      const observer = new IntersectionObserver(([entry]) => {36        if (entry?.isIntersecting) this.projectsQuery.fetchNextPage()37      })38      observer.observe(sentinel)39 40      onCleanup(() => observer.disconnect())41    })42  }43}

一个在 postId 被设置前处于禁用状态且类型安全的查询——将 skipToken 作为 queryFn 传入，而非设置 enabled: false：

angular-ts
1@Component({2  selector: 'comments',3  template: `4    @if (postId() == null) {5      Select a post6    } @else if (commentsQuery.isPending()) {7      Loading...8    } @else if (commentsQuery.isError()) {9      <span>Error: {{ commentsQuery.error()?.message }}</span>10    } @else {11      <ul>12        @for (page of commentsQuery.data().pages; track $index) {13          @for (comment of page.comments; track comment.id) {14            <li>{{ comment.text }}</li>15          }16        }17      </ul>18    }19  `,20})21export class Comments {22  readonly postId = signal<string | undefined>(undefined)23 24  readonly commentsQuery = injectInfiniteQuery(() => ({25    queryKey: ['post', this.postId(), 'comments'],26    queryFn:27      this.postId() != null28        ? ({ pageParam }) => fetchComments(this.postId()!, pageParam)29        : skipToken,30    initialPageParam: 0,31    getNextPageParam: (lastPage) => lastPage.nextId,32  }))33}

调用签名

TypeScript
1function injectInfiniteQuery<TQueryFnData, TError = Error, TData = InfiniteData<TQueryFnData, unknown>, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = unknown>(injectInfiniteQueryFn: () => CreateInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, options?: InjectInfiniteQueryOptions): CreateInfiniteQueryResult<TData, TError>;

定义于：packages/angular-query-experimental/src/inject-infinite-query.ts:266

该重载接受通用的 CreateInfiniteQueryOptions 类型，而非上述与 initialData 相关的重载；因此无法从调用位置推断 data 是否已定义——当你在自定义辅助函数中封装 injectInfiniteQuery 并转发调用方传入的选项时，此特性尤为有用。

类型参数

TQueryFnData

TQueryFnData

TError

TError = Error

TData

TData = InfiniteData<TQueryFnData, unknown>

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

TPageParam

TPageParam = unknown

参数

injectInfiniteQueryFn

() => CreateInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>

一个返回无限查询选项的函数。与 Angular 中的 computed 类似，该函数在响应式上下文中运行，因此其中读取的信号会驱动查询。

options?

InjectInfiniteQueryOptions

附加配置。

返回值

CreateInfiniteQueryResult<TData, TError>

无限查询结果。

参数

injectInfiniteQueryFn

() => CreateInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>

一个返回无限查询选项的函数。与 Angular 中的 computed 类似，该函数在响应式上下文中运行，因此其中读取的信号会驱动查询。

injectInfiniteQueryFn 的属性

属性 类型 默认值 描述
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）。

选项？

InjectInfiniteQueryOptions

其他配置项。

options 属性

属性 类型 描述
injector? Injector 创建无限查询（infinite query）所用的 Injector。若未提供此选项，则将改用当前注入上下文（通过 inject 获取）。

返回值

CreateInfiniteQueryResult<TData, TError>

无限查询结果。

结果属性

基于 BaseQueryNarrowing 和 InfiniteQueryObserverBaseResult 构建。具体变更内容请参见上方类型定义。

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

译自上游 59d11de