TanStackRouter v1
自动
框架
版本
菜单
入门
路由
指南
API
ESLint
路由示例

类型安全

TanStack Router 在 TypeScript 编译器和运行时的限制内构建得尽可能类型安全。这意味着它不仅用 TypeScript 编写，而且还完全推断提供给它的类型，并顽强地将它们传递到整个路由体验中。

最终，这意味着您作为开发者编写更少的类型，并且随着代码的发展对代码更有信心。

路由定义

基于文件的路由

路由是分层的，它们的定义也是如此。如果您使用基于文件的路由，大部分类型安全已经为您处理好了。

基于代码的路由

如果您直接使用 Route 类，您需要了解如何使用 Route 的 getParentRoute 选项确保您的路由正确类型化。这是因为子路由需要了解所有父路由的类型。没有这个，您从 3 层以上的 layout 和 pathless layout 路由中解析出的那些宝贵的搜索参数将丢失到 JS 虚空中。

所以，不要忘记将父路由传递给您的子路由！

tsx
const parentRoute = createRoute({
  getParentRoute: () => parentRoute,
})

const parentRoute = createRoute({
  getParentRoute: () => parentRoute,
})

导出的钩子、组件和工具

为了让您的路由器类型与顶级导出（如 Link、useNavigate、useParams ���）一起工作，它们必须渗透 TypeScript 模块边界并直接注册到库中。为此，我们在导出的 Register 接口上使用声明合并。

ts
const router = createRouter({
  // ...
})

declare module '@tanstack/react-router' {
  interface Register {
    router: typeof router
  }
}

const router = createRouter({
  // ...
})

declare module '@tanstack/react-router' {
  interface Register {
    router: typeof router
  }
}

通过将您的路由器注册到模块中，您现在可以使用导出的钩子、组件和工具以及您路由器的确切类型。

修复组件上下文问题

组件上下文是 React 和其他框架中为组件提供依赖项的绝佳工具。但是，如果该上下文在组件层次结构中移动时类型发生变化，TypeScript 就无法知道如何推断这些变化。为了解决这个问题，基于上下文的钩子和组件需要您提示它们如何以及在何处使用。

tsx
export const Route = createFileRoute('/posts')({
  component: PostsComponent,
})

function PostsComponent() {
  // 每个路由都有来自 TanStack Router 的大多数内置钩子的类型安全版本
  const params = Route.useParams()
  const search = Route.useSearch()

  // 一些钩子需要来自*整个*路由器的上下文，而不仅仅是当前路由。为了在这里实现类型安全，
  // 我们必须传递 `from` 参数来告诉钩子我们在路由层次结构中的相对位置。
  const navigate = useNavigate({ from: Route.fullPath })
  // ... 等等
}

export const Route = createFileRoute('/posts')({
  component: PostsComponent,
})

function PostsComponent() {
  // 每个路由都有来自 TanStack Router 的大多数内置钩子的类型安全版本
  const params = Route.useParams()
  const search = Route.useSearch()

  // 一些钩子需要来自*整个*路由器的上下文，而不仅仅是当前路由。为了在这里实现类型安全，
  // 我们必须传递 `from` 参数来告诉钩子我们在路由层次结构中的相对位置。
  const navigate = useNavigate({ from: Route.fullPath })
  // ... 等等
}

每个需要上下文提示的钩子和组件都有一个 from 参数，您可以在其中传递正在渲染的路由的 ID 或路径。

🧠 快速提示：如果您的组件是代码分割的，您可以使用 getRouteApi 函数 来避免必须传入 Route.fullPath 以获得对类型化的 useParams() 和 useSearch() 钩子的访问。

如果我不知道路由怎么办？如果它是共享组件怎么办？

from 属性是可选的，这意味着如果您不传递它，您将得到路由器对可用类型的最佳猜测。通常，这意味着您将得到路由器中所有路由的所有类型的联合。

如果我传递了错误的 from 路径怎么办？

技术上可以传递一个满足 TypeScript 的 from，但可能与您在运行时实际渲染的路由不匹配。在这种情况下，每个支持 from 的钩子和组件都会检测您的期望是否与您实际渲染的路由不匹配，并会抛出运行时错误。

如果我不知道路由，或者它是共享组件，并且我不能传递 from 怎么办？

如果您正在渲染一个在多个路由之间共享的组件，或者您正在渲染一个不在路由内的组件，您可以传递 strict: false 而不是 from 选项。这不仅会消除运行时错误，还会为您正在调用的潜在钩子提供宽松但准确的类型。一个很好的例子是从共享组件调用 useSearch：

tsx
function MyComponent() {
  const search = useSearch({ strict: false })
}

function MyComponent() {
  const search = useSearch({ strict: false })
}

在这种情况下，search 变量将被类型化为路由器中所有路由的所有可能搜索参数的联合。

路由器上下文

路由器上下文非常有用，因为它是终极的分层依赖注入。您可以为路由器以及它渲染的每个路由提供上下文。当您构建此上下文时，TanStack Router 会将其与路由层次结构合并，以便每个路由都可以访问其所有父级的上下文。

createRootRouteWithContext 工厂使用实例化的类型创建一个新的路由器，然后要求您履行对路由器的相同类型契约，并且还将确保您的上下文在整个路由树中正确类型化。

tsx
const rootRoute = createRootRouteWithContext<{ whateverYouWant: true }>()({
  component: App,
})

const routeTree = rootRoute.addChildren([
  // ... 所有子路由都将在其上下文中访问 `whateverYouWant`
])

const router = createRouter({
  routeTree,
  context: {
    // 现在需要传递这个
    whateverYouWant: true,
  },
})

const rootRoute = createRootRouteWithContext<{ whateverYouWant: true }>()({
  component: App,
})

const routeTree = rootRoute.addChildren([
  // ... 所有子路由都将在其上下文中访问 `whateverYouWant`
])

const router = createRouter({
  routeTree,
  context: {
    // 现在需要传递这个
    whateverYouWant: true,
  },
})

性能建议

随着应用程序的扩展，TypeScript 检查时间自然会增加。当您的应用程序扩展时，有几件事需要记住以保持 TS 检查时间较短。

只推断您需要的类型

客户端数据缓存（TanStack Query 等）的一个很好的模式是预取数据。例如，使用 TanStack Query，您可能有一个在 loader 中调用 queryClient.ensureQueryData 的路由。

tsx
export const Route = createFileRoute('/posts/$postId/deep')({
  loader: ({ context: { queryClient }, params: { postId } }) =>
    queryClient.ensureQueryData(postQueryOptions(postId)),
  component: PostDeepComponent,
})

function PostDeepComponent() {
  const params = Route.useParams()
  const data = useSuspenseQuery(postQueryOptions(params.postId))

  return <></>
}

export const Route = createFileRoute('/posts/$postId/deep')({
  loader: ({ context: { queryClient }, params: { postId } }) =>
    queryClient.ensureQueryData(postQueryOptions(postId)),
  component: PostDeepComponent,
})

function PostDeepComponent() {
  const params = Route.useParams()
  const data = useSuspenseQuery(postQueryOptions(params.postId))

  return <></>
}

这可能看起来很好，对于小的路由树，您可能不会注意到任何 TS 性能问题。但是在这种情况下，TS 必须推断加载器的返回类型，尽管它从未在您的路由中使用过���如果加载器数据是一个复杂的类型，有许多以这种方式预取的路由，它可能会减慢编辑器性能。在这种情况下，更改非常简单，让 TypeScript 推断 Promise。

tsx
export const Route = createFileRoute('/posts/$postId/deep')({
  loader: async ({ context: { queryClient }, params: { postId } }) => {
    await queryClient.ensureQueryData(postQueryOptions(postId))
  },
  component: PostDeepComponent,
})

function PostDeepComponent() {
  const params = Route.useParams()
  const data = useSuspenseQuery(postQueryOptions(params.postId))

  return <></>
}

export const Route = createFileRoute('/posts/$postId/deep')({
  loader: async ({ context: { queryClient }, params: { postId } }) => {
    await queryClient.ensureQueryData(postQueryOptions(postId))
  },
  component: PostDeepComponent,
})

function PostDeepComponent() {
  const params = Route.useParams()
  const data = useSuspenseQuery(postQueryOptions(params.postId))

  return <></>
}

这样，加载器数据永远不会被推断，它将推断从路由树移动到您第一次使用 useSuspenseQuery 时。

尽可能缩小到相关路由

考虑以下 Link 的使用

tsx
<Link to=".." search={{ page: 0 }} />
<Link to="." search={{ page: 0 }} />

<Link to=".." search={{ page: 0 }} />
<Link to="." search={{ page: 0 }} />

这些示例对 TS 性能不利。这是因为 search 解析为所有路由的所有 search 参数的联合，TS 必须检查您传递给 search 属性的任何内容与这个可能很大的联合。随着应用程序的增长，此检查时间将与路由数量和搜索参数数量成线性增长。我们已经尽力为这种情况进行优化（TypeScript 通常会执行一次此工作并缓存它），但对这个大联合的初始检查是昂贵的。这也适用于 params 和其他 API，如 useSearch、useParams、useNavigate 等。

相反，您应该尝试使用 from 或 to 缩小到相关路由。

tsx
<Link from={Route.fullPath} to=".." search={{page: 0}} />
<Link from="/posts" to=".." search={{page: 0}} />

<Link from={Route.fullPath} to=".." search={{page: 0}} />
<Link from="/posts" to=".." search={{page: 0}} />

记住，您始终可以将联合传递给 to 或 from 以缩小您感兴趣的路由。

tsx
const from: '/posts/$postId/deep' | '/posts/' = '/posts/'
<Link from={from} to='..' />

const from: '/posts/$postId/deep' | '/posts/' = '/posts/'
<Link from={from} to='..' />

您还可以将分支传递给 from，以仅将 search 或 params 解析为来自该分支的任何后代：

tsx
const from = '/posts'
<Link from={from} to='..' />

const from = '/posts'
<Link from={from} to='..' />

/posts 可能是一个有许多后代的分支，它们共享相同的 search 或 params

考虑使用 addChildren 的对象语法

路由通常具有 params、search、loaders 或 context，甚至可以引用外部依赖项，这些依赖项在 TS 推断上也很重。对于此类应用程序，使用对象创建路由树可能比元组更高效。

createChildren 也可以接受对象。对于具有复杂路由和外部库的大型路由树，与大型元组相比，对象对于 TS 进行类型检查可能要快得多。性能提升取决于您的项目、您拥有的外部依赖项以及这些库的类型是如何编写的

tsx
const routeTree = rootRoute.addChildren({
  postsRoute: postsRoute.addChildren({ postRoute, postsIndexRoute }),
  indexRoute,
})

const routeTree = rootRoute.addChildren({
  postsRoute: postsRoute.addChildren({ postRoute, postsIndexRoute }),
  indexRoute,
})

请注意，此语法更冗长，但具有更好的 TS 性能。使用基于文件的路由，路由树为您生成，因此冗长的路由树不是问题

避免在没有缩小的情况下使用内部类型

您可能想要重用暴露的类型是很常见的。例如，您可能会想要像这样使用 LinkProps

tsx
const props: LinkProps = {
  to: '/posts/',
}

return (
  <Link {...props}>
)

const props: LinkProps = {
  to: '/posts/',
}

return (
  <Link {...props}>
)

这对 TS 性能非常不利。这里的问题是 LinkProps 没有类型参数，因此是一个极其庞大的类型。它包括 search（所有 search 参数的联合），它包含 params（所有 params 的联合）。当将此对象与 Link 合并时，它将对这个巨大的类型进行结构比较。

相反，您可以使用 as const satisfies 来推断精确类型，而不是直接使用 LinkProps 以避免巨大的检查

tsx
const props = {
  to: '/posts/',
} as const satisfies LinkProps

return (
  <Link {...props}>
)

const props = {
  to: '/posts/',
} as const satisfies LinkProps

return (
  <Link {...props}>
)

由于 props 不是 LinkProps 类型，因此此检查更便宜，因为类型更加精确。您还可以通过缩小 LinkProps 进一步改进类型检查

tsx
const props = {
  to: '/posts/',
} as const satisfies LinkProps<RegisteredRouter, string '/posts/'>

return (
  <Link {...props}>
)

const props = {
  to: '/posts/',
} as const satisfies LinkProps<RegisteredRouter, string '/posts/'>

return (
  <Link {...props}>
)

这甚至更快，因为我们正在检查缩小的 LinkProps 类型。

您还可以使用它将 LinkProps 的类型缩小为特定类型，以用作函数的属性或参数

tsx
export const myLinkProps = [
  {
    to: '/posts',
  },
  {
    to: '/posts/$postId',
    params: { postId: 'postId' },
  },
] as const satisfies ReadonlyArray<LinkProps>

export type MyLinkProps = (typeof myLinkProps)[number]

const MyComponent = (props: { linkProps: MyLinkProps }) => {
  return <Link {...props.linkProps} />
}

export const myLinkProps = [
  {
    to: '/posts',
  },
  {
    to: '/posts/$postId',
    params: { postId: 'postId' },
  },
] as const satisfies ReadonlyArray<LinkProps>

export type MyLinkProps = (typeof myLinkProps)[number]

const MyComponent = (props: { linkProps: MyLinkProps }) => {
  return <Link {...props.linkProps} />
}

这比在组件中直接使用 LinkProps 更快，因为 MyLinkProps 是一个更精确的类型

另一个解决方案是不使用 LinkProps，而是提供控制反转来渲染缩小到特定路由的 Link 组件。渲染属性是将控制反转给组件用户的好方法

tsx
export interface MyComponentProps {
  readonly renderLink: () => React.ReactNode
}

const MyComponent = (props: MyComponentProps) => {
  return <div>{props.renderLink()}</div>
}

const Page = () => {
  return <MyComponent renderLink={() => <Link to="/absolute" />} />
}

export interface MyComponentProps {
  readonly renderLink: () => React.ReactNode
}

const MyComponent = (props: MyComponentProps) => {
  return <div>{props.renderLink()}</div>
}

const Page = () => {
  return <MyComponent renderLink={() => <Link to="/absolute" />} />
}

这个特定示例非常快，因为我们已经将导航位置的控制反转给组件的用户。Link 被缩小到我们想要导航到的确切路由

在 GitHub 上编辑
数据变更
类型工具