开发者工具（Devtools）

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

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

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

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

React Native 用户请注意：已提供一款第三方原生 macOS 应用，可用于在任意基于 JavaScript 的应用中调试 React Query。支持跨设备实时监控查询状态。详情请见：rn-better-dev-tools

注意：自版本 5 起，开发者工具也支持观察修改（mutations）。

安装并导入开发者工具

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

1npm i @tanstack/react-query-devtools

或

1pnpm add @tanstack/react-query-devtools

或

1yarn add @tanstack/react-query-devtools

或

1bun add @tanstack/react-query-devtools

对于 Next.js 13+ 的 App 目录结构，你必须将其作为开发依赖安装，才能正常工作。

你可以按如下方式导入开发者工具：

1import { ReactQueryDevtools } from '@tanstack/react-query-devtools'

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

悬浮模式（Floating Mode）

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

请将以下代码尽可能早地放置在你的 React 应用中。越靠近页面根节点，效果越好！

1import { ReactQueryDevtools } from '@tanstack/react-query-devtools'2 3function App() {4  return (5    <QueryClientProvider client={queryClient}>6      {/* The rest of your application */}7      <ReactQueryDevtools initialIsOpen={false} />8    </QueryClientProvider>9  )10}

选项

• initialIsOpen: boolean
  • 若希望开发者工具默认处于打开状态，请设置此 true
• buttonPosition?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "relative"
  • 默认值为 bottom-right
  • 设置 TanStack 标志按钮的位置，用于打开和关闭开发者工具面板
  • 若设为 relative，则按钮将出现在你渲染开发者工具组件的位置
• position?: "top" | "bottom" | "left" | "right"
  • 默认值为 bottom
  • 设置 React Query 开发者工具面板的位置
• client?: QueryClient,
  • 使用此选项指定自定义的 QueryClient；否则将使用离当前组件最近的上下文中的 QueryClient
• errorTypes?: { name: string; initializer: (query: Query) => TError}[]
  • 使用此选项预定义一些可在查询上触发的错误。当用户在 UI 中启用该错误时，初始化器（initializer）将被调用（传入对应查询），且必须返回一个 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）

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

请将以下代码尽可能早地放置在你的 React 应用中。越靠近页面根节点，效果越好！

1import { ReactQueryDevtoolsPanel } from '@tanstack/react-query-devtools'2 3function App() {4  const [isOpen, setIsOpen] = React.useState(false)5 6  return (7    <QueryClientProvider client={queryClient}>8      {/* The rest of your application */}9      <button10        onClick={() => setIsOpen(!isOpen)}11      >{`${isOpen ? 'Close' : 'Open'} the devtools panel`}</button>12      {isOpen && <ReactQueryDevtoolsPanel onClose={() => setIsOpen(false)} />}13    </QueryClientProvider>14  )15}

选项

• style?: React.CSSProperties
  • 为开发者工具面板指定自定义样式
  • 默认值：{ height: '500px' }
  • 示例：{ height: '100%' }
  • 示例：{ height: '100%', width: '100%' }
• onClose?: () => void
  • 面板关闭时调用的回调函数
• client?: QueryClient,
  • 使用此选项指定自定义的 QueryClient；否则将使用离当前组件最近的上下文中的 QueryClient
• errorTypes?: { name: string; initializer: (query: Query) => TError}[]
  • 使用此选项预定义一些可在查询上触发的错误。当用户在 UI 中启用该错误时，初始化器（initializer）将被调用（传入对应查询），且必须返回一个 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
  • 设置此选项可更改开发者工具面板的主题，它将覆盖「设置」菜单中选定的主题

生产环境中的开发者工具

开发者工具在生产环境构建中默认被排除。但有时你可能希望在生产环境中懒加载开发者工具：

1import * as React from 'react'2import { QueryClient, QueryClientProvider } from '@tanstack/react-query'3import { ReactQueryDevtools } from '@tanstack/react-query-devtools'4import { Example } from './Example'5 6const queryClient = new QueryClient()7 8const ReactQueryDevtoolsProduction = React.lazy(() =>9  import('@tanstack/react-query-devtools/build/modern/production.js').then(10    (d) => ({11      default: d.ReactQueryDevtools,12    }),13  ),14)15 16function App() {17  const [showDevtools, setShowDevtools] = React.useState(false)18 19  React.useEffect(() => {20    // @ts-expect-error21    window.toggleDevtools = () => setShowDevtools((old) => !old)22  }, [])23 24  return (25    <QueryClientProvider client={queryClient}>26      <Example />27      <ReactQueryDevtools initialIsOpen />28      {showDevtools && (29        <React.Suspense fallback={null}>30          <ReactQueryDevtoolsProduction />31        </React.Suspense>32      )}33    </QueryClientProvider>34  )35}36 37export default App

如此，调用 window.toggleDevtools() 即可下载开发者工具资源包并显示面板。

现代打包工具

若你的打包工具支持 package exports，可使用以下导入路径：

1const ReactQueryDevtoolsProduction = React.lazy(() =>2  import('@tanstack/react-query-devtools/production').then((d) => ({3    default: d.ReactQueryDevtools,4  })),5)

对于 TypeScript，你需要在 tsconfig 中设置 moduleResolution: 'nodenext'，这要求 TypeScript 版本至少为 v4.7。