0x00 前言

​Vue-Vben-Admin​​​ 是一个免费开源的中后台模版。使用了最新的​​vue3​​​,​​vite2​​​,​​TypeScript​​等主流技术开发,开箱即用的中后台前端解决方案考。

本系列本着学习参考的目的,对项目代码进行深入分析 ,耐心读完,相信您会有所收获。


本系列需要一定的项目使用经验,建议先阅读项目的 ​​中文文档​​ ,会对理解非常有帮助。


0x.01 ????目录说明

项目主要目录结构及说明,接下来将一一深入分析介绍。

.
├── build # 打包脚本相关
├── mock # mock文件夹
├── public # 公共静态资源目录
├── src # 主目录
│ ├── api # 接口文件
│ ├── assets # 资源文件
│ ├── components # 公共组件
│ ├── design # 样式文件
│ ├── directives # 指令
│ ├── enums # 枚举/常量
│ ├── hooks # hook
│ ├── layouts # 布局文件
│ ├── locales # 多语言
│ ├── logics # 逻辑
│ ├── main.ts # 主入口
│ ├── router # 路由配置
│ ├── settings # 项目配置
│ ├── store # 数据仓库
│ ├── utils # 工具类
│ └── views # 页面
├── test # 测试
├── types # 类型文件
├── vite.config.ts # vite配置文件
└── windi.config.ts # windcss配置文件

0x.02 ???? 系统主入口

文件 ​​src/main.ts​​ 作为系统主入口,主要进行项目初始化操作。

在入口文件中引入​​windicss​​​,这样项目中就可以使用 [类实用程序] 或 [CSS 指令]。
同时引入项目中使用的通用样式,都存放于 ​​​src/design/​​ 下面,默认使用 less 作为预处理语言。

import 'virtual:windi-base.css';
import 'virtual:windi-components.css';
import '/@/design/index.less';
import 'virtual:windi-utilities.css';
// Register icon sprite
import 'virtual:svg-icons-register';


windcss 目前会造成本地开发内存溢出,所以后续可能会考虑切换到 TailwindCss 。


接下来执行 ​​bootstrap​​ 方法创建项目实列。

import App from './App.vue';
import { createApp } from 'vue';
import { initAppConfigStore } from '/@/logics/initAppConfig';
import { setupErrorHandle } from '/@/logics/error-handle';
import { router, setupRouter } from '/@/router';
import { setupRouterGuard } from '/@/router/guard';
import { setupStore } from '/@/store';
import { setupGlobDirectives } from '/@/directives';
import { setupI18n } from '/@/locales/setupI18n';
import { registerGlobComp } from '/@/components/registerGlobComp';

// 项目的初始化配置
async function bootstrap() {
// 创建应用实例
const app = createApp(App);
// 配置存储使用Pinia
setupStore(app);
// 初始化内部系统配置
initAppConfigStore();
// 注册全局组件
registerGlobComp(app);
// 多语言配置
await setupI18n(app);
// 配置路由
setupRouter(app);
// 路由守卫、权限判断、初始化缓存数据
setupRouterGuard(router);
// 注册全局指令
setupGlobDirectives(app);
// 配置全局错误处理
setupErrorHandle(app);
...

app.mount('#app');
}
bootstrap();

​bootstrap()​​ 执行时调用了很多方法用于初始化操作,包括配置存储、加载系统配置注册、注册全局组件、多语言配置、路由配置、路由守卫、权限过滤、注册全局指令等。接下来将快速概览下各方法:

setupStore

​src\store\index.ts​​​ 文件中声明 ​​setupStore​​ 方法,用于将创建一个 pinia 根存储并注册到应用程序中。

...
import { createPinia } from 'pinia';
// 创建一个 pinia(根存储)
const store = createPinia();
export function setupStore(app: App<Element>) {
// 注册到应用程序
app.use(store);
}

initAppConfigStore

​src\logics\initAppConfig.ts​​​ 文件中声明 ​​initAppConfigStore​​ 方法,用于加载并存储 国际化、主题风格、项目配置、页面加载、页面状态、顶栏配置、菜单配置等项目信息。

export function initAppConfigStore() {
const localeStore = useLocaleStore(); // 多语言国际化
const appStore = useAppStore(); // 应用状态(主题风格、项目配置、页面加载、页面状态等等)
// 项目配置 (主题颜色、主题模式、顶栏配置、菜单配置)
let projCfg: ProjectConfig = Persistent.getLocal(PROJ_CFG_KEY) as ProjectConfig;
projCfg = deepMerge(projectSetting, projCfg || {});
...

// 存储项目配置
appStore.setProjectConfig(projCfg);

// init dark mode 初始化暗黑模式
updateDarkTheme(darkMode);
if (darkMode === ThemeEnum.DARK) {
...
} else {
...
}
// init store 初始化国际化多语言
localeStore.initLocale();

// 清理过期的缓存
setTimeout(() => {
clearObsoleteStorage();
}, 16);
}

registerGlobComp

​src\components\registerGlobComp.ts​​​文件中声明 ​​registerGlobComp​​ 方法,全局注册 antdv的Input、Layout组件和手写的Button组件

import { Button } from './Button';
import { Input, Layout } from 'ant-design-vue';

export function registerGlobComp(app: App) {
// 注册 antdv的Input、Layout组件和手写的Button组件
app.use(Input).use(Button).use(Layout);
}

setupI18n

​src\locales\setupI18n.ts​​​ 文件中声明 ​​setupI18n​​​ 方法,初始化国际化插件 ​​vue-i18n​​ 实例并注册到应用程序中。

// 国际化插件 vue-i18n 配置项
async function createI18nOptions(): Promise<I18nOptions> {
const localeStore = useLocaleStoreWithOut(); // 国际化本地存储
const locale = localeStore.getLocale; // 语言环境/当前语言
const defaultLocal = await import(`./lang/${locale}.ts`); // 从服务器端获取语言翻译文件
const message = defaultLocal.default?.message ?? {}; // 本地化的语言环境信息
...

return {
legacy: false,
locale, // 语言环境
fallbackLocale: fallback, // 预设的语言环境
// 本地化的语言环境信息
messages: {
[locale]: message,
},
availableLocales: availableLocales, // 以词法顺序排列的 messages 中的可用语言环境列表
sync: true, // 是否将根级别语言环境与组件本地化语言环境同步。 如果为 false,则无论根级别语言环境如何,都要为每个组件语言环境进行本地化。
silentTranslationWarn: true, // true - warning off 是否取消本地化失败时输出的警告。如果为 true,则禁止本地化失败警告。
missingWarn: false,
silentFallbackWarn: true, // 是否在回退到 fallbackLocale 或 root 时取消警告。如果为 true,则仅在根本没有可用的转换时生成警告,而不是在回退时。
};
}

// 初始化国际化实例
export async function setupI18n(app: App) {
// 获取国际化插件 vue-i18n 配置项
const options = await createI18nOptions();
i18n = createI18n(options) as I18n;
app.use(i18n);
}

setupRouter

​src\router\index.ts​​​ 文件中声明 ​​setupRouter​​ 方法,创建路由实例,加载初始路由列表,注册到应用程序中。

// app router  创建路由实例
export const router = createRouter({
history: createWebHashHistory(import.meta.env.VITE_PUBLIC_PATH), // 基于 hash 的历史记录
routes: basicRoutes as unknown as RouteRecordRaw[], // 添加到路由的初始路由列表
scrollBehavior: () => ({ left: 0, top: 0 }), // 在页面之间导航时控制滚动的函数
});


// 注册路由
export function setupRouter(app: App<Element>) {
app.use(router);
}

setupRouterGuard

​src\router\guard\index.ts​​​ 文件中声明 ​​setupRouterGuard​​ 方法,创建了处理页面加载状态、路由切换、页面顶部进度条、权限验证、菜单及系统状态等守卫。

export function setupRouterGuard(router: Router) {
createPageGuard(router); // 处理页面状态
createPageLoadingGuard(router); // 处理页面加载状态
createHttpGuard(router); // 路由切换时关闭当前页面完成请求
createScrollGuard(router); // 路由切换回到顶部
createMessageGuard(router); // 路由切换时关闭消息实例
createProgressGuard(router); // 页面顶部进度条
createPermissionGuard(router); // 路由切换时权限验证
createParamMenuGuard(router); // 菜单守卫
createStateGuard(router); // 系统状态守卫- 当用户未登录时,进入登录页面并清除存储中的认证信息
}

setupErrorHandle

​src\logics\error-handle\index.ts​​​ 文件中声明 ​​setupErrorHandle​​ 方法,配置全局错误处理,用于监控Vue异常、脚本错误、promise 异常、 静态资源异常等。

/**
* Configure global error handling 配置全局错误处理
* @param app
*/
export function setupErrorHandle(app: App) {
const { useErrorHandle } = projectSetting;
if (!useErrorHandle) {
return;
}
// Vue exception monitoring; Vue异常监控
app.config.errorHandler = vueErrorHandler;

// script error 脚本错误监控
window.onerror = scriptErrorHandler;

// promise exception promise 异常监控
registerPromiseErrorHandler();

// Static resource exception 静态资源异常监控
registerResourceErrorHandler();
}

本文主要概述了项目实例创建时初始化的流程,接下来我们将逐一分析每个模块的功能。