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

createInfiniteQuery

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

概述

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

另请参阅：参数 · 返回值

调用签名

TypeScript
1function createInfiniteQuery<TQueryFnData = unknown, TError = Error, TData = InfiniteData<TQueryFnData, unknown>, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = unknown>(options: Accessor<DefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>>, queryClient?: Accessor<QueryClient>): DefinedCreateInfiniteQueryResult<TData, TError>;

定义于：packages/svelte-query/src/createInfiniteQuery.ts:36

createInfiniteQuery 的选项与 createQuery 完全相同，额外增加了 initialPageParam、getNextPageParam、getPreviousPageParam 和 maxPages。

当 initialData 已知为已定义时，将选择此重载。

类型参数

TQueryFnData

TQueryFnData = unknown

TError

TError = Error

TData

TData = InfiniteData<TQueryFnData, unknown>

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

TPageParam

TPageParam = unknown

参数

options

Accessor<DefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>>

要使用的 DefinedInitialDataInfiniteOptions —— 即可传给 createInfiniteQuery 的全部内容（其中 initialData 已知为已定义），并包裹在 Accessor 中，以支持响应式更新。

queryClient?

Accessor<QueryClient>

使用此参数可指定自定义 QueryClient；否则将使用最近上下文中的 QueryClient。

返回值

DefinedCreateInfiniteQueryResult<TData, TError>

当前查询结果，以及用于分页的 fetchNextPage/fetchPreviousPage/hasNextPage/hasPreviousPage。

参阅

infiniteQueryOptions：在 createInfiniteQuery 与 queryClient.infiniteQuery 等命令式 API 之间共享这些选项。

调用签名

TypeScript
1function createInfiniteQuery<TQueryFnData = unknown, TError = Error, TData = InfiniteData<TQueryFnData, unknown>, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = unknown>(options: Accessor<UndefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>>, queryClient?: Accessor<QueryClient>): CreateInfiniteQueryResult<TData, TError>;

定义于：packages/svelte-query/src/createInfiniteQuery.ts:70

createInfiniteQuery 的选项与 createQuery 完全相同，额外增加了 initialPageParam、getNextPageParam、getPreviousPageParam 和 maxPages。

当 initialData 被省略、可能为 undefined，或是一个可能返回 undefined 的函数时，将选择此重载。

类型参数

TQueryFnData

TQueryFnData = unknown

TError

TError = Error

TData

TData = InfiniteData<TQueryFnData, unknown>

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

TPageParam

TPageParam = unknown

参数

options

Accessor<UndefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>>

要使用的 UndefinedInitialDataInfiniteOptions —— 即可传给 createInfiniteQuery 的全部内容，并包裹在 Accessor 中，以支持响应式更新。

queryClient?

Accessor<QueryClient>

使用此参数可指定自定义 QueryClient；否则将使用最近上下文中的 QueryClient。

返回值

CreateInfiniteQueryResult<TData, TError>

当前查询结果，以及用于分页的 fetchNextPage/fetchPreviousPage/hasNextPage/hasPreviousPage。

参阅

infiniteQueryOptions：在 createInfiniteQuery 与 queryClient.infiniteQuery 等命令式 API 之间共享这些选项。

调用签名

TypeScript
1function createInfiniteQuery<TQueryFnData, TError = Error, TData = InfiniteData<TQueryFnData, unknown>, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = unknown>(options: Accessor<CreateInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>>, queryClient?: Accessor<QueryClient>): CreateInfiniteQueryResult<TData, TError>;

定义于：packages/svelte-query/src/createInfiniteQuery.ts:182

createInfiniteQuery 的选项与 createQuery 完全相同，额外增加了 initialPageParam、getNextPageParam、getPreviousPageParam 和 maxPages。

类型参数

TQueryFnData

TQueryFnData

TError

TError = Error

TData

TData = InfiniteData<TQueryFnData, unknown>

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

TPageParam

TPageParam = unknown

参数

options

Accessor<CreateInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>>

要使用的 CreateInfiniteQueryOptions —— 即可传给 createInfiniteQuery 的全部内容，并包裹在 Accessor 中，以支持响应式更新。

queryClient?

Accessor<QueryClient>

使用此参数可指定自定义 QueryClient；否则将使用最近上下文中的 QueryClient。

返回值

CreateInfiniteQueryResult<TData, TError>

当前查询结果，以及用于分页的 fetchNextPage/fetchPreviousPage/hasNextPage/hasPreviousPage。

参阅

infiniteQueryOptions：在 createInfiniteQuery 与 queryClient.infiniteQuery 等命令式 API 之间共享这些选项。

示例

通过点击“加载更多”按钮获取下一页：

svelte
1<script lang="ts">2  import { createInfiniteQuery } from '@tanstack/svelte-query'3 4  const query = createInfiniteQuery(() => ({5    queryKey: ['projects'],6    queryFn: ({ pageParam }) => fetchProjects(pageParam),7    initialPageParam: 0,8    getNextPageParam: (lastPage) => lastPage.nextId,9  }))10</script>11 12{#if query.isPending}13  Loading...14{:else if query.isError}15  <span>Error: {query.error.message}</span>16{:else}17  <ul>18    {#each query.data.pages as page}19      {#each page.projects as project (project.id)}20        <li>{project.name}</li>21      {/each}22    {/each}23  </ul>24  <button25    onclick={() => query.fetchNextPage()}26    disabled={!query.hasNextPage || query.isFetching}27  >28    {query.isFetchingNextPage29      ? 'Loading more...'30      : query.hasNextPage31        ? 'Load More'32        : 'Nothing more to load'}33  </button>34{/if}

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

svelte
1<script lang="ts">2  import { createInfiniteQuery } from '@tanstack/svelte-query'3 4  const query = createInfiniteQuery(() => ({5    queryKey: ['projects'],6    queryFn: ({ pageParam }) => fetchProjects(pageParam),7    initialPageParam: 0,8    getNextPageParam: (lastPage) => lastPage.nextId,9  }))10 11  let sentinel: HTMLDivElement | undefined = $state()12 13  $effect(() => {14    if (sentinel == null || !query.hasNextPage || query.isFetching) return15 16    const observer = new IntersectionObserver(([entry]) => {17      if (entry?.isIntersecting) query.fetchNextPage()18    })19    observer.observe(sentinel)20 21    return () => observer.disconnect()22  })23</script>24 25{#if query.isPending}26  Loading...27{:else if query.isError}28  <span>Error: {query.error.message}</span>29{:else}30  <ul>31    {#each query.data.pages as page}32      {#each page.projects as project (project.id)}33        <li>{project.name}</li>34      {/each}35    {/each}36  </ul>37  <div bind:this={sentinel}></div>38{/if}

参数

options

Accessor<CreateInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>>

要使用的 CreateInfiniteQueryOptions —— 即可传给 createInfiniteQuery 的全部内容，并包裹在 Accessor 中，以支持响应式更新。

options 属性

属性 类型 默认值 描述
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 获取变通方案。
queryFn? | 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 可禁用查询结果之间的结构共享。将其设为一个接收旧数据和新数据并返回同类型已解析数据的函数，即可实现自定义结构共享逻辑。
suspense? boolean false 若设为 true，查询将在 status === 'pending' 时挂起，并在 status === 'error' 时抛出错误。
throwOnError? | false | true | ((error: TError, query: Query<TQueryFnData, TError, InfiniteData<TQueryFnData, TPageParam>, TQueryKey>) => boolean) false 是否应抛出错误而非设置 error 属性。若设为 true 或 suspense 为 true，所有错误都将抛出至错误边界。若设为 false 且 suspense 也为 false，错误将作为状态返回。若设为函数，则该函数将接收错误和查询，并应返回一个布尔值，指示是否应在错误边界中显示错误（true）或作为状态返回错误（false）。

queryClient？

Accessor<QueryClient>

使用此选项可指定自定义的 QueryClient。否则，将使用离当前组件最近的上下文中的 QueryClient。

返回值

CreateInfiniteQueryResult<TData, TError>

当前查询结果，以及用于分页的 fetchNextPage/fetchPreviousPage/hasNextPage/hasPreviousPage 函数。

返回结果属性

属性 类型 描述
data TData | undefined 查询最后一次成功解析的数据。
dataUpdatedAt number 查询最近一次返回 status 为 "success" 状态的时间戳。
error TError | null 查询的错误对象（如果抛出了错误）。- 默认值为 null。
errorUpdateCount number 所有错误的总数。
errorUpdatedAt number 查询最近一次返回 status 为 "error" 状态的时间戳。
failureCount number 查询失败次数。- 每次查询失败时递增。- 查询成功时重置为 0。
failureReason TError | null 查询重试失败的原因。- 查询成功时重置为 null。
fetchNextPage (options?: FetchNextPageOptions) => Promise<InfiniteQueryObserverResult<TData, TError>> 此函数用于拉取下一页结果。
fetchPreviousPage (options?: FetchPreviousPageOptions) => Promise<InfiniteQueryObserverResult<TData, TError>> 此函数用于拉取上一页结果。
fetchStatus "fetching" | "paused" | "idle" 查询的拉取状态。- fetching：当 queryFn 正在执行时为 true，包括初始 pending 和后台重新拉取。- paused：查询本应拉取，但已被 paused。- idle：查询未处于拉取中。- 更多信息请参阅 Network Mode。
hasNextPage boolean 若存在下一页（通过 getNextPageParam 选项判定），则为 true。
hasPreviousPage boolean 若存在上一页（通过 getPreviousPageParam 选项判定），则为 true。
isEnabled boolean 若该观察者已启用，则为 true；否则为 false。
isError boolean 基于 status 变量推导出的布尔值，仅为方便使用。- 若查询尝试发生错误，则为 true。
isFetched boolean 若查询已完成拉取，则为 true。
isFetchedAfterMount boolean 若查询在组件挂载后完成拉取，则为 true。- 此属性可用于避免显示任何先前缓存的数据。
isFetching boolean 基于 fetchStatus 变量推导出的布尔值，仅为方便使用。- 当 queryFn 正在执行时（包括初始 pending 和后台重新拉取）为 true。
isFetchingNextPage boolean 使用 fetchNextPage 拉取下一页时为 true。
isFetchingPreviousPage boolean 使用 fetchPreviousPage 拉取上一页时为 true。
isFetchNextPageError boolean 若拉取下一页时查询失败，则为 true。
isFetchPreviousPageError boolean 若拉取上一页时查询失败，则为 true。
isInitialLoading boolean 已弃用 isInitialLoading 已被 isLoading 取代，将在下一个主版本中移除。
isLoading boolean 若查询的首次拉取正在进行中，则为 true。- 等同于 isFetching && isPending。
isLoadingError boolean 若查询首次拉取失败，则为 true。
isPaused boolean 基于 fetchStatus 变量推导出的布尔值，仅为方便使用。- 查询本应拉取，但已被 paused。
isPending boolean 若尚无缓存数据且尚未完成任何查询尝试，则为 pending。
isPlaceholderData boolean 若当前显示的数据为占位数据，则为 true。
isRefetchError boolean 若查询在重新拉取时失败，则为 true。
isRefetching boolean 若后台重新拉取正在进行中，则为 true（不包含 初始 pending）。- 等同于 isFetching && !isPending。
isStale boolean 若缓存中的数据已失效，或数据比给定的 staleTime 更旧，则为 true。
isSuccess boolean 基于 status 变量推导出的布尔值，仅为方便使用。- 若查询已收到无错误响应并已准备好显示其数据，则为 true。
refetch (options?: RefetchOptions) => Promise<QueryObserverResult<TData, TError>> 用于手动重新拉取查询的函数。
status "error" | "pending" | "success" 查询的状态。- 可能为：- pending：若尚无缓存数据且尚未完成任何查询尝试。- error：若查询尝试发生错误。- success：若查询已收到无错误响应并已准备好显示其数据。

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

译自上游 59d11de