概览 | TanStack Router React 文档

TanStack Router 是一个用于构建 React 和 Solid 应用程序的路由器。它的一些功能包括：

100% 推断的 TypeScript 支持
类型安全的导航
嵌套路由和布局路由（带有无路径布局）
内置路由加载器，支持 SWR 缓存
专为客户端数据缓存设计（TanStack Query、SWR 等）
自动路由预取
异步路由元素和错误边界
基于文件的路由生成
类型安全的 JSON 优先搜索参数状态管理 API
路径和搜索参数模式验证
搜索参数导航 API
自定义搜索参数解析器/序列化器支持
搜索参数中间件
路由匹配/加载中间件

要快速入门，请前往下一页。如果想了解更多，请系好安全带，我将带你快速了解！

“路由岔路口”

使用路由器构建应用程序被广泛认为是必不可少的，并且通常是你在技术栈中做出的首批选择之一。

那么，为什么你应该选择 TanStack Router 而不是其他路由器呢？

要回答这个问题，我们需要看看这个领域的其他选项。如果你仔细寻找，会发现很多，但在我的经验中，只有少数几个值得认真探索：

Next.js - 被广泛认为是启动新 React 项目的事实框架，它专注于性能、工作流和尖端技术。它的 API 和抽象功能强大，但有时可能显得不标准。它在行业中的极速增长和采用带来了功能丰富的体验，但也牺牲了令人感到不知所措和有时臃肿的代价。
Remix / React Router - 一个基于历史成功的 React Router 的全栈框架，提供同样强大的开发者和用户体验，其 API 和愿景坚定地基于 Web 标准，如请求/响应，并专注于在任何 JS 可以运行的地方运行。它的许多 API 和抽象设计精良，并为不少 TanStack Router API 提供了灵感。尽管如此，其僵化的设计、附加的类型安全以及有时对平台 API 的严格过度遵守，可能会让一些开发者期望更多。

这两个框架（及其路由器）都很棒，我个人可以证明两者都是构建 React 应用程序的非常好的解决方案。我的经验也告诉我，这些解决方案还可以做得更好，特别是在可供开发者使用的实际路由 API 方面，以使他们的应用程序更快、更容易、更愉快地工作。

到目前为止，选择一个路由器如此重要，以至于它通常与你的框架选择一对一地绑定，这可能不足为奇，因为大多数框架都依赖于特定的路由器。

这是否意味着 TanStack Router 是一个框架？

TanStack Router 本身不是传统意义上的“框架”，因为它没有解决一些其他常见的全栈问题。然而，TanStack Router 被设计为可以与其他工具结合使用时，升级为全栈框架，这些工具解决捆绑、部署和服务器端特定功能。这就是我们目前正在开发 TanStack Start 的原因，这是一个基于 TanStack Router 和 Vite 构建的全栈框架。

要深入了解 TanStack Router 的历史，请随意阅读 TanStack Router 的历史。

为什么选择 TanStack Router？

TanStack Router 提供了您对其他路由器所期望的相同基本功能：

嵌套路由、布局路由、分组路由
基于文件的路由
并行数据加载
预取
URL 路径参数
错误边界和处理
SSR
路由遮罩

它还提供了一些提高标准的新功能：

100% 推断的 TypeScript 支持
类型安全的导航
内置的 SWR 缓存用于加载器
专为客户端数据缓存设计（TanStack Query、SWR 等）
类型安全的 JSON 优先搜索参数状态管理 API
路径和搜索参数模式验证
搜索参数导航 API
自定义搜索参数解析器/序列化器支持
搜索参数中间件
继承的路由上下文
混合的文件式和代码式路由

让我们更详细地探讨其中一些更重要的功能！

100% 推断的 TypeScript 支持

如今的一切都“用 Typescript”编写，或者至少提供了覆盖运行时功能的类型定义，但生态系统中很少有包在设计其 API 时真正考虑了 TypeScript。因此，虽然我很高兴您的路由器可以自动完成您的选项字段并捕获一些属性/方法打字错误，但还有更多功能有待发掘。

TanStack Router 在您的代码的任何给定点都完全了解您的所有路由及其配置。这包括路径、路径参数、搜索参数、上下文以及您提供的任何其他配置。最终，这意味着您可以以 100% 的类型安全和信心导航到应用程序中的任何路由，并确信您的链接或导航调用将成功。
TanStack Router 提供无损的类型推断。它使用无数的泛型类型参数来强制并传播您提供给它的任何类型信息，贯穿其 API 的其余部分并最终影响您的应用程序。没有其他路由器提供这种级别的类型安全和开发人员信心。

所有这一切对您意味着什么？

通过自动补全和类型提示更快地进行功能开发
更安全、更快的重构
确信您的代码将按预期工作

一流的搜索参数

搜索参数通常是事后才考虑的，被视为一个字符串（或字符串组）的黑箱，你可以解析和更新，但除此之外别无他物。现有的解决方案也**不**是类型安全的，这增加了处理它们所需的谨慎。即使是最“现代”的框架和路由器也让你自己去解决如何管理这种状态。有时它们会为你将搜索字符串解析成一个对象，或者有时你只能自己用 URLSearchParams 来完成。

让我们回顾一下，请记住 **搜索参数是您整个应用程序中最强大的状态管理器。** 它们是全局的、可序列化的、可书签的、可共享的，这使它们成为存储任何需要在页面刷新或社交分享中存活的状态的完美位置。

为了担负起这份责任，搜索参数在 TanStack Router 中是头等公民。虽然仍然基于标准的 URLSearchParams，但 TanStack Router 使用强大的解析器/序列化器来管理搜索参数中更深层和更复杂的数据结构，同时保持它们的类型安全和易于使用。

这就像在 URL 中拥有 useState 一样！

搜索参数是

自动解析并序列化为 JSON
经过验证和类型化
从父路由继承
可在加载器、组件和 Hook 中访问
通过 useSearch hook、Link、navigate 和 router.navigate API 轻松修改
可通过自定义搜索过滤器和中间件进行定制
通过细粒度搜索参数选择器订阅以实现高效重新渲染

一旦您开始使用 TanStack Router 的搜索参数，您会想知道以前没有它们是如何生活的。

内置缓存和友好的数据加载

数据加载是任何应用程序的关键部分，虽然大多数现有路由器提供某种形式的关键数据加载 API，但在缓存和数据生命周期管理方面它们往往有所不足。现有解决方案存在一些常见问题：

完全没有缓存。数据总是新鲜的，但您的用户却不得不一次又一次地等待经常访问的数据加载。
过度激进的缓存。数据缓存时间过长，导致数据过时，用户体验不佳。
粗暴的失效策略和 API。数据可能失效过于频繁，导致不必要的网络请求和资源浪费，或者您可能根本无法对数据何时失效进行细粒度控制。

TanStack Router 通过双管齐下的缓存和数据加载方法解决了这些问题：

内置缓存

TanStack Router 提供了一个轻量级的内置缓存层，与路由器无缝协作。这个缓存层大致基于 TanStack Query，但功能更少，API 表面积也小得多。像 TanStack Query 一样，合理而强大的默认设置确保您的数据被缓存以供重用，在必要时失效，并在不使用时进行垃圾回收。它还提供了一个简单的 API，以便在需要时手动失效缓存。

灵活强大的数据生命周期 API

TanStack Router 设计有一个灵活且强大的数据加载 API，可以更轻松地与现有数据获取库集成，如 TanStack Query、SWR、Apollo、Relay，甚至您自己的自定义数据获取解决方案。诸如 context、beforeLoad、loaderDeps 和 loader 等可配置 API 协同工作，使定义声明性数据依赖、预取数据以及轻松管理外部数据源的生命周期变得容易。