Skip to main content

路由组

app 目录中,嵌套文件夹通常映射到 URL 路径。但是,你可以将文件夹标记为路由组,以防止该文件夹包含在路由的 URL 路径中。

¥In the app directory, nested folders are normally mapped to URL paths. However, you can mark a folder as a Route Group to prevent the folder from being included in the route's URL path.

这允许你将路由段和项目文件组织到逻辑组中,而不影响 URL 路径结构。

¥This allows you to organize your route segments and project files into logical groups without affecting the URL path structure.

路由组可用于:

¥Route groups are useful for:

惯例

¥Convention

可以通过将文件夹名称括在括号中来创建路由组:(folderName)

¥A route group can be created by wrapping a folder's name in parenthesis: (folderName)

示例

¥Examples

组织路由而不影响 URL 路径

¥Organize routes without affecting the URL path

要在不影响 URL 的情况下组织路由,请创建一个组以将相关路由保存在一起。URL 中将省略括号中的文件夹(例如 (marketing)(shop)

¥To organize routes without affecting the URL, create a group to keep related routes together. The folders in parenthesis will be omitted from the URL (e.g. (marketing) or (shop).

即使 (marketing)(shop) 内的路由共享相同的 URL 层次结构,你也可以通过在其文件夹内添加 layout.js 文件来为每个组创建不同的布局。

¥Even though routes inside (marketing) and (shop) share the same URL hierarchy, you can create a different layout for each group by adding a layout.js file inside their folders.

选择特定的部分到布局中

¥Opting specific segments into a layout

要将特定路由选择到布局中,请创建一个新的路由组(例如 (shop))并将共享相同布局的路由移到该组中(例如 accountcart)。组外的路由不会共享布局(例如 checkout)。

¥To opt specific routes into a layout, create a new route group (e.g. (shop)) and move the routes that share the same layout into the group (e.g. account and cart). The routes outside of the group will not share the layout (e.g. checkout).

选择在特定路由上加载骨架

¥Opting for loading skeletons on a specific route

要通过 loading.js 文件将 加载骨架 应用于特定路由,请创建一个新的路由组(例如 /(overview)),然后将 loading.tsx 移动到该路由组内。

¥To apply a loading skeleton via a loading.js file to a specific route, create a new route group (e.g., /(overview)) and then move your loading.tsx inside that route group.

现在,loading.tsx 文件将仅适用于你的仪表板 → 概览页面,而不是所有仪表板页面,而不会影响 URL 路径结构。

¥Now, the loading.tsx file will only apply to your dashboard → overview page instead of all your dashboard pages without affecting the URL path structure.

创建多个根布局

¥Creating multiple root layouts

要创建多个 根布局,请删除顶层 layout.js 文件,并在每个路由组内添加一个 layout.js 文件。这对于将应用划分为具有完全不同的 UI 或体验的部分非常有用。需要将 <html><body> 标签添加到每个根布局中。

¥To create multiple root layouts, remove the top-level layout.js file, and add a layout.js file inside each route group. This is useful for partitioning an application into sections that have a completely different UI or experience. The <html> and <body> tags need to be added to each root layout.

在上面的示例中,(marketing)(shop) 都有自己的根布局。

¥In the example above, both (marketing) and (shop) have their own root layout.


很高兴知道:

¥Good to know:

  • 路由组的命名除了用于组织之外没有特殊意义。它们不影响 URL 路径。

    ¥The naming of route groups has no special significance other than for organization. They do not affect the URL path.

  • 包含路由组的路由不应解析为与其他路由相同的 URL 路径。例如,由于路由组不影响 URL 结构,因此 (marketing)/about/page.js(shop)/about/page.js 都会解析为 /about 并导致错误。

    ¥Routes that include a route group should not resolve to the same URL path as other routes. For example, since route groups don't affect URL structure, (marketing)/about/page.js and (shop)/about/page.js would both resolve to /about and cause an error.

  • 如果你使用多个根布局而没有顶层 layout.js 文件,则你的主 page.js 文件应在其中一个路由组中定义,例如:app/(marketing)/page.js

    ¥If you use multiple root layouts without a top-level layout.js file, your home page.js file should be defined in one of the route groups, For example: app/(marketing)/page.js.

  • 跨多个根布局导航将导致完整页面加载(与客户端导航相反)。例如,从使用 app/(shop)/layout.js/cart 导航到使用 app/(marketing)/layout.js/blog 将导致整页加载。这仅适用于多个根布局。

    ¥Navigating across multiple root layouts will cause a full page load (as opposed to a client-side navigation). For example, navigating from /cart that uses app/(shop)/layout.js to /blog that uses app/(marketing)/layout.js will cause a full page load. This only applies to multiple root layouts.