开发者工具（Devtools）

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

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

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

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

安装并导入开发者工具

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

1npm i @tanstack/preact-query-devtools

或

1pnpm add @tanstack/preact-query-devtools

或

1yarn add @tanstack/preact-query-devtools

或

1bun add @tanstack/preact-query-devtools

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

1import { PreactQueryDevtools } from '@tanstack/preact-query-devtools'

默认情况下，Preact Query 开发者工具仅在 process.env.NODE_ENV === 'development' 时被包含在构建产物中，因此你无需担心其在生产环境构建中被意外引入。

悬浮模式（Floating Mode）

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

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

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

选项

• initialIsOpen: boolean
  • 若希望开发者工具默认处于打开状态，请设置此 true
• buttonPosition?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "relative"
  • 默认值为 bottom-right
  • 设置 TanStack 标志的位置，用于打开或关闭开发者工具面板
• position?: "top" | "bottom" | "left" | "right"
  • 默认值为 bottom
  • 设置 Preact 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）

嵌入模式会将开发工具作为应用内的一个固定元素展示，以便你将我们的面板集成进自己的开发工具中。

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

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

选项

• style?: 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
  • 设置此选项可更改开发者工具面板的主题，它将覆盖“设置”菜单中选定的主题