类型安全

TanStack Router 在 TypeScript 编译器和运行时的限制范围内，力求实现尽可能高的类型安全。这意味着它不仅使用 TypeScript 编写，而且还完全推断所提供的类型，并将其坚定地贯穿整个路由体验。

最终，这意味着您作为开发人员编写的类型更少，并且在代码演进过程中对代码更有信心。

路由定义

基于文件的路由

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

基于代码的路由

如果您直接使用 Route 类，您需要了解如何使用 Route 的 getParentRoute 选项来确保您的路由类型正确。这是因为子路由需要了解其所有父路由的类型。没有这一点，您从您的“布局”和“无路径布局”路由中解析出来的那些珍贵的搜索参数，往上三层，都将消失在 JS 虚空中。

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

tsx

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

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

导出的 Hook、组件和工具

为了使您的路由器的类型能够与 Link、useNavigate、useParams 等顶级导出项一起工作，它们必须渗透到 TypeScript 模块边界，并注册到库中。为此，我们对导出的 Register 接口使用声明合并。

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

通过在模块中注册您的路由器，您现在可以与路由器的精确类型一起使用导出的 hook、组件和实用程序。

修复组件上下文问题

组件上下文是 React 和其他框架中为组件提供依赖项的绝佳工具。然而，如果该上下文在组件层级结构中移动时类型发生变化，TypeScript 将无法知道如何推断这些变化。为了解决这个问题，基于上下文的 hook 和组件要求您提示它们的使用方式和位置。

tsx

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

function PostsComponent() {
  // Each route has type-safe versions of most of the built-in hooks from TanStack Router
  const params = Route.useParams()
  const search = Route.useSearch()

  // Some hooks require context from the *entire* router, not just the current route. To achieve type-safety here,
  // we must pass the `from` param to tell the hook our relative position in the route hierarchy.
  const navigate = useNavigate({ from: Route.fullPath })
  // ... etc
}

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

function PostsComponent() {
  // Each route has type-safe versions of most of the built-in hooks from TanStack Router
  const params = Route.useParams()
  const search = Route.useSearch()

  // Some hooks require context from the *entire* router, not just the current route. To achieve type-safety here,
  // we must pass the `from` param to tell the hook our relative position in the route hierarchy.
  const navigate = useNavigate({ from: Route.fullPath })
  // ... etc
}

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

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

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

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

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

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

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

如果您正在渲染一个在多个路由之间共享的组件，或者您正在渲染一个不在路由中的组件，您可以传入 strict: false 而不是 from 选项。这不仅会抑制运行时错误，还会为您正在调用的潜在 hook 提供宽松但准确的类型。一个很好的例子是从共享组件调用 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([
  // ... all child routes will have access to `whateverYouWant` in their context
])

const router = createRouter({
  routeTree,
  context: {
    // This will be required to be passed now
    whateverYouWant: true,
  },
})

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

const routeTree = rootRoute.addChildren([
  // ... all child routes will have access to `whateverYouWant` in their context
])

const router = createRouter({
  routeTree,
  context: {
    // This will be required to be passed now
    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 的类型缩小到特定类型，以用作函数 prop 或参数。

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 组件。渲染 props 是将控制权反转给组件用户的好方法。

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 被缩小到我们想要导航到的精确路由。