基于文件的路由

TanStack Router 大部分文档都是为基于文件的路由编写的，旨在帮助您更详细地了解如何配置基于文件的路由以及其工作原理的技术细节。虽然基于文件的路由是配置 TanStack Router 的首选和推荐方式，但如果您愿意，也可以使用基于代码的路由。

什么是基于文件的路由？

基于文件的路由是一种使用文件系统配置路由的方式。您可以使用一系列文件和目录来定义路由层次结构，而不是通过代码定义路由结构。这带来了许多好处：

• 简洁性：基于文件的路由在视觉上直观，易于新老开发者理解。
• 组织性：路由的组织方式与您应用程序的 URL 结构相呼应。
• 可扩展性：随着您的应用程序的增长，基于文件的路由可以轻松添加新路由并维护现有路由。
• 代码分割：基于文件的路由允许 TanStack Router 自动分割路由代码，以获得更好的性能。
• 类型安全：基于文件的路由通过生成和管理路由的类型链接，提高了类型安全的上限，而这在基于代码的路由中可能是一个繁琐的过程。
• 一致性：基于文件的路由强制实施一致的路由结构，使其更容易维护和更新您的应用程序，并从一个项目迁移到另一个项目。

/还是.？

虽然目录长期以来一直用于表示路由层次结构，但基于文件的路由引入了一个额外的概念，即在文件名中使用.字符来表示路由嵌套。这使您不必为少量深度嵌套的路由创建目录，同时仍可以使用目录来表示更广泛的路由层次结构。让我们看一些例子！

目录路由

目录可用于表示路由层次结构，这有助于将多个路由组织成逻辑组，并减少大型深度嵌套路由组的文件名长度。

请参阅下面的示例

文件名	路由路径	组件输出
ʦ __root.tsx		<Root>
ʦ index.tsx	/ (精确匹配)	<Root><RootIndex>
ʦ about.tsx	/about	<Root><About>
ʦ posts.tsx	/posts	<Root><Posts>
📂 posts
┄ ʦ index.tsx	/posts (精确匹配)	<Root><Posts><PostsIndex>
┄ ʦ $postId.tsx	/posts/$postId	<Root><Posts><Post>
📂 posts_
┄ 📂 $postId
┄ ┄ ʦ edit.tsx	/posts/$postId/edit	<Root><EditPost>
ʦ settings.tsx	/settings	<Root><Settings>
📂 settings		<Root><Settings>
┄ ʦ profile.tsx	/settings/profile	<Root><Settings><Profile>
┄ ʦ notifications.tsx	/settings/notifications	<Root><Settings><Notifications>
ʦ _pathlessLayout.tsx		<Root><PathlessLayout>
📂 _pathlessLayout
┄ ʦ route-a.tsx	/route-a	<Root><PathlessLayout><RouteA>
┄ ʦ route-b.tsx	/route-b	<Root><PathlessLayout><RouteB>
📂 files
┄ ʦ $.tsx	/files/$	<Root><Files>
📂 account
┄ ʦ route.tsx	/account	<Root><Account>
┄ ʦ overview.tsx	/account/overview	<Root><Account><Overview>

扁平路由

扁平路由使您能够使用.来表示路由嵌套级别。

当您拥有大量唯一深度嵌套的路由并且不想为每个路由创建目录时，这会很有用。

请参阅下面的示例

文件名	路由路径	组件输出
ʦ __root.tsx		<Root>
ʦ index.tsx	/ (精确匹配)	<Root><RootIndex>
ʦ about.tsx	/about	<Root><About>
ʦ posts.tsx	/posts	<Root><Posts>
ʦ posts.index.tsx	/posts (精确匹配)	<Root><Posts><PostsIndex>
ʦ posts.$postId.tsx	/posts/$postId	<Root><Posts><Post>
ʦ posts_.$postId.edit.tsx	/posts/$postId/edit	<Root><EditPost>
ʦ settings.tsx	/settings	<Root><Settings>
ʦ settings.profile.tsx	/settings/profile	<Root><Settings><Profile>
ʦ settings.notifications.tsx	/settings/notifications	<Root><Settings><Notifications>
ʦ _pathlessLayout.tsx		<Root><PathlessLayout>
ʦ _pathlessLayout.route-a.tsx	/route-a	<Root><PathlessLayout><RouteA>
ʦ _pathlessLayout.route-b.tsx	/route-b	<Root><PathlessLayout><RouteB>
ʦ files.$.tsx	/files/$	<Root><Files>
ʦ account.tsx	/account	<Root><Account>
ʦ account.overview.tsx	/account/overview	<Root><Account><Overview>

混合扁平路由和目录路由

您的项目极有可能不会完全使用目录或扁平路由结构，因此 TanStack Router 允许您混合使用扁平路由和目录路由，以在合理的地方结合两者的优势来创建路由树。

请参阅下面的示例

文件名	路由路径	组件输出
ʦ __root.tsx		<Root>
ʦ index.tsx	/ (精确匹配)	<Root><RootIndex>
ʦ about.tsx	/about	<Root><About>
ʦ posts.tsx	/posts	<Root><Posts>
📂 posts
┄ ʦ index.tsx	/posts (精确匹配)	<Root><Posts><PostsIndex>
┄ ʦ $postId.tsx	/posts/$postId	<Root><Posts><Post>
┄ ʦ $postId.edit.tsx	/posts/$postId/edit	<Root><Posts><Post><EditPost>
ʦ settings.tsx	/settings	<Root><Settings>
ʦ settings.profile.tsx	/settings/profile	<Root><Settings><Profile>
ʦ settings.notifications.tsx	/settings/notifications	<Root><Settings><Notifications>
ʦ account.tsx	/account	<Root><Account>
ʦ account.overview.tsx	/account/overview	<Root><Account><Overview>

扁平路由和目录路由可以混合使用，以在合理的地方结合两者的优势来创建路由树。

开始使用基于文件的路由

要开始使用基于文件的路由，您需要配置项目的打包器以使用 TanStack Router 插件或 TanStack Router CLI。

要启用基于文件的路由，您需要使用支持的打包器来使用 React。请查看下面的配置指南，看您的打包器是否在列表中。

• 使用 Vite 进行配置

通过受支持的打包器使用 TanStack Router 的基于文件的路由时，我们的插件将在您打包器的开发和构建过程中自动生成您的路由配置。这是使用 TanStack Router 的路由生成功能最简单的方法。

如果您的打包器尚不支持，您可以在 Discord 或 GitHub 上联系我们，告知我们。在此之前，请放心！您仍然可以使用@tanstack/router-cli包来生成您的路由树文件。