queryOptions

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

概述

TypeScript

1function queryOptions<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: DefinedInitialQueryOptions<TQueryFnData, TError, TData, TQueryKey>): DefinedInitialQueryOptionsWithDataTag<TQueryFnData, TError, TData, TQueryKey>;2function queryOptions<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: () => DefinedInitialQueryOptions<TQueryFnData, TError, TData, TQueryKey>): () => DefinedInitialQueryOptionsWithDataTag<TQueryFnData, TError, TData, TQueryKey>;3function queryOptions<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: UndefinedInitialQueryOptions<TQueryFnData, TError, TData, TQueryKey>): UndefinedInitialQueryOptionsWithDataTag<TQueryFnData, TError, TData, TQueryKey>;4function queryOptions<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: () => UndefinedInitialQueryOptions<TQueryFnData, TError, TData, TQueryKey>): () => UndefinedInitialQueryOptionsWithDataTag<TQueryFnData, TError, TData, TQueryKey>;

DefinedInitialQueryOptions → DefinedInitialQueryOptionsWithDataTag：你通常可以向 queryOptions 传入所有能传给 useQuery 的参数。这些选项可在多个 Hook 和命令式 API（例如 queryClient.query）之间共享。options.queryKey 是必需的，它指定了用于生成选项的查询键。
() => DefinedInitialQueryOptions → () => DefinedInitialQueryOptionsWithDataTag：与普通对象重载相同，但适用于闭包中捕获响应式状态（即在函数体内读取的 ref）的选项。请将它们包裹在一个 getter 中，以便 queryClient 方法（如 invalidateQueries/fetchQuery）始终读取当前值，而非创建选项时捕获的值。
UndefinedInitialQueryOptions → UndefinedInitialQueryOptionsWithDataTag：你通常可以向 queryOptions 传入所有能传给 useQuery 的参数。这些选项可在多个 Hook 和命令式 API（例如 queryClient.query）之间共享。options.queryKey 是必需的，它指定了用于生成选项的查询键。
() => UndefinedInitialQueryOptions → () => UndefinedInitialQueryOptionsWithDataTag：与普通对象重载相同，但适用于闭包中捕获响应式状态（即在函数体内读取的 ref）的选项。请将它们包裹在一个 getter 中，以便 queryKey（以及任何其他从 ref 衍生出的内容）响应变化，并确保 queryClient 方法（如 invalidateQueries/fetchQuery）始终读取当前值，而非创建选项时捕获的值。

另请参阅：参数 · 返回值

调用签名

TypeScript

1function queryOptions<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: DefinedInitialQueryOptions<TQueryFnData, TError, TData, TQueryKey>): DefinedInitialQueryOptionsWithDataTag<TQueryFnData, TError, TData, TQueryKey>;

定义于：packages/vue-query/src/queryOptions.ts:253

你通常可以向 queryOptions 传入所有能传给 useQuery 的参数。这些选项可在多个 Hook 和命令式 API（例如 queryClient.query）之间共享。options.queryKey 是必需的，它指定了用于生成选项的查询键。

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

类型参数

TQueryFnData

TQueryFnData = unknown

TError

TError = Error

TData

TData = TQueryFnData

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

参数

options

DefinedInitialQueryOptions<TQueryFnData, TError, TData, TQueryKey>

要使用的 DefinedInitialQueryOptions —— 即所有可传给 useQuery 的参数，且 initialData 已知为已定义。

返回值

DefinedInitialQueryOptionsWithDataTag<TQueryFnData, TError, TData, TQueryKey>

相同选项对象，其类型被设定为使 queryKey 携带推断出的数据类型。

参阅

使用 useQuery 运行带有这些选项的查询。

示例

HTML

1<script setup lang="ts">2import { queryOptions, useQuery } from '@tanstack/vue-query'34const postsOptions = queryOptions({5  queryKey: ['posts'],6  queryFn: fetchPosts,7  initialData: [],8})910// `data` is `Post[]`, never `undefined`, thanks to `initialData` — even if a refetch fails,11// so the list stays visible alongside the error.12const { data, isError, error } = useQuery(postsOptions)13</script>

调用签名

TypeScript

1function queryOptions<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: () => DefinedInitialQueryOptions<TQueryFnData, TError, TData, TQueryKey>): () => DefinedInitialQueryOptionsWithDataTag<TQueryFnData, TError, TData, TQueryKey>;

定义于：packages/vue-query/src/queryOptions.ts:288

与普通对象重载相同，但适用于闭包中捕获响应式状态（即在函数体内读取的 ref）的选项。请将它们包裹在一个 getter 中，以便 queryClient 方法（如 invalidateQueries/fetchQuery）始终读取当前值，而非创建选项时捕获的值。

类型参数

TQueryFnData

TQueryFnData = unknown

TError

TError = Error

TData

TData = TQueryFnData

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

参数

options

() => DefinedInitialQueryOptions<TQueryFnData, TError, TData, TQueryKey>

返回要使用的 DefinedInitialQueryOptions 的函数，按需重新求值。

返回值

一个返回相同选项对象的函数，其类型被设定为使 queryKey 携带推断出的数据类型。

() => DefinedInitialQueryOptionsWithDataTag<TQueryFnData, TError, TData, TQueryKey>

参阅

使用 useQuery 运行带有这些选项的查询。

示例

HTML

1<script setup lang="ts">2import { ref } from 'vue'3import { queryOptions, useQuery } from '@tanstack/vue-query'45const postId = ref(1)6const postOptions = queryOptions(() => ({7  queryKey: ['post', postId.value],8  queryFn: () => fetchPost(postId.value),9  initialData: { id: postId.value, title: '' },10}))1112// Pass the getter itself, not `postOptions()`, so the query keeps reacting to `postId` changes.13const { data } = useQuery(postOptions)14</script>

调用签名

TypeScript

1function queryOptions<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: UndefinedInitialQueryOptions<TQueryFnData, TError, TData, TQueryKey>): UndefinedInitialQueryOptionsWithDataTag<TQueryFnData, TError, TData, TQueryKey>;

定义于：packages/vue-query/src/queryOptions.ts:331

类型参数

TQueryFnData

TQueryFnData = unknown

TError

TError = Error

TData

TData = TQueryFnData

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

参数

options

UndefinedInitialQueryOptions<TQueryFnData, TError, TData, TQueryKey>

要使用的 UndefinedInitialQueryOptions —— 即所有可传给 useQuery 的参数。

返回值

UndefinedInitialQueryOptionsWithDataTag<TQueryFnData, TError, TData, TQueryKey>

相同选项对象，其类型被设定为使 queryKey 携带推断出的数据类型。

参阅

使用 useQuery 运行带有这些选项的查询。

示例

参数化工厂函数，使得同一选项对象可按 id 复用：

HTML

1<script setup lang="ts">2import { queryOptions, useQuery } from '@tanstack/vue-query'34function postOptions(id: string) {5  return queryOptions({6    queryKey: ['post', id],7    queryFn: () => fetchPost(id),8  })9}1011const { data, isPending, isError, error } = useQuery(postOptions('1'))12</script>

调用签名

TypeScript

1function queryOptions<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: () => UndefinedInitialQueryOptions<TQueryFnData, TError, TData, TQueryKey>): () => UndefinedInitialQueryOptionsWithDataTag<TQueryFnData, TError, TData, TQueryKey>;

定义于：packages/vue-query/src/queryOptions.ts:394

与普通对象重载相同，但适用于闭包中捕获响应式状态（即在函数体内读取的 ref）的选项。请将它们包裹在一个 getter 中，以便 queryKey（以及任何其他从 ref 衍生出的内容）响应变化，并确保 queryClient 方法（如 invalidateQueries/fetchQuery）始终读取当前值，而非创建选项时捕获的值。

类型参数

TQueryFnData

TQueryFnData = unknown

TError

TError = Error

TData

TData = TQueryFnData

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

参数

options

() => UndefinedInitialQueryOptions<TQueryFnData, TError, TData, TQueryKey>

返回要使用的 UndefinedInitialQueryOptions 的函数，按需重新求值。

返回值

一个返回相同选项对象的函数，其类型被设定为使 queryKey 携带推断出的数据类型。

() => UndefinedInitialQueryOptionsWithDataTag<TQueryFnData, TError, TData, TQueryKey>

参阅

使用 useQuery 运行带有这些选项的查询。

示例

HTML

1<script setup lang="ts">2import { ref } from 'vue'3import { queryOptions, useQuery, useQueryClient } from '@tanstack/vue-query'45const postId = ref(1)6const postOptions = queryOptions(() => ({7  queryKey: ['post', postId.value],8  queryFn: () => fetchPost(postId.value),9}))1011// Pass the getter itself, not `postOptions()`, so the query keeps reacting to `postId` changes.12const { data } = useQuery(postOptions)13const queryClient = useQueryClient()14// Here, call `postOptions()` so `invalidateQueries` reads the current `queryKey` right away.15queryClient.invalidateQueries(postOptions())16</script>

一个参数化工厂函数，该函数在 postId 被设置前禁用查询（类型安全）。整个选项 getter 在 postId 每次变更时都会重新求值 queryFn。queryFn 也可以是一个 computed，但绝不能是裸露的 getter，因为此处的函数本身即为查询函数：

HTML

1<script setup lang="ts">2import { queryOptions, skipToken, useQuery } from '@tanstack/vue-query'34function postOptions(postId: number | undefined) {5  return queryOptions(() => ({6    queryKey: ['post', postId],7    queryFn: postId != null ? () => fetchPost(postId) : skipToken,8  }))9}1011const props = defineProps<{ postId: number | undefined }>()12const { data, isLoading, isError, error } = useQuery(postOptions(props.postId))13</script>

参数

options

() => UndefinedInitialQueryOptions<TQueryFnData, TError, TData, TQueryKey>

返回要使用的 UndefinedInitialQueryOptions 的函数，按需重新求值。

返回值

一个返回相同选项对象的函数，其类型被设定为使 queryKey 携带推断出的数据类型。

() => UndefinedInitialQueryOptionsWithDataTag<TQueryFnData, TError, TData, TQueryKey>