Devtools | TanStack Router React 文档

链接，拿起这把剑……我是说 Devtools！……来帮助你前进！

挥舞双手，高喊万岁，因为 TanStack Router 提供了专用的开发工具！🥳

当你开始你的 TanStack Router 之旅时，你会希望这些开发工具在你身边。它们有助于可视化 TanStack Router 的所有内部工作原理，如果你陷入困境，它们可能会为你节省数小时的调试时间！

安装

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

npm install @tanstack/react-router-devtools

npm install @tanstack/react-router-devtools

或

pnpm add @tanstack/react-router-devtools

pnpm add @tanstack/react-router-devtools

或

yarn add @tanstack/react-router-devtools

yarn add @tanstack/react-router-devtools

或

bun add @tanstack/react-router-devtools

bun add @tanstack/react-router-devtools

导入 Devtools

import { TanStackRouterDevtools } from '@tanstack/react-router-devtools'

import { TanStackRouterDevtools } from '@tanstack/react-router-devtools'

在生产环境中使用 Devtools

如果将 Devtools 导入为 TanStackRouterDevtools，它将不会在生产环境中显示。如果你想在 process.env.NODE_ENV === 'production' 的环境中使用 devtools，请改用 TanStackRouterDevtoolsInProd，它具有所有相同的选项

tsx

import { TanStackRouterDevtoolsInProd } from '@tanstack/react-router-devtools'

import { TanStackRouterDevtoolsInProd } from '@tanstack/react-router-devtools'

在 RouterProvider 内部使用

Devtools 最简单的工作方式是将其渲染到你的根路由（或任何其他路由）内部。这将自动将 Devtools 连接到路由实例。

tsx

const rootRoute = createRootRoute({
  component: () => (
    <>
      <Outlet />
      <TanStackRouterDevtools />
    </>
  ),
})

const routeTree = rootRoute.addChildren([
  // ... other routes
])

const router = createRouter({
  routeTree,
})

function App() {
  return <RouterProvider router={router} />
}

const rootRoute = createRootRoute({
  component: () => (
    <>
      <Outlet />
      <TanStackRouterDevtools />
    </>
  ),
})

const routeTree = rootRoute.addChildren([
  // ... other routes
])

const router = createRouter({
  routeTree,
})

function App() {
  return <RouterProvider router={router} />
}

手动传递路由实例

如果将 devtools 渲染到 RouterProvider 内部不是你的菜，那么 devtools 的 router prop 接受你传递给 Router 组件的相同 router 实例。这使得可以将 devtools 放置在页面上的任何位置，而不仅仅是提供者内部

tsx

function App() {
  return (
    <>
      <RouterProvider router={router} />
      <TanStackRouterDevtools router={router} />
    </>
  )
}

function App() {
  return (
    <>
      <RouterProvider router={router} />
      <TanStackRouterDevtools router={router} />
    </>
  )
}

浮动模式

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

将以下代码尽可能高地放置在你的 React 应用程序中。它越靠近页面的根部，它就越能正常工作！

import { TanStackRouterDevtools } from '@tanstack/react-router-devtools'

function App() {
  return (
    <>
      <Router />
      <TanStackRouterDevtools initialIsOpen={false} />
    </>
  )
}

import { TanStackRouterDevtools } from '@tanstack/react-router-devtools'

function App() {
  return (
    <>
      <Router />
      <TanStackRouterDevtools initialIsOpen={false} />
    </>
  )
}

Devtools 选项

router: Router
- 要连接的路由实例。
initialIsOpen: 布尔值
- 如果你希望 devtools 默认打开，请将其设置为 true。
panelProps: PropsObject
- 使用它向面板添加 prop。例如，你可以添加 className、style（合并并覆盖默认样式）等。
closeButtonProps: PropsObject
- 使用它向关闭按钮添加 prop。例如，你可以添加 className、style（合并并覆盖默认样式）、onClick（扩展默认处理程序）等。
toggleButtonProps: PropsObject
- 使用它向切换按钮添加 prop。例如，你可以添加 className、style（合并并覆盖默认样式）、onClick（扩展默认处理程序）等。
position?: "top-left" | "top-right" | "bottom-left" | "bottom-right"
- 默认为 bottom-left。
- 用于打开和关闭 devtools 面板的 TanStack Router 标志的位置。
shadowDOMTarget?: ShadowRoot
- 为 devtools 指定一个 Shadow DOM 目标。
- 默认情况下，devtools 样式应用于主文档的 <head> 标签（light DOM）。当提供 shadowDOMTarget 时，样式将应用于此 Shadow DOM 内部。
containerElement?: string | any
- 使用它将 devtools 渲染到不同类型的容器元素中，以实现辅助功能。
- 允许任何与有效内在 JSX 元素对应的字符串。
- 默认为 'footer'。

固定模式

要控制 devtools 的位置，请导入 TanStackRouterDevtoolsPanel

import { TanStackRouterDevtoolsPanel } from '@tanstack/react-router-devtools'

import { TanStackRouterDevtoolsPanel } from '@tanstack/react-router-devtools'

然后可以将其附加到提供的 shadow DOM 目标。

<TanStackRouterDevtoolsPanel
  shadowDOMTarget={shadowContainer}
  router={router}
/>

<TanStackRouterDevtoolsPanel
  shadowDOMTarget={shadowContainer}
  router={router}
/>

点击此处在 StackBlitz 中查看此内容的实时示例。

嵌入模式

嵌入模式将把 devtools 作为普通组件嵌入到你的应用程序中。之后你可以随意设置它的样式！

import { TanStackRouterDevtoolsPanel } from '@tanstack/react-router-devtools'

function App() {
  return (
    <>
      <Router router={router} />
      <TanStackRouterDevtoolsPanel
        router={router}
        style={styles}
        className={className}
      />
    </>
  )
}

import { TanStackRouterDevtoolsPanel } from '@tanstack/react-router-devtools'

function App() {
  return (
    <>
      <Router router={router} />
      <TanStackRouterDevtoolsPanel
        router={router}
        style={styles}
        className={className}
      />
    </>
  )
}

DevtoolsPanel 选项

router: Router
- 要连接的路由实例。
style: StyleObject
- 用于使用内联样式设置组件样式的标准 React 样式对象。
className: string
- 用于使用类设置组件样式的标准 React className 属性。
isOpen?: boolean
- 一个布尔变量，指示面板是打开还是关闭。
setIsOpen?: (isOpen: boolean) => void
- 一个用于切换面板打开和关闭状态的函数。
handleDragStart?: (e: any) => void
- 处理 devtools 面板的打开和关闭。
shadowDOMTarget?: ShadowRoot
- 为 devtools 指定一个 Shadow DOM 目标。
- 默认情况下，devtools 样式应用于主文档的 <head> 标签（light DOM）。当提供 shadowDOMTarget 时，样式将应用于此 Shadow DOM 内部。

开发工具

安装