开发者工具 | TanStack Query React 文档

挥舞双手，欢呼雀跃吧，因为 React Query 自带了专属的开发者工具！🥳

当你开始 React Query 之旅时，你会希望这些开发者工具常伴左右。它们有助于可视化 React Query 的所有内部工作，如果你遇到困难，很可能会为你节省数小时的调试时间！

对于 Chrome、Firefox 和 Edge 用户：有第三方浏览器扩展可用于直接在浏览器 DevTools 中调试 TanStack Query。这些扩展提供了与框架特定开发者工具包相同的功能

Chrome 开发者工具

Firefox 开发者工具

Edge 开发者工具

对于 React Native 用户：有一个第三方 macOS 原生应用可用于在任何基于 js 的应用程序中调试 React Query。实时监控设备间的查询。在此查看：rn-better-dev-tools

请注意，从第 5 版开始，开发者工具也支持观察突变。

安装和导入开发者工具

开发者工具是一个单独的包，你需要安装它

bash

npm i @tanstack/react-query-devtools

npm i @tanstack/react-query-devtools

或

bash

pnpm add @tanstack/react-query-devtools

pnpm add @tanstack/react-query-devtools

或

bash

yarn add @tanstack/react-query-devtools

yarn add @tanstack/react-query-devtools

或

bash

bun add @tanstack/react-query-devtools

bun add @tanstack/react-query-devtools

对于 Next 13+ App Dir，您必须将其作为开发依赖项安装才能正常工作。

您可以像这样导入开发者工具

tsx

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

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

默认情况下，React Query Devtools 仅在 process.env.NODE_ENV === 'development' 时包含在 bundle 中，因此您无需担心在生产构建期间排除它们。

浮动模式

浮动模式将把开发者工具作为固定浮动元素挂载到您的应用中，并在屏幕角落提供一个切换按钮来显示和隐藏开发者工具。此切换状态将存储在 localStorage 中，并在重新加载时保留。

将以下代码尽可能放在您的 React 应用程序的顶部。它离页面根部越近，效果越好！

tsx

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

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      {/* The rest of your application */}
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  )
}

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

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      {/* The rest of your application */}
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  )
}

选项

initialIsOpen: 布尔值
- 如果您希望开发者工具默认打开，请将其设置为 true
buttonPosition?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "relative"
- 默认为 bottom-right
- 用于打开和关闭开发者工具面板的 React Query 标志的位置
- 如果为 relative，则按钮放置在您渲染开发者工具的位置。
position?: "top" | "bottom" | "left" | "right"
- 默认为 bottom
- React Query 开发者工具面板的位置
client?: QueryClient,
- 使用此选项可以使用自定义 QueryClient。否则，将使用最近上下文中的 QueryClient。
errorTypes?: { name: string; initializer: (query: Query) => TError}[]
- 使用此选项可以预定义一些可以在您的查询上触发的错误。当在 UI 中切换该错误时，将调用初始化器（带上特定查询）。它必须返回一个 Error。
styleNonce?: string
- 使用此项将 nonce 传递给添加到文档头部的 style 标签。如果您正在使用内容安全策略 (CSP) nonce 来允许内联样式，这将非常有用。
shadowDOMTarget?: ShadowRoot
- 默认行为会将开发者工具的样式应用到 DOM 中的 head 标签。
- 使用此选项将影子 DOM 目标传递给开发者工具，以便样式将应用于影子 DOM 中，而不是在 light DOM 的 head 标签中。

嵌入模式

嵌入模式将在您的应用程序中以固定元素的形式显示开发工具，这样您就可以在自己的开发工具中使用我们的面板。

将以下代码尽可能放在您的 React 应用程序的顶部。它离页面根部越近，效果越好！

tsx

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

function App() {
  const [isOpen, setIsOpen] = React.useState(false)

  return (
    <QueryClientProvider client={queryClient}>
      {/* The rest of your application */}
      <button
        onClick={() => setIsOpen(!isOpen)}
      >{`${isOpen ? 'Close' : 'Open'} the devtools panel`}</button>
      {isOpen && <ReactQueryDevtoolsPanel onClose={() => setIsOpen(false)} />}
    </QueryClientProvider>
  )
}

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

function App() {
  const [isOpen, setIsOpen] = React.useState(false)

  return (
    <QueryClientProvider client={queryClient}>
      {/* The rest of your application */}
      <button
        onClick={() => setIsOpen(!isOpen)}
      >{`${isOpen ? 'Close' : 'Open'} the devtools panel`}</button>
      {isOpen && <ReactQueryDevtoolsPanel onClose={() => setIsOpen(false)} />}
    </QueryClientProvider>
  )
}

选项

style?: React.CSSProperties
- 开发者工具面板的自定义样式
- 默认值：{ height: '500px' }
- 示例：{ height: '100%' }
- 示例：{ height: '100%', width: '100%' }
onClose?: () => unknown
- 开发者工具面板关闭时调用的回调函数
client?: QueryClient,
- 使用此选项可以使用自定义 QueryClient。否则，将使用最近上下文中的 QueryClient。
errorTypes?: { name: string; initializer: (query: Query) => TError}[]
- 使用此选项可以预定义一些可以在您的查询上触发的错误。当在 UI 中切换该错误时，将调用初始化器（带上特定查询）。它必须返回一个 Error。
styleNonce?: string
- 使用此项将 nonce 传递给添加到文档头部的 style 标签。如果您正在使用内容安全策略 (CSP) nonce 来允许内联样式，这将非常有用。
shadowDOMTarget?: ShadowRoot
- 默认行为会将开发者工具的样式应用到 DOM 中的 head 标签。
- 使用此选项将影子 DOM 目标传递给开发者工具，以便样式将应用于影子 DOM 中，而不是在 light DOM 的 head 标签中。

生产环境中的开发者工具

开发者工具在生产构建中被排除。然而，在生产环境中延迟加载开发者工具可能是有益的

tsx

import * as React from 'react'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
import { Example } from './Example'

const queryClient = new QueryClient()

const ReactQueryDevtoolsProduction = React.lazy(() =>
  import('@tanstack/react-query-devtools/build/modern/production.js').then(
    (d) => ({
      default: d.ReactQueryDevtools,
    }),
  ),
)

function App() {
  const [showDevtools, setShowDevtools] = React.useState(false)

  React.useEffect(() => {
    // @ts-expect-error
    window.toggleDevtools = () => setShowDevtools((old) => !old)
  }, [])

  return (
    <QueryClientProvider client={queryClient}>
      <Example />
      <ReactQueryDevtools initialIsOpen />
      {showDevtools && (
        <React.Suspense fallback={null}>
          <ReactQueryDevtoolsProduction />
        </React.Suspense>
      )}
    </QueryClientProvider>
  )
}

export default App

import * as React from 'react'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
import { Example } from './Example'

const queryClient = new QueryClient()

const ReactQueryDevtoolsProduction = React.lazy(() =>
  import('@tanstack/react-query-devtools/build/modern/production.js').then(
    (d) => ({
      default: d.ReactQueryDevtools,
    }),
  ),
)

function App() {
  const [showDevtools, setShowDevtools] = React.useState(false)

  React.useEffect(() => {
    // @ts-expect-error
    window.toggleDevtools = () => setShowDevtools((old) => !old)
  }, [])

  return (
    <QueryClientProvider client={queryClient}>
      <Example />
      <ReactQueryDevtools initialIsOpen />
      {showDevtools && (
        <React.Suspense fallback={null}>
          <ReactQueryDevtoolsProduction />
        </React.Suspense>
      )}
    </QueryClientProvider>
  )
}

export default App

这样，调用 window.toggleDevtools() 将下载开发者工具包并显示它们。

现代打包工具

如果您的打包工具支持包导出，您可以使用以下导入路径

tsx

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

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

对于 TypeScript，您需要在 tsconfig 中设置 moduleResolution: 'nodenext'，这需要至少 TypeScript v4.7。

开发工具

安装和导入开发者工具

浮动模式

选项

嵌入模式

选项

生产环境中的开发者工具

现代打包工具

想跳过文档吗？

想跳过文档吗？