开发工具 | TanStack Router React Docs

Link，拿着这把剑...我是说开发工具！...来帮助你前进！

挥舞你的双手并大声欢呼，因为 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

导入开发工具

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

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

在生产环境中使用开发工具

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

tsx

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

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

在 RouterProvider 内部使用

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

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

手动传递路由器实例

如果在 RouterProvider 内部渲染开发工具不符合您的喜好，开发工具的 router 属性接受与您传递给 Router 组件相同的 router 实例。这使得可以将开发工具放置在页面的任何位置，而不仅仅是在提供程序内部：

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

开发工具选项

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

固定模式

要控制开发工具的位置，请导入 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 中查看此示例的实时演示。

嵌入模式

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

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
- 处理开发工具面板的打开和关闭。
shadowDOMTarget?: ShadowRoot
- 为开发工具指定 Shadow DOM 目标。
- 默认情况下，开发工具样式应用于主文档（light DOM）的 <head> 标签。当提供 shadowDOMTarget 时，样式将应用于此 Shadow DOM 内部。