From ea8af983244380404e8a6e1a2ff16ca9c017ce82 Mon Sep 17 00:00:00 2001 From: Arthur Darkstone Date: Mon, 11 Nov 2024 19:22:39 +0800 Subject: [PATCH] docs: add route config desc (#4857) --- apps/web-antd/src/router/routes/index.ts | 5 +- apps/web-ele/src/router/routes/index.ts | 5 +- apps/web-naive/src/router/routes/index.ts | 5 +- docs/src/en/guide/essentials/route.md | 206 +++++++++++++--------- docs/src/guide/essentials/route.md | 22 ++- playground/src/router/routes/index.ts | 6 +- 6 files changed, 156 insertions(+), 93 deletions(-) diff --git a/apps/web-antd/src/router/routes/index.ts b/apps/web-antd/src/router/routes/index.ts index ea91dbe7116..e6fb1440204 100644 --- a/apps/web-antd/src/router/routes/index.ts +++ b/apps/web-antd/src/router/routes/index.ts @@ -17,12 +17,12 @@ const dynamicRoutes: RouteRecordRaw[] = mergeRouteModules(dynamicRouteFiles); /** 外部路由列表，访问这些页面可以不需要Layout，可能用于内嵌在别的系统(不会显示在菜单中) */ // const externalRoutes: RouteRecordRaw[] = mergeRouteModules(externalRouteFiles); -/** 不需要权限的菜单列表（会显示在菜单中） */ // const staticRoutes: RouteRecordRaw[] = mergeRouteModules(staticRouteFiles); const staticRoutes: RouteRecordRaw[] = []; const externalRoutes: RouteRecordRaw[] = []; -/** 路由列表，由基本路由+静态路由组成 */ +/** 路由列表，由基本路由、外部路由和404兜底路由组成 + * 无需走权限验证（会一直显示在菜单中） */ const routes: RouteRecordRaw[] = [ ...coreRoutes, ...externalRoutes, @@ -32,5 +32,6 @@ const routes: RouteRecordRaw[] = [ /** 基本路由列表，这些路由不需要进入权限拦截 */ const coreRouteNames = traverseTreeValues(coreRoutes, (route) => route.name); +/** 有权限校验的路由列表，包含动态路由和静态路由 */ const accessRoutes = [...dynamicRoutes, ...staticRoutes]; export { accessRoutes, coreRouteNames, routes }; diff --git a/apps/web-ele/src/router/routes/index.ts b/apps/web-ele/src/router/routes/index.ts index ea91dbe7116..e6fb1440204 100644 --- a/apps/web-ele/src/router/routes/index.ts +++ b/apps/web-ele/src/router/routes/index.ts @@ -17,12 +17,12 @@ const dynamicRoutes: RouteRecordRaw[] = mergeRouteModules(dynamicRouteFiles); /** 外部路由列表，访问这些页面可以不需要Layout，可能用于内嵌在别的系统(不会显示在菜单中) */ // const externalRoutes: RouteRecordRaw[] = mergeRouteModules(externalRouteFiles); -/** 不需要权限的菜单列表（会显示在菜单中） */ // const staticRoutes: RouteRecordRaw[] = mergeRouteModules(staticRouteFiles); const staticRoutes: RouteRecordRaw[] = []; const externalRoutes: RouteRecordRaw[] = []; -/** 路由列表，由基本路由+静态路由组成 */ +/** 路由列表，由基本路由、外部路由和404兜底路由组成 + * 无需走权限验证（会一直显示在菜单中） */ const routes: RouteRecordRaw[] = [ ...coreRoutes, ...externalRoutes, @@ -32,5 +32,6 @@ const routes: RouteRecordRaw[] = [ /** 基本路由列表，这些路由不需要进入权限拦截 */ const coreRouteNames = traverseTreeValues(coreRoutes, (route) => route.name); +/** 有权限校验的路由列表，包含动态路由和静态路由 */ const accessRoutes = [...dynamicRoutes, ...staticRoutes]; export { accessRoutes, coreRouteNames, routes }; diff --git a/apps/web-naive/src/router/routes/index.ts b/apps/web-naive/src/router/routes/index.ts index ea91dbe7116..e6fb1440204 100644 --- a/apps/web-naive/src/router/routes/index.ts +++ b/apps/web-naive/src/router/routes/index.ts @@ -17,12 +17,12 @@ const dynamicRoutes: RouteRecordRaw[] = mergeRouteModules(dynamicRouteFiles); /** 外部路由列表，访问这些页面可以不需要Layout，可能用于内嵌在别的系统(不会显示在菜单中) */ // const externalRoutes: RouteRecordRaw[] = mergeRouteModules(externalRouteFiles); -/** 不需要权限的菜单列表（会显示在菜单中） */ // const staticRoutes: RouteRecordRaw[] = mergeRouteModules(staticRouteFiles); const staticRoutes: RouteRecordRaw[] = []; const externalRoutes: RouteRecordRaw[] = []; -/** 路由列表，由基本路由+静态路由组成 */ +/** 路由列表，由基本路由、外部路由和404兜底路由组成 + * 无需走权限验证（会一直显示在菜单中） */ const routes: RouteRecordRaw[] = [ ...coreRoutes, ...externalRoutes, @@ -32,5 +32,6 @@ const routes: RouteRecordRaw[] = [ /** 基本路由列表，这些路由不需要进入权限拦截 */ const coreRouteNames = traverseTreeValues(coreRoutes, (route) => route.name); +/** 有权限校验的路由列表，包含动态路由和静态路由 */ const accessRoutes = [...dynamicRoutes, ...staticRoutes]; export { accessRoutes, coreRouteNames, routes }; diff --git a/docs/src/en/guide/essentials/route.md b/docs/src/en/guide/essentials/route.md index 501cba3825e..bef40d691f5 100644 --- a/docs/src/en/guide/essentials/route.md +++ b/docs/src/en/guide/essentials/route.md @@ -2,42 +2,66 @@ outline: deep --- -# Routing and Menus +# Routes and Menus -In the project, the framework provides a basic routing system and **automatically generates the corresponding menu structure based on the routing file**. +::: info -## Route Types +This page is translated by machine translation and may not be very accurate. -Routes are divided into static routes and dynamic routes. Static routes are routes that have been determined when the project starts. Dynamic routes are generally routes that are dynamically generated based on the user's permissions after the user logs in. +::: + +In the project, the framework provides a basic routing system and **automatically generates the corresponding menu structure based on the routing files**. + +## Types of Routes + +Routes are divided into core routes, static routes, and dynamic routes. Core routes are built-in routes of the framework, including root routes, login routes, 404 routes, etc.; static routes are routes that are determined when the project starts; dynamic routes are generally generated dynamically based on the user's permissions after the user logs in. + +Both static and dynamic routes go through permission control, which can be controlled by configuring the `authority` field in the `meta` property of the route. + +### Core Routes + +Core routes are built-in routes of the framework, including root routes, login routes, 404 routes, etc. The configuration of core routes is in the `src/router/routes/core` directory under the application. + +::: tip + +Core routes are mainly used for the basic functions of the framework, so it is not recommended to put business-related routes in core routes. It is recommended to put business-related routes in static or dynamic routes. + +::: ### Static Routes -If your page project does not require permission control, you can directly use static routes. The configuration of static routes is in the `src/router/routes/index` directory under the application. Open the commented file content: +The configuration of static routes is in the `src/router/routes/index` directory under the application. Open the commented file content: + +::: tip + +Permission control is controlled by the `authority` field in the `meta` property of the route. If your page project does not require permission control, you can omit the `authority` field. + +::: ```ts -// If necessary, you can open your own comments and create folders +// Uncomment if needed and create the folder // const externalRouteFiles = import.meta.glob('./external/**/*.ts', { eager: true }); // [!code --] const staticRouteFiles = import.meta.glob('./static/**/*.ts', { eager: true }); // [!code ++] -/** Dynamic routing */ +/** Dynamic routes */ const dynamicRoutes: RouteRecordRaw[] = mergeRouteModules(dynamicRouteFiles); -/** External routing lists, which can be accessed without Layout, may be used for embedding in other systems */ +/** External route list, these pages can be accessed without Layout, possibly used for embedding in other systems */ // const externalRoutes: RouteRecordRaw[] = mergeRouteModules(externalRouteFiles) // [!code --] const externalRoutes: RouteRecordRaw[] = []; // [!code --] const externalRoutes: RouteRecordRaw[] = mergeRouteModules(externalRouteFiles); // [!code ++] ``` -### Dynamic routing +### Dynamic Routes -The configuration of dynamic routing is in the corresponding application `src/router/routes/modules` directory. All routing files are stored in this directory. The content format of each file is as follows, which is consistent with the routing configuration format of Vue Router. The following is the configuration of secondary routes and multi-level routes. +The configuration of dynamic routes is in the `src/router/routes/modules` directory under the corresponding application. This directory contains all the route files. The content format of each file is consistent with the Vue Router route configuration format. Below is the configuration of secondary and multi-level routes. -## Define the route +## Route Definition -Static routes and dynamic routes are configured in the same way. The configuration of the level-2 and multi-level routes is as follows: +The configuration method of static routes and dynamic routes is the same. Below is the configuration of secondary and multi-level routes: -### Secondary route +### Secondary Routes -::: details Example code of the secondary route +::: details Secondary Route Example Code ```ts import type { RouteRecordRaw } from 'vue-router'; @@ -81,17 +105,16 @@ export default routes; ::: -### Multilevel routing +### Multi-level Routes ::: tip -- The parent route of multi-level routing does not need to set the 'component' attribute, only the 'children' attribute needs to be set. Unless you really need to display content under nested parent routing. - -- If there are no special circumstances, the 'redirect' attribute of the parent route does not need to be specified and will default to the first child route. +- 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. ::: -::: details Multilevel Routing Example Code +::: details Multi-level Route Example Code ```ts import type { RouteRecordRaw } from 'vue-router'; @@ -112,7 +135,7 @@ const routes: RouteRecordRaw[] = [ path: '/demos', redirect: '/demos/access', children: [ - // 嵌套菜单 + // Nested menu { meta: { icon: 'ic:round-menu', @@ -208,13 +231,13 @@ export default routes; ::: -## Add a New Page +## Adding a New Page To add a new page, you only need to add a route and the corresponding page component. -### Add a Route +### Adding a Route -Add a route object in the corresponding routing file as follows: +Add a route object in the corresponding route file, as follows: ```ts import type { RouteRecordRaw } from 'vue-router'; @@ -251,9 +274,9 @@ const routes: RouteRecordRaw[] = [ export default routes; ``` -### Add Page Component +### Adding a Page Component -In `#/views/home/`, add a new `index.vue` file as follows: +In `#/views/home/`, add a new `index.vue` file, as follows: ```vue