尧图网页设计 
Vue Querytanstack/vue-query实战指南Vue 应用中异步数据的获取、缓存与状态管理【免费下载链接】query Powerful asynchronous state management, server-state utilities and data fetching for the web. TS/JS, React Query, Solid Query, Svelte Query and Vue Query.项目地址: https://gitcode.com/GitHub_Trending/qu/queryVue Query 是 TanStack Query 生态在 Vue 侧的官方实现它为 Vue 应用提供了一套用于获取、缓存和更新异步数据的组合式 APIComposables。本指南将带你从零开始安装、初始化并在setup()中使用useQuery深入讲解其响应式选项机制与底层实现原理并覆盖无限查询、变更Mutation、预取等完整能力帮助你写出更少样板代码、更健壮的 Vue 数据层代码。安装与初始化安装包在当前仓库中Vue Query 的实现位于 packages/vue-query发布名称为tanstack/vue-query当前仓库版本为 5.102.8见 packages/vue-query/package.json。你可以使用任意主流包管理器安装$ npm i tanstack/vue-query$ pnpm add tanstack/vue-query$ yarn add tanstack/vue-query$ bun add tanstack/vue-queryVue 2.x 用户注意该包通过 vue-demi 支持 Vue 2.x。如果使用 Vue 2.6还需要额外安装并配置 vue/composition-api。从 packages/vue-query/package.json 的peerDependencies可以看到其声明为vue: ^2.6.0 || ^3.3.0且vue/composition-api为可选依赖而devDependencies中同时包含vue3、vue22.6、vue2.7测试脚本分别通过vue-demi-switch在 2 / 2.7 / 3 三种模式下运行以验证跨版本兼容性。通过 VueQueryPlugin 初始化Vue Query 通过插件Plugin形式接入应用插件的install会在应用上下文provide/inject中注入一个共享的QueryClient实例之后所有组合式函数才能工作import { createApp } from vue import { VueQueryPlugin } from tanstack/vue-query import App from ./App.vue createApp(App).use(VueQueryPlugin).mount(#app)从 packages/vue-query/src/vueQueryPlugin.ts 的源码可以看到VueQueryPlugin内部做了几件关键事情创建或复用 QueryClient若传入queryClient选项则直接使用否则用queryClientConfig新建一个QueryClient内部调用new QueryClient(clientConfig)。挂载客户端非服务端环境下调用client.mount()使缓存开始工作。支持持久化clientPersister若提供clientPersister插件会调用它拿到[unmount, promise]在持久化 Promise 完成后将client.isRestoring.value置回false并触发clientPersisterOnSuccess回调。应用卸载时清理优先注册app.onUnmount(cleanup)否则包装app.unmount方法确保调用client.unmount()与 persister 的清理函数。注入客户端Vue 3 下调用app.provide(clientKey, client)Vue 2 下通过 mixin 的beforeCreate将客户端写入_provided。可选 Devtools开发环境下若开启enableDevtoolsV6Plugin则调用setupDevtools接入调试面板。插件可配置项VueQueryPluginOptions总结如下选项类型说明queryClientQueryClient直接提供已创建的客户端实例queryClientConfigQueryClientConfig未提供queryClient时用于新建客户端的配置queryClientKeystring自定义注入键后缀生成如VUE_QUERY_CLIENT:key的键见 packages/vue-query/src/utils.ts 的getClientKeyclientPersister(client) [unmount, promise]客户端持久化函数返回卸载函数与 PromiseclientPersisterOnSuccess(client) void持久化成功后的回调enableDevtoolsV6Pluginboolean是否启用 Vue Devtools v6 插件支持第一个查询useQuery安装并注册插件后即可在任何组件的setup()中使用useQueryimport { defineComponent } from vue import { useQuery } from tanstack/vue-query export default defineComponent({ name: MyComponent, setup() { const query useQuery({ queryKey: [todos], queryFn: getTodos }) return { query, } }, })useQuery返回的对象中data、isLoading、isError、error、isFetching等状态均以Ref形式暴露模板中可自动解包setup中需要.value访问而refetch、fetchNextPage等函数则保持为普通函数。这一点可以从 packages/vue-query/src/useBaseQuery.ts 的类型定义UseBaseQueryReturnType看出除了fetchNextPage/fetchPreviousPage/refetch三个函数外其余结果字段都被包装为RefReadonlyTResult[K]。动态更新选项使用响应式变量Vue Query 是响应式驱动reactive的库——当查询选项如queryKey、enabled发生变化时查询会自动重新执行。因此如果需要动态更新查询选项必须将选项以响应式变量ref / getter的形式传入import { ref } from vue const id ref(1) const enabled ref(false) const query useQuery({ queryKey: [todos, id], queryFn: () getTodos(id), enabled, })当id.value变化时queryKey随之变化Vue Query 会感知到并触发重新获取enabled为false时查询会被禁用不发起请求但保留已有缓存。响应式选项的底层原理useQuery只是useBaseQuery(QueryObserver, options)的一层薄封装见 packages/vue-query/src/useQuery.ts。真正承载响应式逻辑的是 packages/vue-query/src/useBaseQuery.ts其核心流程为选项归一化通过computed对传入的options求值——若 options 是 getter 函数则先调用它随后用cloneDeepUnref深度克隆并解包所有 ref/getter得到纯对象再调用client.defaultQueryOptions填充默认值并设置_optimisticResults恢复期标记。创建 Observer以defaultedOptions.value实例化QueryObserver来自tanstack/query-core。状态包装默认用reactive(observer.getCurrentResult())生成响应式状态若选项shallow: true则改用shallowReactive之后通过updateState把观察者每次推送的结果合并进该状态。订阅与清理watch(defaultedOptions, updater)监听选项变化并调用observer.setOptions重新同步onScopeDispose中退订确保组件销毁后不再泄漏源码还针对在setup()或 effect scope 之外调用组合式函数的情况在开发环境打印内存泄漏警告。错误边界watch监听state.error在shouldThrowError判定为需要抛出时直接throw error配合ErrorBoundary使用。cloneDeepUnref见 packages/vue-query/src/utils.ts是响应式选项的关键工具函数它递归遍历对象遇到 ref 自动unref遇到 getter在queryKey层级自动调用取值从而让选项中的任意深度的 ref 都能被正确解包并触发依赖追踪。深入响应式为什么必须传响应式变量Vue Query 在 Vue 侧的独特设计是响应式选项 深度解包。它把所有选项放进computed中求值因此传入ref的选项如enabled、id会在 ref 变化时触发defaultedOptions重算传入 getter 函数如() ({ queryKey: [todos, id.value] })同样受支持queryKey支持数组与嵌套 ref如[todos, id]cloneDeepUnref会深度解包到最底层。这种设计与 React Query 的选项对象每次渲染重新创建不同Vue 的响应式系统让选项变化 → 查询重新执行成为声明式行为无需手动管理依赖数组。更多响应式设计细节可参考仓库文档 docs/framework/vue/reactivity.md。更丰富的查询能力并行与依赖查询useQueries当需要同时发起多个查询如动态数量的查询时使用useQueries当查询 B 依赖查询 A 的结果时可在queryFn中读取前一个查询的data形成依赖关系。无限查询与滚动加载useInfiniteQueryuseInfiniteQuery用于分页、游标与加载更多场景。从 packages/vue-query/src/useInfiniteQuery.ts 可见它同样是useBaseQuery的封装只不过观察者换成InfiniteQueryObserver。其返回结果比useQuery多了data.pages、data.pageParams、fetchNextPage、fetchPreviousPage、hasNextPage等字段配合getNextPageParam即可实现滚动分页Vue Query 还支持滚动位置恢复Scroll Recovery参考仓库示例 examples/react/load-more-infinite-scroll 与 examples/vue/2.7-basic 等目录。变更useMutation异步数据的写操作增删改通过useMutation完成。典型用法import { useMutation } from tanstack/vue-query const mutation useMutation({ mutationFn: (newTodo) axios.post(/todos, newTodo), })从 packages/vue-query/src/useMutation.ts 源码可以看到useMutation内部使用MutationObserver返回的mutate是同步触发函数内部调用observer.mutate并吞掉 Promise 拒绝以免产生未捕获异常、mutateAsync返回 Promise 以便await此外还有reset与isPending/isError/error等状态 Ref。变更成功后通常配合queryClient.invalidateQueries让相关查询失效并重新获取。全局状态助手useIsFetching()/useIsMutating()获取当前应用中正在获取/变更的查询数量可用于全局 loading 指示。useMutationState()订阅并观察 mutation 的状态列表用于乐观更新等场景。这些导出一并汇总在入口文件 packages/vue-query/src/index.ts该文件同时重导出了tanstack/query-core的全部能力QueryClient、QueryCache、MutationCache等。预取PrefetchingusePrefetchQuery与usePrefetchInfiniteQuery允许在渲染前主动将数据写入缓存配合 Suspense 可实现Fetch-As-You-Render边渲染边获取的体验。缓存、失效与重新获取Vue Query 的核心价值在于开箱即用的缓存体系主要包括自动缓存 重新获取Auto Caching Refetching基于 stale-while-revalidate 策略数据过期后在后台静默重新获取支持窗口聚焦Window Refocus时重新获取、轮询/实时刷新Polling/Realtime。多层缓存 自动垃圾回收Multi-layer Cache Garbage Collection未使用的查询在gcTime默认 5 分钟后被自动清理释放内存。请求取消Request Cancellation查询键变化或组件卸载时自动取消进行中的请求queryFn中可通过signal支持 AbortController。失效与重取queryClient.invalidateQueries({ queryKey: [...] })使指定查询失效refetchQueries直接重取setQueryData手动写入缓存。以上能力最终由tanstack/query-core提供仓库文档 docs/framework/vue/reference/QueryClient.md 提供了QueryClient的完整 API 参考。类型安全与查询选项工厂为提升类型体验Vue Query 提供了queryOptions、infiniteQueryOptions、mutationOptions三个选项工厂函数见 packages/vue-query/src/queryOptions.ts 等。它们返回带类型标注的选项对象让useQuery/useInfiniteQuery/useMutation能够自动推断data与error的类型。仓库中还配套了丰富的类型测试如 packages/vue-query/src/tests/useQuery.test-d.tsx、useInfiniteQuery.test-d.tsx并通过test:types脚本在多个 TypeScript 版本5.6/5.7/5.8/5.9/当前/7.0下做编译校验。更多 TypeScript 用法参见 docs/framework/vue/typescript.md。进阶能力与生态Suspense实验性useQuery返回对象中带有suspense()方法见useBaseQuery中的suspense实现支持 Suspense 数据流。SSR实验性支持服务端渲染场景可在服务端预取数据。Devtools提供专属调试面板安装tanstack/vue-query-devtools仓库内位于 packages/vue-query-devtools并可配合 docs/framework/vue/devtools.md 使用。持久化结合tanstack/vue-query-persist-client仓库内位于 packages/vue-query-persist-client可将查询缓存持久化到 storage。快速上手指南仓库为 Vue 提供了多个可直接运行的示例建议从 examples/vue/basic 开始它包含完整的 Vite Vue 工程与src/main.ts、src/App.vue等源码覆盖插件注册、useQuery使用与响应式选项的标准写法。其他示例2.6-basic、2.7-basic、dependent-queries、persister、nuxt3等分别演示了旧版本 Vue 兼容、依赖查询、持久化与 Nuxt 集成等场景。完整的 API 参考与概念文档位于仓库 docs/framework/vue 目录包括 overview.md、quick-start.md、installation.md 以及 guides 下的各专题指南。【免费下载链接】query Powerful asynchronous state management, server-state utilities and data fetching for the web. TS/JS, React Query, Solid Query, Svelte Query and Vue Query.项目地址: https://gitcode.com/GitHub_Trending/qu/query创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Vue Query（@tanstack/vue-query）实战指南：Vue 应用中异步数据的获取、缓存与状态管理
Vue Querytanstack/vue-query实战指南Vue 应用中异步数据的获取、缓存与状态管理【免费下载链接】query Powerful asynchronous state management, server-state utilities and data fetching for the web. TS/JS, React Query, Solid Query, Svelte Query and Vue Query.项目地址: https://gitcode.com/GitHub_Trending/qu/queryVue Query 是 TanStack Query 生态在 Vue 侧的官方实现它为 Vue 应用提供了一套用于获取、缓存和更新异步数据的组合式 APIComposables。本指南将带你从零开始安装、初始化并在setup()中使用useQuery深入讲解其响应式选项机制与底层实现原理并覆盖无限查询、变更Mutation、预取等完整能力帮助你写出更少样板代码、更健壮的 Vue 数据层代码。安装与初始化安装包在当前仓库中Vue Query 的实现位于 packages/vue-query发布名称为tanstack/vue-query当前仓库版本为 5.102.8见 packages/vue-query/package.json。你可以使用任意主流包管理器安装$ npm i tanstack/vue-query$ pnpm add tanstack/vue-query$ yarn add tanstack/vue-query$ bun add tanstack/vue-queryVue 2.x 用户注意该包通过 vue-demi 支持 Vue 2.x。如果使用 Vue 2.6还需要额外安装并配置 vue/composition-api。从 packages/vue-query/package.json 的peerDependencies可以看到其声明为vue: ^2.6.0 || ^3.3.0且vue/composition-api为可选依赖而devDependencies中同时包含vue3、vue22.6、vue2.7测试脚本分别通过vue-demi-switch在 2 / 2.7 / 3 三种模式下运行以验证跨版本兼容性。通过 VueQueryPlugin 初始化Vue Query 通过插件Plugin形式接入应用插件的install会在应用上下文provide/inject中注入一个共享的QueryClient实例之后所有组合式函数才能工作import { createApp } from vue import { VueQueryPlugin } from tanstack/vue-query import App from ./App.vue createApp(App).use(VueQueryPlugin).mount(#app)从 packages/vue-query/src/vueQueryPlugin.ts 的源码可以看到VueQueryPlugin内部做了几件关键事情创建或复用 QueryClient若传入queryClient选项则直接使用否则用queryClientConfig新建一个QueryClient内部调用new QueryClient(clientConfig)。挂载客户端非服务端环境下调用client.mount()使缓存开始工作。支持持久化clientPersister若提供clientPersister插件会调用它拿到[unmount, promise]在持久化 Promise 完成后将client.isRestoring.value置回false并触发clientPersisterOnSuccess回调。应用卸载时清理优先注册app.onUnmount(cleanup)否则包装app.unmount方法确保调用client.unmount()与 persister 的清理函数。注入客户端Vue 3 下调用app.provide(clientKey, client)Vue 2 下通过 mixin 的beforeCreate将客户端写入_provided。可选 Devtools开发环境下若开启enableDevtoolsV6Plugin则调用setupDevtools接入调试面板。插件可配置项VueQueryPluginOptions总结如下选项类型说明queryClientQueryClient直接提供已创建的客户端实例queryClientConfigQueryClientConfig未提供queryClient时用于新建客户端的配置queryClientKeystring自定义注入键后缀生成如VUE_QUERY_CLIENT:key的键见 packages/vue-query/src/utils.ts 的getClientKeyclientPersister(client) [unmount, promise]客户端持久化函数返回卸载函数与 PromiseclientPersisterOnSuccess(client) void持久化成功后的回调enableDevtoolsV6Pluginboolean是否启用 Vue Devtools v6 插件支持第一个查询useQuery安装并注册插件后即可在任何组件的setup()中使用useQueryimport { defineComponent } from vue import { useQuery } from tanstack/vue-query export default defineComponent({ name: MyComponent, setup() { const query useQuery({ queryKey: [todos], queryFn: getTodos }) return { query, } }, })useQuery返回的对象中data、isLoading、isError、error、isFetching等状态均以Ref形式暴露模板中可自动解包setup中需要.value访问而refetch、fetchNextPage等函数则保持为普通函数。这一点可以从 packages/vue-query/src/useBaseQuery.ts 的类型定义UseBaseQueryReturnType看出除了fetchNextPage/fetchPreviousPage/refetch三个函数外其余结果字段都被包装为RefReadonlyTResult[K]。动态更新选项使用响应式变量Vue Query 是响应式驱动reactive的库——当查询选项如queryKey、enabled发生变化时查询会自动重新执行。因此如果需要动态更新查询选项必须将选项以响应式变量ref / getter的形式传入import { ref } from vue const id ref(1) const enabled ref(false) const query useQuery({ queryKey: [todos, id], queryFn: () getTodos(id), enabled, })当id.value变化时queryKey随之变化Vue Query 会感知到并触发重新获取enabled为false时查询会被禁用不发起请求但保留已有缓存。响应式选项的底层原理useQuery只是useBaseQuery(QueryObserver, options)的一层薄封装见 packages/vue-query/src/useQuery.ts。真正承载响应式逻辑的是 packages/vue-query/src/useBaseQuery.ts其核心流程为选项归一化通过computed对传入的options求值——若 options 是 getter 函数则先调用它随后用cloneDeepUnref深度克隆并解包所有 ref/getter得到纯对象再调用client.defaultQueryOptions填充默认值并设置_optimisticResults恢复期标记。创建 Observer以defaultedOptions.value实例化QueryObserver来自tanstack/query-core。状态包装默认用reactive(observer.getCurrentResult())生成响应式状态若选项shallow: true则改用shallowReactive之后通过updateState把观察者每次推送的结果合并进该状态。订阅与清理watch(defaultedOptions, updater)监听选项变化并调用observer.setOptions重新同步onScopeDispose中退订确保组件销毁后不再泄漏源码还针对在setup()或 effect scope 之外调用组合式函数的情况在开发环境打印内存泄漏警告。错误边界watch监听state.error在shouldThrowError判定为需要抛出时直接throw error配合ErrorBoundary使用。cloneDeepUnref见 packages/vue-query/src/utils.ts是响应式选项的关键工具函数它递归遍历对象遇到 ref 自动unref遇到 getter在queryKey层级自动调用取值从而让选项中的任意深度的 ref 都能被正确解包并触发依赖追踪。深入响应式为什么必须传响应式变量Vue Query 在 Vue 侧的独特设计是响应式选项 深度解包。它把所有选项放进computed中求值因此传入ref的选项如enabled、id会在 ref 变化时触发defaultedOptions重算传入 getter 函数如() ({ queryKey: [todos, id.value] })同样受支持queryKey支持数组与嵌套 ref如[todos, id]cloneDeepUnref会深度解包到最底层。这种设计与 React Query 的选项对象每次渲染重新创建不同Vue 的响应式系统让选项变化 → 查询重新执行成为声明式行为无需手动管理依赖数组。更多响应式设计细节可参考仓库文档 docs/framework/vue/reactivity.md。更丰富的查询能力并行与依赖查询useQueries当需要同时发起多个查询如动态数量的查询时使用useQueries当查询 B 依赖查询 A 的结果时可在queryFn中读取前一个查询的data形成依赖关系。无限查询与滚动加载useInfiniteQueryuseInfiniteQuery用于分页、游标与加载更多场景。从 packages/vue-query/src/useInfiniteQuery.ts 可见它同样是useBaseQuery的封装只不过观察者换成InfiniteQueryObserver。其返回结果比useQuery多了data.pages、data.pageParams、fetchNextPage、fetchPreviousPage、hasNextPage等字段配合getNextPageParam即可实现滚动分页Vue Query 还支持滚动位置恢复Scroll Recovery参考仓库示例 examples/react/load-more-infinite-scroll 与 examples/vue/2.7-basic 等目录。变更useMutation异步数据的写操作增删改通过useMutation完成。典型用法import { useMutation } from tanstack/vue-query const mutation useMutation({ mutationFn: (newTodo) axios.post(/todos, newTodo), })从 packages/vue-query/src/useMutation.ts 源码可以看到useMutation内部使用MutationObserver返回的mutate是同步触发函数内部调用observer.mutate并吞掉 Promise 拒绝以免产生未捕获异常、mutateAsync返回 Promise 以便await此外还有reset与isPending/isError/error等状态 Ref。变更成功后通常配合queryClient.invalidateQueries让相关查询失效并重新获取。全局状态助手useIsFetching()/useIsMutating()获取当前应用中正在获取/变更的查询数量可用于全局 loading 指示。useMutationState()订阅并观察 mutation 的状态列表用于乐观更新等场景。这些导出一并汇总在入口文件 packages/vue-query/src/index.ts该文件同时重导出了tanstack/query-core的全部能力QueryClient、QueryCache、MutationCache等。预取PrefetchingusePrefetchQuery与usePrefetchInfiniteQuery允许在渲染前主动将数据写入缓存配合 Suspense 可实现Fetch-As-You-Render边渲染边获取的体验。缓存、失效与重新获取Vue Query 的核心价值在于开箱即用的缓存体系主要包括自动缓存 重新获取Auto Caching Refetching基于 stale-while-revalidate 策略数据过期后在后台静默重新获取支持窗口聚焦Window Refocus时重新获取、轮询/实时刷新Polling/Realtime。多层缓存 自动垃圾回收Multi-layer Cache Garbage Collection未使用的查询在gcTime默认 5 分钟后被自动清理释放内存。请求取消Request Cancellation查询键变化或组件卸载时自动取消进行中的请求queryFn中可通过signal支持 AbortController。失效与重取queryClient.invalidateQueries({ queryKey: [...] })使指定查询失效refetchQueries直接重取setQueryData手动写入缓存。以上能力最终由tanstack/query-core提供仓库文档 docs/framework/vue/reference/QueryClient.md 提供了QueryClient的完整 API 参考。类型安全与查询选项工厂为提升类型体验Vue Query 提供了queryOptions、infiniteQueryOptions、mutationOptions三个选项工厂函数见 packages/vue-query/src/queryOptions.ts 等。它们返回带类型标注的选项对象让useQuery/useInfiniteQuery/useMutation能够自动推断data与error的类型。仓库中还配套了丰富的类型测试如 packages/vue-query/src/tests/useQuery.test-d.tsx、useInfiniteQuery.test-d.tsx并通过test:types脚本在多个 TypeScript 版本5.6/5.7/5.8/5.9/当前/7.0下做编译校验。更多 TypeScript 用法参见 docs/framework/vue/typescript.md。进阶能力与生态Suspense实验性useQuery返回对象中带有suspense()方法见useBaseQuery中的suspense实现支持 Suspense 数据流。SSR实验性支持服务端渲染场景可在服务端预取数据。Devtools提供专属调试面板安装tanstack/vue-query-devtools仓库内位于 packages/vue-query-devtools并可配合 docs/framework/vue/devtools.md 使用。持久化结合tanstack/vue-query-persist-client仓库内位于 packages/vue-query-persist-client可将查询缓存持久化到 storage。快速上手指南仓库为 Vue 提供了多个可直接运行的示例建议从 examples/vue/basic 开始它包含完整的 Vite Vue 工程与src/main.ts、src/App.vue等源码覆盖插件注册、useQuery使用与响应式选项的标准写法。其他示例2.6-basic、2.7-basic、dependent-queries、persister、nuxt3等分别演示了旧版本 Vue 兼容、依赖查询、持久化与 Nuxt 集成等场景。完整的 API 参考与概念文档位于仓库 docs/framework/vue 目录包括 overview.md、quick-start.md、installation.md 以及 guides 下的各专题指南。【免费下载链接】query Powerful asynchronous state management, server-state utilities and data fetching for the web. TS/JS, React Query, Solid Query, Svelte Query and Vue Query.项目地址: https://gitcode.com/GitHub_Trending/qu/query创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考