开发工具

Link，拿起这把剑... 我是说 Devtools！... 来帮助你前进！

举起你的双手欢呼吧！因为 TanStack Router 自带专用的开发工具！🥳

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

安装

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

npm install -D @tanstack/react-router-devtools

npm install -D @tanstack/react-router-devtools

或

pnpm add -D @tanstack/react-router-devtools

pnpm add -D @tanstack/react-router-devtools

或

yarn add -D @tanstack/react-router-devtools

yarn add -D @tanstack/react-router-devtools

或

bun add -D @tanstack/react-router-devtools

bun add -D @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' 的环境中使用开发工具，请改用 TanStackRouterDevtoolsInProd，它具有所有相同的选项

tsx

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

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

在 RouterProvider 中使用

开发工具工作的最简单方法是在你的根路由（或任何其他路由）内部渲染它们。这将自动将开发工具连接到 router 实例。

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} />
}

手动传递 Router 实例

如果在 RouterProvider 内部渲染开发工具不是你喜欢的，devtools 的 router prop 接受你传递给 Router 组件的同一个 router 实例。这使得可以将开发工具放置在页面上的任何位置，而不仅仅是在 provider 内部

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 的位置，请导入 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 上查看此功能的实时示例。

选项

router: Router
- 要连接的 router 实例
initialIsOpen: Boolean
- 如果你希望开发工具默认打开，请将其设置为 true
panelProps: PropsObject
- 使用此选项向面板添加 props。例如，你可以添加 className、style（合并和覆盖默认样式）等。
closeButtonProps: PropsObject
- 使用此选项向关闭按钮添加 props。例如，你可以添加 className、style（合并和覆盖默认样式）、onClick（扩展默认处理程序）等。
toggleButtonProps: PropsObject
- 使用此选项向切换按钮添加 props。例如，你可以添加 className、style（合并和覆盖默认样式）、onClick（扩展默认处理程序）等。
position?: "top-left" | "top-right" | "bottom-left" | "bottom-right"
- 默认为 bottom-left
- 用于打开和关闭开发工具面板的 TanStack Router 标志的位置
shadowDOMTarget?: ShadowRoot
- 指定 devtools 的 Shadow DOM 目标。
- 默认情况下，devtool 样式应用于主文档（light DOM）的 <head> 标签。当提供 shadowDOMTarget 时，样式将应用于此 Shadow DOM 内。

嵌入模式

嵌入模式会将开发工具作为常规组件嵌入到你的应用程序中。之后你可以随意设置其样式！

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}
      />
    </>
  )
}

选项

使用这些选项来设置开发工具的样式。

style: StyleObject
- 用于使用内联样式设置组件样式的标准 React style 对象
className: string
- 用于使用类设置组件样式的标准 React className 属性

安装