From eedf522bbb339dd60b3da4343b13dec2fd5ec7b8 Mon Sep 17 00:00:00 2001 From: Bruce Yang Date: Wed, 28 Feb 2024 09:54:49 +0800 Subject: [PATCH] =?UTF-8?q?=E2=9C=8D=EF=B8=8F[doc]=20update=20router=20cha?= =?UTF-8?q?pter.=20(#9)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/.vitepress/config.js | 2 +- docs/guide/quick-understanding.md | 44 +++++++- docs/guide/router.md | 162 +++++++++++++++++++++++++----- docs/index.md | 2 +- 4 files changed, 181 insertions(+), 29 deletions(-) diff --git a/docs/.vitepress/config.js b/docs/.vitepress/config.js index ff28c3c..5778e7b 100644 --- a/docs/.vitepress/config.js +++ b/docs/.vitepress/config.js @@ -99,7 +99,7 @@ export default { text: "编辑此页", }, footer: { - copyright: `MIT License Copyright ©️ 2023-present Vben` + copyright: `MIT License Copyright ©️ 2024-present Vben` } }, }; diff --git a/docs/guide/quick-understanding.md b/docs/guide/quick-understanding.md index 1b7d85f..cbe5f4c 100644 --- a/docs/guide/quick-understanding.md +++ b/docs/guide/quick-understanding.md @@ -2,11 +2,51 @@ ## 功能特性 -vben3 的功能介绍…… +### :jigsaw: 框架无关 + +vben3不与任何框架深度集成，开发者可以选择自己中意的框架进行开发:smiling_face_with_three_hearts:。 + +默认情况下，vben3的示例demo采用[Naive UI](https://www.naiveui.com/zh-CN/light)框架进行编写。 + +### :herb: Turborepo架构 + +采用比Monorepo更优秀的Turborepo架构，提升构建体验:sunglasses: + +::: info +点击 [此处](https://turbo.build/repo/docs/core-concepts/monorepos) 查看Turborepo对Monorepo的优势 +::: + +### :rocket: 快速开发 + +每个开发者都有自己用的习惯或顺手的轮子进行快速开发。 + +在vben3里，我们将轮子与业务彻底解耦，开发者可以引入自己熟悉的轮子或者直接引用vben3封装完成的轮子进行快速开发，从而大大节省时间和精力:heart_eyes:。 + +::: details +但是，任何轮子都需要时间进行学习，我们将vben3的框架工具类在本文档进行详尽编写，任何你觉得有疑问的地方都可以先查询本文档:thinking:。 +::: ## 内置功能 -内置功能模块…… +vben3内置功能存放在`packages`目录下： + +```js +📁 packages + ┣━ 📁components -------------- 存放自定义组件 + ┣━ 📁constants --------------- 存放全局常量枚举 + ┣━ 📁demo -------------------- 示例demo + ┣━ 📁directives -------------- 存放自定义指令 + ┣━ 📁hooks ------------------- 存放hooks工具类 + ┣━ 📁locale ------------------ 存放多语言本地化i18n相关 + ┣━ 📁request ----------------- 存放http请求工具类 + ┣━ 📁router ------------------ 存放router路由工具类 + ┣━ 📁stores ------------------ 存放状态管理库工具类 + ┣━ 📁style ------------------- 存放主题配置相关类 + ┣━ 📁types ------------------- 存放类型定义配置文件类 + ┣━ 📁utils ------------------- 存放工具类相关 + ┣━ 📁vbenComponents ---------- 存放封装好的第三方组件 + ┣━ 📁grid-layouts ------------ 存放布局相关工具类 +``` ## 技术选型 diff --git a/docs/guide/router.md b/docs/guide/router.md index 26b4c0f..943a3cf 100644 --- a/docs/guide/router.md +++ b/docs/guide/router.md @@ -1,13 +1,68 @@ # 路由 -路由配置存放于 src/router/routes 下面。 -src/router/routes/modules用于存放路由模块，路由模块会自动注册。 + +Vben3采用Vuejs官方推荐路由[vue-router](https://router.vuejs.org/)，功能路径位于`packages/router`下。 + +## 依赖安装 + +::: code-group + +```bash [pnpm] +pnpm add vue-router@4 +``` +::: ## 路由模块 -:::info 注意 -在 src/router/routes/modules 内的 .ts 文件会被视为一个路由模块。 + +### `router-view` + +所有的路由都由`router-view`标签进行映射，在SPA中，你可以将其放在任何地方以适应你的布局。 + +### 编写方式 + +路由功能使用不同的写法以适用不同规格的项目的需求:point_right: [简单示例](https://router.vuejs.org/guide/) + +以下为Vben3路由组织方式:point_down: + +```js +📁router +└── 📁src + └── 📁helper // 路由功能 + └── 📁menus // 菜单功能 + └── 📁mitt // 路由更改监听 + └── 📁page // 公共路由相关 + └── 📁routes // 功能路由相关 + └── 📁modules // 功能路由存放 + └── index.ts + └── index.ts // 入口文件 + └── guard.ts // 路由导航守卫 +``` + +::: tip 提示 + +所有功能路由文件都放在`modules`目录下以ts文件后缀进行解析。 + ::: -```ts +::: code-group + +```ts [index.ts] +import { createRouter, createWebHashHistory, Router } from 'vue-router' + +// 初始化路由 +export let router: Router; +export function InitRouter(path: string): Router { + router = createRouter({ + history: createWebHashHistory(path), + routes: BaseRoutes, + strict: true, + scrollBehavior: () => ({left: 0, top: 0}) + }) + return router +} +``` + +```ts [dashboard.ts] +// routes/modules/dashboard.ts import { LAYOUT } from '../basic' const dashboard: RouteRecordItem = { @@ -45,9 +100,85 @@ const dashboard: RouteRecordItem = { export default dashboard ``` +::: + +## 相关功能 + +### 路由导航 + +路由导航分为`编程式导航`和`声明式导航`,通常使用`✔️编程式导航`进行路由跳转。 + +| 声明式 | 编程式 | +|-------------------------- | ------------------- | +| `` | `$router.push(...)` | + +```ts +// 字符串路径 +this.$router.push('/home')； + +// 带有路径的对象 +this.$router.push({ path: '/home' }) + +// 命名的路由，并加上参数，让路由建立url +this.$router.push({ name: 'user', params: { username: 'foo' }}); + +// 带查询参数，结果是 /register?plan=private +this.$router.push({ path: '/register', query: { plan: 'private' }}) + +// 带hash，结果是 /about#team +this.$router.push({ path: '/about', hash: '#team' }) +``` + +::: warning +注意：如果提供了 path，params 会被忽略，上述例子中的 query 并不属于这种情况。取而代之的是下面例子的做法，你需要提供路由的 name 或手写完整的带有参数的 path。 +::: + +### 路由白名单功能 + +通过设置路由白名单，无需通过路由导航守卫拦截即可访问页面。 + + +### 路由导航守卫功能 + +在导航到新路由之前，导航守卫会拦截那些正在进入的路由。从而实现导航前和导航后的一些行为实现。 + +### 路由权限功能 + +通过给路由添加权限标识符，在跳转之前进行拦截检测路由的权限，来控制用户是否有权限访问该路由。 + +### 路由异常处理功能 -## meta定义 +对一些异常路由进行异常处理，如404，500等。 + +### 动态路由Tab自动关闭功能 + +```ts + { + path: 'detail/:id', + name: 'TabDetail', + component: () => import('/@/views/demo/feat/tabs/TabDetail.vue'), + meta: { + currentActiveMenu: '/feat/tabs', + title: t('routes.demo.feat.tabDetail'), + hideMenu: true, + //dynamicLevel 最大能打开的Tab标签页数 + dynamicLevel: 3, + //realPath 动态路由实际路径(考虑到动态路由有时候可能存在N层的情况 + //例：/:id/:subId/:...), 为了减少计算开销, + //使用配置方式事先规定好路由的实际路径(注意: 该参数若不设置，将无法使用该功能) + realPath: '/feat/tabs/detail', + }, + } +``` + + +## API说明 + +### 路由元信息 + +有时，我们想要将一些任意信息附加到路由上，如过渡，权限，状态等。这些信息可以通过接收属性对象的`meta`属性来实现，并且它可以在路由地址和导航守卫上都被访问到。以下是`meta`属性可配置的字段:point_down: ```ts + export interface RouteMeta { // 路由title 一般必填 title: string; @@ -89,22 +220,3 @@ export interface RouteMeta { hidePathForChildren?: boolean; } ``` -## 动态路由Tab自动关闭功能 -```Ts -{ - path: 'detail/:id', - name: 'TabDetail', - component: () => import('/@/views/demo/feat/tabs/TabDetail.vue'), - meta: { - currentActiveMenu: '/feat/tabs', - title: t('routes.demo.feat.tabDetail'), - hideMenu: true, - //dynamicLevel 最大能打开的Tab标签页数 - dynamicLevel: 3, - //realPath 动态路由实际路径(考虑到动态路由有时候可能存在N层的情况 - //例：/:id/:subId/:...), 为了减少计算开销, - //使用配置方式事先规定好路由的实际路径(注意: 该参数若不设置，将无法使用该功能) - realPath: '/feat/tabs/detail', - }, -} -``` diff --git a/docs/index.md b/docs/index.md index ce073d1..3d7a70b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,7 +4,7 @@ layout: home hero: name: Vben Admin text: 一个开箱即用前端框架 - tagline: 采用Monorepo，分离组件样式逻辑，更通用的公共逻辑，降低组件开发的耦合。 + tagline: 采用Turborepo，分离组件样式逻辑，更通用的公共逻辑，降低组件开发的耦合。 image: src: /vben.svg alt: vben logo