开发者工具（Devtools）

更新于 2026-11-02 Angular 查看英文原文 ↗

Chrome、Firefox 和 Edge 用户请注意：第三方浏览器扩展可用于直接在浏览器开发者工具（DevTools）中调试 TanStack Query。这些扩展提供的功能与框架专用的 devtools 包完全相同：

Devtools for Chrome

Devtools for Firefox

Devtools for Edge

启用开发者工具

开发者工具可帮助你调试和检查查询与修改。你可通过在 provideTanStackQuery 中添加 withDevtools 来启用开发者工具。

默认情况下，Angular Query 开发者工具仅包含在开发模式构建包中，因此你无需担心在生产环境构建时将其排除。

TypeScript

1import {2  QueryClient,3  provideTanStackQuery,4} from '@tanstack/angular-query-experimental'5 6import { withDevtools } from '@tanstack/angular-query-experimental/devtools'7 8export const appConfig: ApplicationConfig = {9  providers: [provideTanStackQuery(new QueryClient(), withDevtools())],10}

生产环境中的开发者工具

开发者工具会自动从生产环境构建包中排除。但有时你可能希望在生产环境中按需加载开发者工具。

若要在生产环境构建中使用 withDevtools，请通过 production 子路径导入。该子路径导出的函数与主路径函数完全一致，但不会被排除出生产环境构建。

TypeScript

1import { withDevtools } from '@tanstack/angular-query-experimental/devtools/production'

你可以使用 loadDevtools 选项来控制开发者工具的加载时机。

当不设置该选项或将其设为 'auto' 时，开发者工具仅在 Angular 处于开发模式下自动加载。

TypeScript

1import { withDevtools } from '@tanstack/angular-query-experimental/devtools'2 3provideTanStackQuery(new QueryClient(), withDevtools())4 5// which is equivalent to6provideTanStackQuery(7  new QueryClient(),8  withDevtools(() => ({ loadDevtools: 'auto' })),9)

当将该选项设为 true 时，开发者工具将在开发和生产两种模式下均被加载。

如果你希望基于 Angular 环境配置加载开发者工具，此设置非常有用。例如，当应用运行在你的生产构建预发布环境（staging environment）时，可将此选项设为 true。

TypeScript

1import { environment } from './environments/environment'2// Make sure to use the production sub-path to load devtools in production builds3import { withDevtools } from '@tanstack/angular-query-experimental/devtools/production'4 5provideTanStackQuery(6  new QueryClient(),7  withDevtools(() => ({ loadDevtools: environment.loadDevtools })),8)

当将该选项设为 false 时，开发者工具将不会被加载。

TypeScript

1provideTanStackQuery(2  new QueryClient(),3  withDevtools(() => ({ loadDevtools: false })),4)

通过响应式机制派生选项

为支持通过信号（signals）实现响应式，选项通过回调函数传入 withDevtools。以下示例中，从一个在键盘快捷键触发时发出值的 RxJS Observable 创建了一个信号。当该派生信号被设为 true 时，开发者工具将被按需懒加载。

以下示例在开发模式下始终加载开发者工具；在生产模式下，则仅在按下键盘快捷键时按需加载。

TypeScript

1import { Injectable, isDevMode } from '@angular/core'2import { fromEvent, map, scan } from 'rxjs'3import { toSignal } from '@angular/core/rxjs-interop'4 5@Injectable({ providedIn: 'root' })6export class DevtoolsOptionsManager {7  loadDevtools = toSignal(8    fromEvent<KeyboardEvent>(document, 'keydown').pipe(9      map(10        (event): boolean =>11          event.metaKey && event.ctrlKey && event.shiftKey && event.key === 'D',12      ),13      scan((acc, curr) => acc || curr, isDevMode()),14    ),15    {16      initialValue: isDevMode(),17    },18  )19}

若你希望在回调函数中使用可注入对象（如服务），可使用 deps。注入的值将作为参数传递给回调函数。

这与 Angular 的 useFactory 提供器中的 deps 类似。

TypeScript

1// ...2// 👇 Note we import from the production sub-path to enable devtools lazy loading in production builds3import { withDevtools } from '@tanstack/angular-query-experimental/devtools/production'4 5export const appConfig: ApplicationConfig = {6  providers: [7    provideHttpClient(),8    provideTanStackQuery(9      new QueryClient(),10      withDevtools(11        (devToolsOptionsManager: DevtoolsOptionsManager) => ({12          loadDevtools: devToolsOptionsManager.loadDevtools(),13        }),14        {15          // `deps` is used to inject and pass `DevtoolsOptionsManager` to the `withDevtools` callback.16          deps: [DevtoolsOptionsManager],17        },18      ),19    ),20  ],21}

回调函数返回的选项

以下选项支持通过信号实现响应式：loadDevtools、client、position、errorTypes、buttonPosition、initialIsOpen 和 theme。

loadDevtools?: 'auto' | boolean
- 默认值为 auto：在开发模式下懒加载开发者工具；在生产模式下跳过加载。
- 使用此选项控制是否加载开发者工具。
initialIsOpen?: Boolean
- 若希望工具默认处于打开状态，请将此项设为 true。
buttonPosition?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "relative"
- 默认值为 bottom-right。
- TanStack 标志按钮的位置，用于打开和关闭开发者工具面板。
- 若设为 relative，则按钮将置于你渲染开发者工具的 DOM 位置。
position?: "top" | "bottom" | "left" | "right"
- 默认值为 bottom。
- Angular Query 开发者工具面板的位置。
client?: QueryClient,
- 使用此选项指定自定义的 QueryClient；否则将注入通过 provideTanStackQuery 提供的 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）

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

使用 injectDevtoolsPanel 将开发者工具面板渲染到组件的某个元素内。与 withDevtools 一样，它也仅包含在开发模式构建包中。若要在生产环境构建中使用，请从 @tanstack/angular-query-experimental/devtools-panel/production 导入。

angular-ts

1import { Component, signal, viewChild } from '@angular/core'2import { injectDevtoolsPanel } from '@tanstack/angular-query-experimental/devtools-panel'3import type { ElementRef } from '@angular/core'4 5@Component({6  selector: 'app-root',7  template: `8    <button type="button" (click)="isOpen.set(!isOpen())">9      {{ isOpen() ? 'Close' : 'Open' }} the devtools panel10    </button>11    @if (isOpen()) {12      <div #div style="height: 500px"></div>13    }14  `,15})16export class AppComponent {17  readonly isOpen = signal(false)18  readonly divEl = viewChild<ElementRef>('div')19 20  readonly devtools = injectDevtoolsPanel(() => ({21    hostElement: this.divEl(),22    onClose: () => this.isOpen.set(false),23  }))24}

injectDevtoolsPanel 必须在注入上下文（injection context）中调用，或通过其第二个参数的 injector 选项显式传入 Injector：injectDevtoolsPanel(() => ({ ... }), { injector })。

选项

以下选项支持通过信号实现响应式：hostElement、client、errorTypes、onClose 和 theme。

hostElement?: ElementRef
- 渲染开发者工具面板的目标元素。当其值为 undefined 或 null 时，开发者工具面板将不会被创建，或若已存在则会被销毁。
onClose?: () => void
- 当开发者工具面板关闭时调用的回调函数。
client?: QueryClient,
- 使用此选项指定自定义的 QueryClient；否则将注入通过 provideTanStackQuery 提供的 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。
- 设置此项可更改开发者工具面板的主题，它将覆盖“设置”菜单中选定的主题。