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

createQuery

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

概述

TypeScript
1function createQuery<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: Accessor<DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>>, queryClient?: Accessor<QueryClient>): DefinedCreateQueryResult<TData, TError>;2function createQuery<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: Accessor<UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>>, queryClient?: Accessor<QueryClient>): CreateQueryResult<TData, TError>;3function createQuery<TQueryFnData, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: Accessor<CreateQueryOptions<TQueryFnData, TError, TData, TQueryKey>>, queryClient?: Accessor<QueryClient>): CreateQueryResult<TData, TError>;

另请参阅：参数 · 返回值

调用签名

TypeScript
1function createQuery<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: Accessor<DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>>, queryClient?: Accessor<QueryClient>): DefinedCreateQueryResult<TData, TError>;

定义于：packages/svelte-query/src/createQuery.ts:53

订阅一个查询：一种声明式依赖，指向一个与唯一查询键关联的异步数据源。
查询会在选项要求时执行 — enabled: false 会跳过初始拉取。

当 initialData 已知被定义时，将选择此重载，因此所得 data 永远不会是 undefined（除非某个 select 将 TData 更改为包含 undefined）。

类型参数

TQueryFnData

TQueryFnData = unknown

TError

TError = Error

TData

TData = TQueryFnData

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

参数

options

Accessor<DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>>

要使用的 DefinedInitialDataOptions — 即所有可传给 createQuery 的选项，且 initialData 已知被定义，并包裹在 Accessor 中以支持响应式更新。

queryClient?

Accessor<QueryClient>

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

返回值

DefinedCreateQueryResult<TData, TError>

当前查询结果，其类型确保 status 为 success — 或在拉取失败但保留已有数据时为 error（在此重载的类型中，status 永远不会解析为 pending，因为 initialData 保证了初始数据的存在）。isSuccess/isError 是为方便起见推导出的布尔值。

参阅

使用 queryOptions 在 createQuery 和 queryClient.query 等命令式 API 之间共享这些选项。

示例

svelte
1<script lang="ts">2  import { createQuery } from '@tanstack/svelte-query'3 4  // `data` is `Post[]`, never `undefined`, thanks to `initialData` — even if a refetch fails,5  // so the list stays visible alongside the error.6  const query = createQuery(() => ({7    queryKey: ['posts'],8    queryFn: fetchPosts,9    initialData: [],10  }))11</script>12 13{#if query.isError}14  <span>Error: {query.error.message}</span>15{/if}16<ul>17  {#each query.data as post (post.id)}18    <li>{post.title}</li>19  {/each}20</ul>

调用签名

TypeScript
1function createQuery<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: Accessor<UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>>, queryClient?: Accessor<QueryClient>): CreateQueryResult<TData, TError>;

定义于：packages/svelte-query/src/createQuery.ts:124

订阅一个查询：一种声明式依赖，指向一个与唯一查询键关联的异步数据源。
查询会在选项要求时执行 — enabled: false 会跳过初始拉取。

类型参数

TQueryFnData

TQueryFnData = unknown

TError

TError = Error

TData

TData = TQueryFnData

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

参数

options

Accessor<UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>>

要使用的 UndefinedInitialDataOptions — 即所有可传给 createQuery 的选项，并包裹在 Accessor 中以支持响应式更新。

queryClient?

Accessor<QueryClient>

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

返回值

CreateQueryResult<TData, TError>

当前查询结果。若无缓存数据可供显示，则 status 为 pending；若上一次拉取尝试失败，则为 error；若查询已有数据可供显示，则为 success。isPending/isSuccess/isError 是为方便起见推导出的布尔值。

参阅

使用 queryOptions 在 createQuery 和 queryClient.query 等命令式 API 之间共享这些选项。

示例

svelte
1<script lang="ts">2  import { createQuery } from '@tanstack/svelte-query'3 4  const query = createQuery(() => ({5    queryKey: ['posts'],6    queryFn: fetchPosts,7  }))8</script>9 10{#if query.status === 'pending'}11  Loading...12{:else if query.status === 'error'}13  <span>Error: {query.error.message}</span>14{:else}15  <ul>16    {#each query.data as post (post.id)}17      <li>{post.title}</li>18    {/each}19  </ul>20{/if}

同一查询，检查 isPending/isError 而非 status — 任选其一，以代码可读性更佳者为准：

svelte
1<script lang="ts">2  import { createQuery } from '@tanstack/svelte-query'3 4  const query = createQuery(() => ({5    queryKey: ['posts'],6    queryFn: fetchPosts,7  }))8</script>9 10{#if query.isPending}11  Loading...12{:else if query.isError}13  <span>Error: {query.error.message}</span>14{:else}15  <ul>16    {#each query.data as post (post.id)}17      <li>{post.title}</li>18    {/each}19  </ul>20{/if}

调用签名

TypeScript
1function createQuery<TQueryFnData, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: Accessor<CreateQueryOptions<TQueryFnData, TError, TData, TQueryKey>>, queryClient?: Accessor<QueryClient>): CreateQueryResult<TData, TError>;

定义于：packages/svelte-query/src/createQuery.ts:249

后备重载，适用于 initialData 是否存在在静态类型检查中无法确定的情况 — 例如，对象类型为 CreateQueryOptions 而非字面量对象。如有可能，请优先选用其他重载，因为它们能直接根据 initialData 推断 data 是否可为 undefined。

类型参数

TQueryFnData

TQueryFnData

TError

TError = Error

TData

TData = TQueryFnData

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

参数

options

Accessor<CreateQueryOptions<TQueryFnData, TError, TData, TQueryKey>>

要使用的 CreateQueryOptions — 即所有可传给 createQuery 的选项，并包裹在 Accessor 中以支持响应式更新。

queryClient?

Accessor<QueryClient>

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

返回值

CreateQueryResult<TData, TError>

当前查询结果。若无缓存数据可供显示，则 status 为 pending；若上一次拉取尝试失败，则为 error；若查询已有数据可供显示，则为 success。isPending/isSuccess/isError 是为方便起见推导出的布尔值。

参阅

使用 queryOptions 在 createQuery 和 queryClient.query 等命令式 API 之间共享这些选项。

示例

select 从缓存值中派生组件所需的 data，而不改变缓存中实际存储的内容 — 缓存仍保存完整的 Post[]，但此处的 data 是一个 number：

svelte
1<script lang="ts">2  import { createQuery } from '@tanstack/svelte-query'3 4  const query = createQuery(() => ({5    queryKey: ['posts'],6    queryFn: fetchPosts,7    select: (posts) => posts.length,8  }))9</script>10 11{#if query.isPending}12  Loading...13{:else if query.isError}14  <span>Error: {query.error.message}</span>15{:else}16  <span>{query.data} posts</span>17{/if}

一个依赖型查询，仅在 postId 被设置后才启用 — 使用 isLoading，而非 isPending，以避免查询被禁用时仍显示加载状态：

svelte
1<script lang="ts">2  import { createQuery } from '@tanstack/svelte-query'3 4  let { postId }: { postId: number | undefined } = $props()5 6  const query = createQuery(() => ({7    queryKey: ['post', postId],8    queryFn: () => fetchPost(postId!),9    enabled: postId != null,10  }))11</script>12 13{#if postId == null}14  Select a post15{:else if query.isLoading}16  Loading...17{:else if query.isError}18  <span>Error: {query.error.message}</span>19{:else}20  <h1>{query.data?.title}</h1>21{/if}

从已缓存的列表中预填充详情查询，从而跳过加载状态：

svelte
1<script lang="ts">2  import { createQuery, useQueryClient } from '@tanstack/svelte-query'3 4  let { postId }: { postId: number } = $props()5 6  const queryClient = useQueryClient()7 8  const query = createQuery(() => ({9    queryKey: ['post', postId],10    queryFn: () => fetchPost(postId),11    initialData: () =>12      queryClient13        .getQueryData<Array<Post>>(['posts'])14        ?.find((post) => post.id === postId),15  }))16</script>17 18{#if query.isError}19  <span>Error: {query.error.message}</span>20{/if}21<h1>{query.data?.title}</h1>

分页数据，在加载下一页时保持上一页的数据可见：

svelte
1<script lang="ts">2  import { createQuery, keepPreviousData } from '@tanstack/svelte-query'3 4  let page = $state(0)5 6  const query = createQuery(() => ({7    queryKey: ['posts', page],8    queryFn: () => fetchPosts(page),9    placeholderData: keepPreviousData,10  }))11</script>12 13{#if query.isError}14  <span>Error: {query.error.message}</span>15{/if}16<ul>17  {#each query.data ?? [] as post (post.id)}18    <li>{post.title}</li>19  {/each}20</ul>21<button disabled={query.isPlaceholderData} onclick={() => page++}>22  Next Page23</button>

参数

options

Accessor<CreateQueryOptions<TQueryFnData, TError, TData, TQueryKey>>

要使用的 CreateQueryOptions — 即所有可传给 createQuery 的选项，并包裹在 Accessor 中以支持响应式更新。

options 属性

属性 类型 默认值 描述
enabled? | false | true | ((query: Query<TQueryFnData, TError, TQueryData, TQueryKey>) => boolean) true 将此选项设为 false 或一个返回 false 的函数，可禁用查询挂载或查询键变更时的自动重新拉取。如需重新拉取查询，请使用 refetch 实例返回的 useQuery 方法。接受布尔值或返回布尔值的函数。
gcTime? number undefined 未使用/非活跃缓存数据在内存中保留的毫秒数。当某个查询的缓存变为未使用或非活跃状态后，该缓存数据将在该持续时间后被垃圾回收。若指定了多个垃圾回收时间，则采用最长的那个。设为 Infinity 将禁用垃圾回收。默认值为 5 * 60 * 1000（5 分钟），服务端渲染（SSR）期间则为 Infinity。注意：最大允许时间为约 24 天，这是由 setTimeout 的 32 位有符号整数延迟所限制——参见 timeoutManager.setTimeoutProvider 获取变通方案。
initialData? TQueryData | (() => TQueryData | undefined) undefined 若设置此值，它将作为查询缓存的初始数据（前提是该查询尚未创建或缓存）。若设为函数，该函数将在共享/根查询初始化期间仅执行一次，且需同步返回初始数据。默认情况下，初始数据被视为过期，除非已设置 staleTime。initialData 会被持久化到缓存中。
initialDataUpdatedAt? number | (() => number | undefined) undefined 若设置此值，它将作为 initialData 本身最后一次更新的时间（毫秒）。
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? | NonFunctionGuard<TQueryData> | ((previousData: NonFunctionGuard<TQueryData> | undefined, previousQuery: | Query<NonFunctionGuard<TQueryData>, TError, NonFunctionGuard<TQueryData>, TQueryKey> | undefined) => NonFunctionGuard<TQueryData> | 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, TQueryData, TQueryKey>) => number | false | undefined) false 若设为数字，查询将以该毫秒频率持续重新拉取。若设为函数，该函数将使用最新数据和查询来计算频率。
refetchIntervalInBackground? boolean false 若设为 true，查询将在其所在标签页/窗口处于后台时继续重新拉取。
refetchOnMount? | boolean | "always" | ((query: Query<TQueryFnData, TError, TQueryData, TQueryKey>) => boolean | "always") true 若设为 true，当数据过期时，查询将在挂载时重新拉取。若设为 false，将禁用额外查询实例触发后台重新拉取。若设为 'always'，查询将在每次挂载时始终重新拉取（除非使用 staleTime: 'static'）。若设为函数，该函数将使用最新数据和查询来计算该值。
refetchOnReconnect? | boolean | "always" | ((query: Query<TQueryFnData, TError, TQueryData, TQueryKey>) => boolean | "always") undefined 若设为 true，当数据过期时，查询将在重新连接网络时重新拉取。若设为 false，查询不会在网络重连时重新拉取。若设为 'always'，查询将在每次网络重连时始终重新拉取（除非使用 staleTime: 'static'）。若设为函数，该函数将使用最新数据和查询来计算该值。默认值为 true，除非 networkMode 为 'always'。
refetchOnWindowFocus? | boolean | "always" | ((query: Query<TQueryFnData, TError, TQueryData, 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 整数和实际的 Error，并返回下次尝试前应延迟的毫秒数。类似 attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000) 的函数应用指数退避策略；类似 attempt => attempt * 1000 的函数应用线性退避策略。默认为一个应用指数退避策略的函数，上限为 30 秒。
retryOnMount? | false | true | ((query: Query<TQueryFnData, TError, TQueryData, TQueryKey>) => boolean) true 若设为 false，包含错误的查询在挂载时将不会重试。若设为函数，该函数将使用查询来计算该值。
select? (data: TQueryData) => TData undefined 此选项可用于转换或选取查询函数返回数据的一部分。它会影响返回的 data 值，但不影响存储在查询缓存中的内容。select 函数仅在 data 发生变更，或 select 函数本身的引用发生变更时才会执行。为优化性能，请对函数进行记忆化处理，使其引用在多次调用中保持稳定。
staleTime? | number | "static" | ((query: Query<TQueryFnData, TError, TQueryData, 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, TQueryData, TQueryKey>) => boolean) false 是否应抛出错误而非设置 error 属性。若设为 true 或 suspense 为 true，所有错误都将抛出至错误边界。若设为 false 且 suspense 为 false，错误将作为状态返回。若设为函数，该函数将接收错误和查询，并应返回一个布尔值，指示是否应在错误边界中显示错误（true）或作为状态返回错误（false）。

queryClient？

Accessor<QueryClient>

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

返回值

CreateQueryResult<TData, TError>

当前查询结果。status 在尚无缓存数据可供显示时为 pending，上一次拉取尝试失败时为 error，查询已有数据可供显示时为 success。isPending/isSuccess/isError 是为方便使用而派生出的布尔值。

返回结果属性

属性 类型 描述
data TData | undefined 查询最后一次成功解析得到的数据。
dataUpdatedAt number 查询最近一次返回 status 为 "success" 的时间戳。
error TError | null 查询的错误对象（若抛出了错误）。- 默认值为 null。
errorUpdateCount number 所有错误的总数。
errorUpdatedAt number 查询最近一次返回 status 为 "error" 的时间戳。
failureCount number 查询失败次数。- 每次查询失败时递增。- 查询成功时重置为 0。
failureReason TError | null 查询重试失败的原因。- 查询成功时重置为 null。
fetchStatus "fetching" | "paused" | "idle" 查询的拉取状态。- fetching：当 queryFn 正在执行时为 true，包括初始 pending 和后台重新拉取。- paused：查询本应拉取，但已被 paused。- idle：查询未处于拉取中。- 更多信息请参阅 Network Mode。
isEnabled boolean 若该观察者已启用则为 true，否则为 false。
isError boolean 基于 status 变量派生出的布尔值，便于使用。- 若查询尝试发生错误则为 true。
isFetched boolean 若查询已完成拉取则为 true。
isFetchedAfterMount boolean 若查询在组件挂载后完成拉取则为 true。- 此属性可用于避免显示任何先前缓存的数据。
isFetching boolean 基于 fetchStatus 变量派生出的布尔值，便于使用。- 当 queryFn 正在执行时为 true，包括初始 pending 和后台重新拉取。
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