From 77468ce9a603bceb3a14d014372a8f6a4451ec75 Mon Sep 17 00:00:00 2001 From: dream-weave <62940878+dream-weave@users.noreply.github.com> Date: Thu, 2 Jul 2026 18:35:54 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=B7=AF=E7=94=B1=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E7=A4=BA=E4=BE=8B=E4=BB=A3=E7=A0=81=E5=90=8C=E6=AD=A5=E8=B7=AF?= =?UTF-8?q?=E7=94=B1=E7=BB=84=E7=BB=87=E6=96=B0=E8=A7=84=E8=8C=83=20(#8114?= =?UTF-8?q?)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/src/en/guide/essentials/route.md | 40 +++++++++++++-------------- docs/src/guide/essentials/route.md | 37 +++++++++++++------------ 2 files changed, 38 insertions(+), 39 deletions(-) diff --git a/docs/src/en/guide/essentials/route.md b/docs/src/en/guide/essentials/route.md index 8fb0a6d1c..71540b2a5 100644 --- a/docs/src/en/guide/essentials/route.md +++ b/docs/src/en/guide/essentials/route.md @@ -61,6 +61,13 @@ The configuration method of static routes and dynamic routes is the same. Below ### Secondary Routes +::: tip + +- Only top-level routes should start their `path` with `/`; routes inside `children` should use relative segments such as `about` or `menu1`. +- When a parent route does not define `redirect`, the framework automatically fills it with the first child route. This only works when child paths stay relative. + +::: + ::: details Secondary Route Example Code ```ts @@ -68,7 +75,6 @@ import type { RouteRecordRaw } from 'vue-router'; import { VBEN_LOGO_URL } from '@vben/constants'; -import { BasicLayout } from '#/layouts'; import { $t } from '#/locales'; const routes: RouteRecordRaw[] = [ @@ -82,11 +88,10 @@ const routes: RouteRecordRaw[] = [ }, name: 'VbenProject', path: '/vben-admin', - redirect: '/vben-admin/about', children: [ { name: 'VbenAbout', - path: '/vben-admin/about', + path: 'about', component: () => import('#/views/_core/about/index.vue'), meta: { badgeType: 'dot', @@ -108,6 +113,7 @@ export default routes; ::: tip +- Multi-level routes follow the same rule: keep top-level paths absolute and child paths relative, instead of repeating the full path inside `children`. - The parent route of multi-level routes does not need to set the `component` property, just set the `children` property. Unless you really need to display content nested under the parent route. - In most cases, the `redirect` property of the parent route does not need to be specified, it will default to the first child route. @@ -118,7 +124,6 @@ export default routes; ```ts import type { RouteRecordRaw } from 'vue-router'; -import { BasicLayout } from '#/layouts'; import { $t } from '#/locales'; const routes: RouteRecordRaw[] = [ @@ -131,7 +136,6 @@ const routes: RouteRecordRaw[] = [ }, name: 'Demos', path: '/demos', - redirect: '/demos/access', children: [ // Nested menu { @@ -140,12 +144,11 @@ const routes: RouteRecordRaw[] = [ title: $t('demos.nested.title'), }, name: 'NestedDemos', - path: '/demos/nested', - redirect: '/demos/nested/menu1', + path: 'nested', children: [ { name: 'Menu1Demo', - path: '/demos/nested/menu1', + path: 'menu1', component: () => import('#/views/demos/nested/menu-1.vue'), meta: { icon: 'ic:round-menu', @@ -155,17 +158,16 @@ const routes: RouteRecordRaw[] = [ }, { name: 'Menu2Demo', - path: '/demos/nested/menu2', + path: 'menu2', meta: { icon: 'ic:round-menu', keepAlive: true, title: $t('demos.nested.menu2'), }, - redirect: '/demos/nested/menu2/menu2-1', children: [ { name: 'Menu21Demo', - path: '/demos/nested/menu2/menu2-1', + path: 'menu2-1', component: () => import('#/views/demos/nested/menu-2-1.vue'), meta: { icon: 'ic:round-menu', @@ -177,12 +179,11 @@ const routes: RouteRecordRaw[] = [ }, { name: 'Menu3Demo', - path: '/demos/nested/menu3', + path: 'menu3', meta: { icon: 'ic:round-menu', title: $t('demos.nested.menu3'), }, - redirect: '/demos/nested/menu3/menu3-1', children: [ { name: 'Menu31Demo', @@ -201,11 +202,10 @@ const routes: RouteRecordRaw[] = [ icon: 'ic:round-menu', title: $t('demos.nested.menu3_2'), }, - redirect: '/demos/nested/menu3/menu3-2/menu3-2-1', children: [ { name: 'Menu321Demo', - path: '/demos/nested/menu3/menu3-2/menu3-2-1', + path: 'menu3-2-1', component: () => import('#/views/demos/nested/menu-3-2-1.vue'), meta: { @@ -242,7 +242,6 @@ import type { RouteRecordRaw } from 'vue-router'; import { VBEN_LOGO_URL } from '@vben/constants'; -import { BasicLayout } from '#/layouts'; import { $t } from '#/locales'; const routes: RouteRecordRaw[] = [ @@ -253,11 +252,10 @@ const routes: RouteRecordRaw[] = [ }, name: 'Home', path: '/home', - redirect: '/home/index', children: [ { name: 'HomeIndex', - path: '/home/index', + path: 'index', component: () => import('#/views/home/index.vue'), meta: { icon: 'mdi:home', @@ -294,11 +292,11 @@ The route configuration items are mainly in the `meta` property of the route obj ```ts {5-8} const routes = [ { - name: 'HomeIndex', - path: '/home/index', + name: 'Home', + path: '/home', meta: { icon: 'mdi:home', - title: $t('page.home.index'), + title: $t('page.home.title'), }, }, ]; diff --git a/docs/src/guide/essentials/route.md b/docs/src/guide/essentials/route.md index 8383e7620..9668e8d54 100644 --- a/docs/src/guide/essentials/route.md +++ b/docs/src/guide/essentials/route.md @@ -55,6 +55,13 @@ const externalRoutes: RouteRecordRaw[] = mergeRouteModules(externalRouteFiles); ### 二级路由 +::: tip + +- 只有顶级路由的 `path` 需要以 `/` 开头；写在 `children` 中的子路由请使用相对路径片段，例如 `about`、`menu1`。 +- 当父级路由未显式配置 `redirect` 时，框架会自动补全到第一个子路由的重定向；这依赖子路由使用相对路径。 + +::: + ::: details 二级路由示例代码 ```ts @@ -75,11 +82,10 @@ const routes: RouteRecordRaw[] = [ }, name: 'VbenProject', path: '/vben-admin', - redirect: '/vben-admin/about', children: [ { name: 'VbenAbout', - path: '/vben-admin/about', + path: 'about', component: () => import('#/views/_core/about/index.vue'), meta: { badgeType: 'dot', @@ -101,6 +107,7 @@ export default routes; ::: tip +- 多级路由同样遵循“顶级绝对路径、子级相对路径”的组织方式，避免在 `children` 中重复写完整路径。 - 如果没有特殊情况，父级路由的 `redirect` 属性，不需要指定，默认会指向第一个子路由。 ::: @@ -122,7 +129,6 @@ const routes: RouteRecordRaw[] = [ }, name: 'Demos', path: '/demos', - redirect: '/demos/access', children: [ // 嵌套菜单 { @@ -131,12 +137,11 @@ const routes: RouteRecordRaw[] = [ title: $t('demos.nested.title'), }, name: 'NestedDemos', - path: '/demos/nested', - redirect: '/demos/nested/menu1', + path: 'nested', children: [ { name: 'Menu1Demo', - path: '/demos/nested/menu1', + path: 'menu1', component: () => import('#/views/demos/nested/menu-1.vue'), meta: { icon: 'ic:round-menu', @@ -146,17 +151,16 @@ const routes: RouteRecordRaw[] = [ }, { name: 'Menu2Demo', - path: '/demos/nested/menu2', + path: 'menu2', meta: { icon: 'ic:round-menu', keepAlive: true, title: $t('demos.nested.menu2'), }, - redirect: '/demos/nested/menu2/menu2-1', children: [ { name: 'Menu21Demo', - path: '/demos/nested/menu2/menu2-1', + path: 'menu2-1', component: () => import('#/views/demos/nested/menu-2-1.vue'), meta: { icon: 'ic:round-menu', @@ -168,12 +172,11 @@ const routes: RouteRecordRaw[] = [ }, { name: 'Menu3Demo', - path: '/demos/nested/menu3', + path: 'menu3', meta: { icon: 'ic:round-menu', title: $t('demos.nested.menu3'), }, - redirect: '/demos/nested/menu3/menu3-1', children: [ { name: 'Menu31Demo', @@ -192,11 +195,10 @@ const routes: RouteRecordRaw[] = [ icon: 'ic:round-menu', title: $t('demos.nested.menu3_2'), }, - redirect: '/demos/nested/menu3/menu3-2/menu3-2-1', children: [ { name: 'Menu321Demo', - path: '/demos/nested/menu3/menu3-2/menu3-2-1', + path: 'menu3-2-1', component: () => import('#/views/demos/nested/menu-3-2-1.vue'), meta: { @@ -243,11 +245,10 @@ const routes: RouteRecordRaw[] = [ }, name: 'Home', path: '/home', - redirect: '/home/index', children: [ { name: 'HomeIndex', - path: '/home/index', + path: 'index', component: () => import('#/views/home/index.vue'), meta: { icon: 'mdi:home', @@ -284,11 +285,11 @@ export default routes; ```ts {5-8} const routes = [ { - name: 'HomeIndex', - path: '/home/index', + name: 'Home', + path: '/home', meta: { icon: 'mdi:home', - title: $t('page.home.index'), + title: $t('page.home.title'), }, }, ];