feat: 完善前端文档

.vitepress/src/zh/sidebars.ts

@@ -83,6 +83,10 @@ const sidebar:DefaultTheme.Sidebar = {
     {
       text: '进阶',
       items: [
+        {
+          text: '系统参数配置',
+          link: '/zh/front/advanced/system-config'
+        },
         {
           text: '自动导入',
           link: '/zh/front/advanced/auto-import'

docs/zh/front/advanced/layout.md

@@ -1 +1,50 @@
-# 布局
+# 布局
+
+布局跟 `2.0` 有很大差别，没有再区分一个个目录去构造不同的布局形式，整体都写在了 `src/layouts/index.tsx` 下。
+本章节讲解一些 `布局相关API` 以及 `全局css` 修改布局主侧边栏、子侧边栏、头部的宽度等等。
+
+## 布局相关API
+
+在 `useSettingStore()` 里定义了整个前端设置的 `api`，关于布局的有以下几个，其他的可以查看源码，或者看[常用Store](/zh/front/high/store)
+
+- `isMixedLayout()`  是否为混合布局
+- `isColumnsLayout()`  是否为分栏布局
+- `isClassicLayout()`  是否为经典布局
+- `getFixedAsideState()`  获取子侧边栏状态是否为固定状态
+- `getMenuCollapseState()` 获取菜单是否为折叠状态
+- `getMobileState()` 是否为移动端状态
+
+## 全局默认css
+
+::: tip 提示
+文件路径: `src/assets/styles/global.scss`
+:::
+
+可设置布局默认的一些高度、高度等等
+
+```css
+/* 变量定义 */
+:root {
+  /* 头部高度 */
+  --mine-g-header-height: 55px;
+  /* 脚部高度 */
+  --mine-g-footer-height: 50px;
+  /* 侧边栏主菜单宽度 */
+  --mine-g-main-aside-width: 80px;
+  /* 侧边栏子菜单展开宽度 */
+  --mine-g-sub-aside-width: 200px;
+  /* 侧边栏子菜单折叠后宽度 */
+  --mine-g-sub-aside-collapse-width: 65px;
+  /* 菜单缩进宽度 */
+  --mine-g-menu-retract-width: 15px;
+  /* 工具栏高度 */
+  --mine-g-toolbar-height: 55px;
+  /* 标签栏高度 */
+  --mine-g-tabbar-height: 40px;
+  /* 盒子阴影 */
+  --mine-g-box-shadow-color: rgb(0 0 0 / 18%);
+  /* 主颜色 */
+  --el-color-primary: --ui-primery;
+}
+```
+

docs/zh/front/advanced/module.md

@@ -1 +1,45 @@
-# 模块化
+# 模块化
+
+::: tip 说明
+现版本**视图、api定义文件等**将以模块化管理。
+:::
+
+## 模块根目录
+
+`src/modules`
+
+## base模块
+
+`base` 模块是系统自带的一个基础模块，会发现模块将 `视图文件`，`API请求文件`，`模块全局多语言` 等 `其他文件` 归类存放管理。
+基础模块里包含了目前系统自带的所有功能，包括登录、欢迎页、仪表盘、整个权限系统等等都在 `base` 模块下
+```bash
+./src/modules/base/
+  api/       # 模块下的API请求文件
+    attachment.ts
+    log.ts
+    menu.ts
+    permisstion.ts
+    role.ts
+    user.ts
+  locales/   # 模块下的全局国际化
+    en[English].yaml
+    zh_CN[简体中文].yaml
+    zh_TW[繁體中文].yaml
+  views/
+    dashboard/  
+      *.vue  # 太多vue 文件就不一一列出，以星号代替
+    log/
+      *.vue  # 太多vue 文件就不一一列出，以星号代替
+    login/
+      *.vue  # 太多vue 文件就不一一列出，以星号代替
+    permission/
+      *.vue  # 太多vue 文件就不一一列出，以星号代替
+    uc/
+      *.vue  # 太多vue 文件就不一一列出，以星号代替
+    welcome/
+      *.vue  # 太多vue 文件就不一一列出，以星号代替
+```
+
+::: info 
+如果新开发功能，就建议另外新建模块，不要写在 `base` 下。
+:::

docs/zh/front/advanced/system-config.md

@@ -0,0 +1,55 @@
+# 系统参数配置
+
+::: tip 配置文件
+- 默认配置文件：`src/provider/settings/index.ts`
+- 自定义配置文件：`src/provider/settings/settings.config.ts`
+
+修改配置，请将默认配置拷贝到 `settings.config.ts` 文件后，再修改，系统加载时会自动合并。
+:::
+
+## 默认配置
+```ts
+const defaultGlobalConfigSettings: RecursiveRequired<SystemSettings.all> = {
+  app: {
+    colorMode: 'autoMode',
+    useLocale: 'zh_CN',
+    whiteRoute: ['login'],
+    layout: 'classic',
+    pageAnimate: 'ma-slide-down',
+    enableWatermark: false,
+    primaryColor: '#2563EB',
+    asideDark: false,
+    showBreadcrumb: true,
+    loadUserSetting: true,
+    watermarkText: import.meta.env.VITE_APP_TITLE,
+  },
+  welcomePage: {
+    name: 'welcome',
+    path: '/welcome',
+    title: '欢迎页',
+    icon: 'icon-park-outline:jewelry',
+  },
+  mainAside: {
+    showIcon: true,
+    showTitle: true,
+    enableOpenFirstRoute: false,
+  },
+  subAside: {
+    showIcon: true,
+    showTitle: true,
+    fixedAsideState: false,
+    showCollapseButton: true,
+  },
+  tabbar: {
+    enable: true,
+    mode: 'rectangle',
+  },
+  copyright: {
+    enable: true,
+    dates: useDayjs().format('YYYY'),
+    company: 'MineAdmin Team',
+    website: 'https://www.mineadmin.com',
+    putOnRecord: '豫ICP备00000000号-1',
+  },
+}
+```

docs/zh/front/advanced/tools.md

@@ -1 +1,90 @@
-# 工具栏扩展
+# 工具栏扩展
+
+:::tip 提示
+右上角一排图标按钮，就是工具栏，系统开放了接口可以扩展工具栏。
+:::
+![工具栏](https://s21.ax1x.com/2024/10/24/pAwKsvq.jpg)
+
+## 获取工具栏助手函数实例
+
+::: code-group
+
+```vue [useGlobal() 方式]
+<!-- 在 `setup()` 生命周期或者可以获取到 `Vue上下文` 中的代码里获取方式 -->
+<script setup lang="ts">
+const toolbar = useGlobal().$toolbars
+</script>
+```
+
+```ts [通过 Vue 实例获取]
+// 通过当前实例获取
+const { appContext } = getCurrentInstance()
+const toolbar = appContext.config.globalProperties.$toolbars
+
+```
+
+```ts [插件内获取方法]
+/**
+ * 系统插件 `install` 方法，外部会传入 Vue 实例，然后获取 toolbar
+ * 可参考 `src/plugins/mine-admin/demo/index.ts`
+ **/
+install(app: App) {
+  const toolbar = app.config.globalProperties.$toolbars
+}
+```
+:::
+
+## toolbar API列表
+|       API        |               类型               |     说明     |      返回值       |
+|:----------------:|:------------------------------:|:----------:|:--------------:|
+|  getShowToolbar  |            Function            | 获取启用的工具列表  | MineToolbar[]  |
+|     toolbars     |       Ref<MineToolbar[]>       |  注册的工具列表   | MineToolbar[]  |
+|  add  | Function(toolbar: MineToolbar) | 向工具栏注册新工具  |      void      |
+|  remove  |     Function(name: string)     | 移除工具栏注册的工具 |      void      |
+
+## MineToolbar 类型
+```ts
+interface MineToolbar {
+  name: string
+  icon: string
+  title: string | (() => string)
+  show: boolean
+  className?: string | (() => string)
+  component?: () => any
+  handle?: (toolbar: MineToolbar) => any
+}
+```
+## 注册新工具
+
+:::tip
+`handle` 事件和 `component` 属性冲突，两者只会生效一种，`handle` 优先级高。
+如若使用 `component` 请不要定义 `handle` 或者注释掉
+:::
+
+```ts
+const toolbar = useGlobal().$toolbars
+toolbar.add({
+  name: 'test',
+  title: '测试',
+  show: true,
+  icon: 'heroicons:archive-box',
+  // 工具被点击时，触发 handle 方法，可用于简单的弹窗提示等等
+  handle: () => alert('我是注册的新工具哦'),
+  /**
+   * 指定组件，完全通过组件来渲染显示
+   * 同时上面的 icon 属性将不被渲染，handle 方法也将失效
+   * 
+   * 注意：实际开发中，在使用 component 后需要将 handle 注释掉
+   **/
+  component: () => import('@/modules/demo/views/demo.vue')
+})
+```
+
+## 移除已注册的工具
+
+```ts
+const toolbar = useGlobal().$toolbars
+
+// 移除 name 为 test 的工具
+toolbar.remove('test')
+```