概述 | 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 标准，如 Request/Response，并专注于在任何可以运行 JS 的地方运行。它的许多 API 和抽象设计精妙，并且是许多 TanStack Router API 的灵感来源。然而，其僵化的设计、后加的类型安全以及有时过于严格地遵守平台 API 可能会让一些开发者想要更多。

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

在这一点上，选择路由器如此重要，以至于它通常与您选择的框架 1 对 1 绑定，这可能并不令人惊讶，因为大多数框架都依赖于特定的路由器。

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

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

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

为什么选择 TanStack Router？

TanStack Router 实现了您期望的其他路由器相同的基本期望

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

并且它还提供了一些新的功能，提高了标准

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

让我们更详细地深入探讨一些更重要的内容！

100% 类型推断 TypeScript 支持

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

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

这对您意味着什么？

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

一流的搜索参数

搜索参数通常是事后才考虑的，被视为字符串（或字符串）的黑匣子，您可以解析和更新，但仅此而已。现有的解决方案也不是类型安全的，这增加了处理它们所需的谨慎。即使是最“现代”的框架和路由器也让您自己去弄清楚如何管理这种状态。有时它们会将搜索字符串解析为对象，有时您需要使用 URLSearchParams 自己完成。

让我们退一步，记住搜索参数是您整个应用程序中最强大的状态管理器。它们是全局的、可序列化的、可书签的、可共享的，这使得它们成为存储任何需要经历页面刷新或社交分享的状态的完美场所。

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

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

搜索参数是

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

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

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

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

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

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

内置缓存

TanStack Router 提供了一个轻量级的内置缓存层，可以与 Router 无缝协作。此缓存层松散地基于 TanStack Query，但功能较少，API 表面积也小得多。与 TanStack Query 类似，合理但强大的默认设置保证了您的数据被缓存以供重用，在必要时失效，并在不使用时进行垃圾回收。它还提供了一个简单的 API，用于在需要时手动使缓存失效。

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

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

继承的路由上下文

TanStack Router 的路由器和路由上下文是一个强大的功能，它允许您定义特定于路由的上下文，然后该上下文将由所有子路由继承。甚至路由器和根路由本身也可以提供上下文。上下文可以同步和异步构建，并且可以用于在路由和路由配置之间共享数据、配置甚至函数。这对于以下场景尤其有用

身份验证和授权
混合 SSR/CSR 数据获取和预加载
主题化
单例和全局实用程序
跨预加载、加载和渲染阶段的柯里化或部分应用

另外，如果路由上下文不是类型安全的，那又有什么意义呢？TanStack Router 的路由上下文是完全类型安全的，并且零成本地推断给您。

概述