开发者工具（Devtools）

挥舞双手，大声欢呼吧，因为 Vue Query 自带专用的开发者工具！🥳

当你开启 Vue Query 之旅时，这些开发者工具将成为你不可或缺的助手。它们能直观呈现 Vue Query 的所有内部运作机制，一旦你陷入调试困境，它们很可能为你节省数小时时间！

对于 Chrome、Firefox 和 Edge 用户：已有第三方浏览器扩展，可直接在浏览器开发者工具中调试 TanStack Query。这些扩展提供的功能与框架专属的开发者工具包完全一致：

• Devtools for Chrome
• Devtools for Firefox
• Devtools for Edge

基于组件的开发者工具（Vue 3）

你可以通过专用包，将开发者工具组件直接集成到页面中。
基于组件的开发者工具采用与框架无关的实现，始终与最新版本保持同步。

该开发者工具组件是一个独立的包，需单独安装：

1npm i @tanstack/vue-query-devtools

或

1pnpm add @tanstack/vue-query-devtools

或

1yarn add @tanstack/vue-query-devtools

或

1bun add @tanstack/vue-query-devtools

默认情况下，Vue Query 开发者工具仅在 process.env.NODE_ENV === 'development' 时被包含在构建产物中，因此你无需担心在生产环境构建中手动排除它们。

悬浮模式（Floating Mode）

开发者工具将以固定悬浮元素的形式挂载到你的应用中，并在屏幕角落提供一个开关，用于显示或隐藏开发者工具面板。该开关状态会保存至 localStorage，并在页面重载后自动恢复。

请将以下代码尽可能靠近你的 Vue 应用根节点处放置——越靠近根节点，效果越好！

1<script setup>2import { VueQueryDevtools } from '@tanstack/vue-query-devtools'3</script>4 5<template>6  <h1>The app!</h1>7  <VueQueryDevtools />8</template>

选项

• initialIsOpen: boolean
  • 若希望开发者工具默认处于打开状态，请设置此 true。
• buttonPosition?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "relative"
  • 默认值为 bottom-right。
  • 设置 TanStack 标志在页面上的位置，用于打开和关闭开发者工具面板。
• position?: "top" | "bottom" | "left" | "right"
  • 默认值为 bottom。
  • 设置 Vue Query 开发者工具面板在页面上的位置。
• client?: QueryClient
  • 使用此选项指定自定义的 QueryClient；否则将使用最近上下文中的 QueryClient。
• errorTypes?: { name: string; initializer: (query: Query) => TError}[]
  • 使用此选项预定义一些可在查询上触发的错误。当用户在 UI 中启用该错误时，初始化器函数（接收对应查询作为参数）会被调用，且必须返回一个 Error 实例。
• styleNonce?: string
  • 使用此选项向插入文档 head 的 style 标签传递 nonce。若你启用了内容安全策略（CSP）并依赖 nonce 允许内联样式，则此选项十分有用。
• shadowDOMTarget?: ShadowRoot
  • 默认行为是将开发者工具的样式注入 DOM 的 head 标签中。
  • 使用此选项可向开发者工具传入 shadow DOM 目标，使样式被注入 shadow DOM 内部，而非 light DOM 的 head 标签中。
• hideDisabledQueries?: boolean
  • 默认值为 false。
  • 设为 true 可在开发者工具面板中隐藏已禁用的查询。
• theme?: "light" | "dark" | "system"
  • 默认值为开发者工具「设置」菜单中选定的主题；若未选择主题，则默认为 system。
  • 设置此选项可更改开发者工具面板的主题，它将覆盖「设置」菜单中选定的主题。

嵌入模式（Embedded Mode）

嵌入模式会将开发者工具以固定元素形式显示在你的应用中，以便你将我们的面板集成进自己的开发工具界面。

请将以下代码尽可能靠近你的 Vue 应用根节点处放置——越靠近根节点，效果越好！

1<script setup>2import { ref } from 'vue'3import { VueQueryDevtoolsPanel } from '@tanstack/vue-query-devtools'45const isOpen = ref(false)6</script>7 8<template>9  <h1>The app!</h1>10  <button @click="isOpen = !isOpen">11    {{ isOpen ? 'Close' : 'Open' }} the devtools panel12  </button>13  <VueQueryDevtoolsPanel v-if="isOpen" :onClose="() => (isOpen = false)" />14</template>

选项

• style?: Partial<CSSStyleDeclaration>
  • 为开发者工具面板指定自定义样式
  • 默认值：{ height: '500px' }
  • 示例：{ height: '100%' }
  • 示例：{ height: '100%', width: '100%' }
• onClose?: () => void
  • 当开发者工具面板关闭时调用的回调函数
• client?: QueryClient
  • 使用此选项指定自定义的 QueryClient；否则将使用最近上下文中的 QueryClient。
• errorTypes?: { name: string; initializer: (query: Query) => TError}[]
  • 使用此选项预定义一些可在查询上触发的错误。当用户在 UI 中启用该错误时，初始化器函数（接收对应查询作为参数）会被调用，且必须返回一个 Error 实例。
• styleNonce?: string
  • 使用此选项向插入文档 head 的 style 标签传递 nonce。若你启用了内容安全策略（CSP）并依赖 nonce 允许内联样式，则此选项十分有用。
• shadowDOMTarget?: ShadowRoot
  • 默认行为是将开发者工具的样式注入 DOM 的 head 标签中。
  • 使用此选项可向开发者工具传入 shadow DOM 目标，使样式被注入 shadow DOM 内部，而非 light DOM 的 head 标签中。
• hideDisabledQueries?: boolean
  • 默认值为 false。
  • 设为 true 可在开发者工具面板中隐藏已禁用的查询。
• theme?: "light" | "dark" | "system"
  • 默认值为开发者工具「设置」菜单中选定的主题；若未选择主题，则默认为 system。
  • 设置此选项可更改开发者工具面板的主题，它将覆盖「设置」菜单中选定的主题。

传统开发者工具（Traditional Devtools）

Vue Query 将无缝集成 官方 Vue 开发者工具，添加自定义检查器（inspector）和时间线事件（timeline events）。
开发者工具代码默认会在生产环境构建中被自动移除（tree-shaken）。

要启用该功能，你只需在插件选项中开启即可：

1app.use(VueQueryPlugin, {2  enableDevtoolsV6Plugin: true,3})

v6 和 v7 版本的开发者工具均受支持。