Devtools
挥动你的双手，欢呼吧，因为 React Query 自带了专门的 devtools！🥳
当你开始你的 React Query 之旅时，你会希望这些 devtools 在你身边。它们帮助可视化 React Query 的所有内部运作，并且如果你发现自己陷入困境，它们可能会为你节省数小时的调试时间！
请注意，目前 devtools **不支持 React Native**。如果您想帮助我们使 devtools 成为平台无关的，请告诉我们！
激动人心的消息：我们现在为 React Native React Query DevTools 提供了一个单独的包！这个新添加的功能带来了原生支持，允许您将 DevTools 直接集成到您的 React Native 项目中。查看并在此处贡献： react-native-react-query-devtools
还有一个外部工具可用，可以通过外部仪表板启用 React Query DevTools 的使用。在 react-query-external-sync 上了解更多信息并贡献
请注意，自版本 5 以来，devtools 也支持观察 mutations (突变)。
安装和导入 Devtools
devtools 是一个单独的包，您需要安装它
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，您必须将其作为开发依赖项安装才能使其工作。
您可以像这样导入 devtools
tsx
import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
默认情况下，React Query Devtools 仅在 process.env.NODE_ENV === 'development' 时包含在 bundle 中，因此您无需担心在生产构建期间排除它们。
浮动模式
浮动模式会将 devtools 作为固定的浮动元素挂载到您的应用程序中，并在屏幕的角落提供一个切换按钮来显示和隐藏 devtools。此切换状态将被存储并记录在 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: Boolean (初始打开状态：布尔值)
- 如果您希望 devtools 默认打开，请将此项设置为 true
- buttonPosition?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "relative" (按钮位置？：“左上” | “右上” | “左下” | “右下” | “相对”)
- 默认为 bottom-right (右下)
- React Query 徽标的位置，用于打开和关闭 devtools 面板
- 如果为 relative (相对)，则按钮放置在您渲染 devtools 的位置。
- position?: "top" | "bottom" | "left" | "right" (位置？：“顶部” | “底部” | “左侧” | “右侧”)
- 默认为 bottom (底部)
- React Query devtools 面板的位置
- client?: QueryClient (客户端？：QueryClient),
- 使用此项以使用自定义 QueryClient。否则，将使用来自最近上下文的 QueryClient。
- errorTypes?: { name: string; initializer: (query: Query) => TError}[] (错误类型？：{ name: 字符串; initializer: (query: Query) => TError}[])
- 使用此项来预定义一些可以在您的查询上触发的错误。当从 UI 上切换该错误时，将调用 Initializer（使用特定的查询）。它必须返回一个 Error。
- styleNonce?: string (样式随机数？：字符串)
- 使用此项将随机数传递给添加到文档 head 中的 style 标签。如果您正在使用内容安全策略 (CSP) 随机数来允许内联样式，这将非常有用。
- shadowDOMTarget?: ShadowRoot (shadowDOM 目标？：ShadowRoot)
- 默认行为会将 devtool 的样式应用于 DOM 中的 head 标签。
- 使用此项将 shadow DOM 目标传递给 devtools，以便样式将应用于 shadow 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 (样式？：React.CSSProperties)
- devtools 面板的自定义样式
- 默认值： { height: '500px' }
- 示例： { height: '100%' }
- 示例： { height: '100%', width: '100%' }
- onClose?: () => unknown (onClose？：() => unknown)
- 当 devtools 面板关闭时调用的回调函数
- client?: QueryClient (客户端？：QueryClient),
- 使用此项以使用自定义 QueryClient。否则，将使用来自最近上下文的 QueryClient。
- errorTypes?: { name: string; initializer: (query: Query) => TError}[] (错误类型？：{ name: 字符串; initializer: (query: Query) => TError}[])
- 使用此项来预定义一些可以在您的查询上触发的错误。当从 UI 上切换该错误时，将调用 Initializer（使用特定的查询）。它必须返回一个 Error。
- styleNonce?: string (样式随机数？：字符串)
- 使用此项将随机数传递给添加到文档 head 中的 style 标签。如果您正在使用内容安全策略 (CSP) 随机数来允许内联样式，这将非常有用。
- shadowDOMTarget?: ShadowRoot (shadowDOM 目标？：ShadowRoot)
- 默认行为会将 devtool 的样式应用于 DOM 中的 head 标签。
- 使用此项将 shadow DOM 目标传递给 devtools，以便样式将应用于 shadow DOM 内，而不是 light DOM 中的 head 标签内。
生产环境中的 Devtools
Devtools 在生产构建中被排除。但是，可能希望在生产环境中延迟加载 devtools
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() 将下载 devtools bundle 并显示它们。
现代打包器
如果您的打包器支持包导出，则可以使用以下导入路径
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。
