tanstack-vue-query-skilld

@tanstack/[email protected]

适用于 Vue 的异步数据钩子。版本为 5.103.2，准备好的源代码位于 input/source。 对等依赖项：vue ^2.6.0 || ^3.3.0；Vue 2 需要 @vue/composition-api（可选对等依赖项）（package.json:56-59）。 重新导出 @tanstack/query-core 5.103.2 中的所有内容，因此 keepPreviousData、skipToken、focusManager、onlineManager、hydration 工具和 observer 类都可以直接从 @tanstack/vue-query 导入（src/index.ts:1）。

安装

每个应用安装一次插件。它会创建（或接收）一个 QueryClient，在整个应用中提供该客户端，并挂载／卸载该客户端（src/vueQueryPlugin.ts:74-154）：

import { createApp } from 'vue'
import { QueryClient, VueQueryPlugin } from '@tanstack/vue-query'

const app = createApp(App)

// Option A: pass your own client (required for SSR — one fresh client per request)
const queryClient = new QueryClient()
app.use(VueQueryPlugin, { queryClient })

// Option B: let the plugin build one with your defaults
app.use(VueQueryPlugin, {
  queryClientConfig: { defaultOptions: { queries: { staleTime: 5 * 1000 } } },
})

VueQueryPluginOptions：queryClient 或 queryClientConfig（二选一）、queryClientKey（仅在安装多个客户端时使用）、clientPersister + clientPersisterOnSuccess（恢复持久化缓存）、enableDevtoolsV6Plugin（src/vueQueryPlugin.ts:11-38）。服务器上不会挂载客户端（src/vueQueryPlugin.ts:87-89）。

如果在注入上下文之外调用 useQueryClient(id?)，或未安装插件，该函数会抛出错误（src/useQueryClient.ts:27-44）。

基本查询

<script setup lang="ts">
import { ref } from 'vue'
import { useQuery } from '@tanstack/vue-query'

const postId = ref(1)
const { status, data, error, refetch } = useQuery({
  queryKey: ['post', postId],          // ref inside the key: tracked, no .value
  queryFn: () => fetchPost(postId.value),
})
</script>

<template>
  <span v-if="status === 'pending'">Loading...</span>
  <span v-else-if="status === 'error'">Error: {{ error!.message }}</span>
  <h1 v-else>{{ data!.title }}</h1>
</template>

基本变更

<script setup lang="ts">
import { useMutation, useQueryClient } from '@tanstack/vue-query'

const queryClient = useQueryClient()
const addMutation = useMutation({
  mutationFn: addTodo,
  onSuccess: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
})

function onAdd() {
  addMutation.mutate('Item', {
    onError: (error) => console.error('Failed:', error),
  })
}
</script>

<template>
  <button @click="onAdd">Add</button>
</template>

mutate 会按设计吞掉拒绝；每次调用的回调只会在最新一次调用时触发。要为每次调用获取一个 Promise，请使用 mutateAsync（src/useMutation.ts:262-270）。

Vue 开发者需注意的规则

• 返回值都是 Ref。 useQuery／useInfiniteQuery／useMutation 的每个结果字段都是 Ref（在脚本中使用 data.value，在模板中会自动解包），但函数 refetch、fetchNextPage、fetchPreviousPage、mutate、mutateAsync、reset 以及 suspense() 除外（src/useBaseQuery.ts:27-40、src/useMutation.ts:53-68）。
• useQueries 返回一个包含整个结果数组（或 combine 值）的 Ref，而不是响应式数组（src/useQueries.ts:357-376）。
• 查询键中的 ref 永远不要解包。 将 ref 本身放入 queryKey，并在 queryFn 中读取 .value（src/utils.ts:84-111）。
• 只有 queryKey 和 enabled 接受响应式 getter。 其他位置的函数都是实际回调（queryFn、select 等）。要让任意选项变为响应式，请传入整个选项对象的 getter：useQuery(() => ({ ... }))（src/queryOptions.ts:67-76、src/useQuery.ts:225-227）。
• initialData 不具备响应性；它只会读取一次（src/queryOptions.ts:136-148）。
• 在 setup() 或 effectScope 中调用组合式函数。 在作用域之外调用时，开发模式会发出可能导致内存泄漏的警告（src/useBaseQuery.ts:82-88）。
• 命令式获取数据请通过 queryClient.query()／queryClient.infiniteQuery() 执行。 fetchQuery、prefetchQuery、fetchInfiniteQuery、prefetchInfiniteQuery、ensureQueryData 已弃用，计划移除（src/queryClient.ts:251-253、src/queryClient.ts:311-313）。
• 使用 queryOptions() 声明共享查询，这样查询键就会携带数据类型，可供 getQueryData、invalidateQueries 和预取复用（src/queryOptions.ts:244-251）。

环境限制

• 准备好的源代码：@tanstack/vue-query 5.103.2，搭配 @tanstack/query-core 5.103.2（package.json:2,45）。文档与 v5 匹配；旧示例中可能会出现 v4 API。
• Vue 3 需使用 Vue 3.3+；Vue 2.6+ 需搭配 @vue/composition-api，或使用原生支持的 Vue 2.7（package.json:52-59）。
• 以 ESM 为优先的双构建版本（build/modern、build/legacy）；sideEffects: false（package.json:21-35）。

参考资料

• references/api.md — 每个导出项及其签名和在源码中的位置。
• references/reactivity.md — refs、getter、skipToken、queryOptions getter、shallow。
• references/query-client.md — Vue QueryClient、响应式参数、失效时机、SSR、多个客户端。
• references/mutations.md — 变更、mutationOptions、useMutationState、乐观更新。
• references/migration.md — v5 破坏性变更，以及 5.90 之后的版本特定规则。

官方文档：https://tanstack.com/query/latest/docs/framework/vue/overview