vben-admin-一个前端开箱即用的企业级管理系统框架

Vben Admin企业级管理系统框架

目次

• 框架先容
  
• 核心特点
  
• 项目结构
  
• 快速开始
  
• 核心功能详解
  
• 最佳实践
  
• 常见问题与解决方案
  
• 资源与社区
  

1. 框架先容

1.1 什么是Vben Admin

Vben Admin是一个基于Vue 3、Vite、TypeScript和Ant Design Vue的企业级中后台管理系统框架。它提供了一套完备的解决方案，资助开发者快速搭建当代化的管理系统。
1.2 框架优势

• 开箱即用：提供丰富的组件和功能，减少重复开发
  
• 高度可定制：支持主题定制、布局定制、组件定制等
  
• 性能良好：基于Vue 3和Vite，提供极速的开发体验和良好的性能
  
• 类型安全：全面支持TypeScript，提供类型安全和更好的开发体验
  
• 社区活跃：拥有活跃的社区和持续的更新维护
  

1.3 适用场景

• 企业级中后台管理系统
  
• 数据可视化平台
  
• 内容管理系统
  
• 工作流管理系统
  
• 权限管理系统
  

2. 核心特点

2.1 技术栈先进

• Vue 3：接纳最新的Vue 3框架，享受Composition API带来的开发体验提拔
  
• TypeScript：全面支持TypeScript，提供类型安全和更好的开发体验
  
• Vite：使用Vite作为构建工具，提供极速的开发体验
  
• Ant Design Vue：基于Ant Design设计规范，提供丰富的UI组件
  
• Pinia：使用Pinia进行状态管理，提供更好的TypeScript支持
  
• Vue Router：使用Vue Router进行路由管理，支持动态路由
  

2.2 功能完满

• 权限管理：基于角色的访问控制(RBAC)，支持动态路由和权限验证
  
• 主题设置：支持多主题切换，可自定义主题色和布局
  
• 国际化：内置国际化解决方案，支持多语言切换
  
• 组件封装：封装了常用的业务组件，如表格、表单、图表等
  
• Mock数据：内置Mock数据服务，方便前后端分离开发
  
• 错误处置处罚：内置全局错误处置处罚机制，提供友爱的错误提示
  
• 日志系统：内置日志系统，方便问题排查和用户举动分析
  

2.3 开发体验

• 代码规范：接纳ESLint、Prettier等工具包管代码质量
  
• Git提交规范：使用commitlint规范Git提交信息
  
• 自动导入：支持组件和API的自动导入，减少重复代码
  
• 热更新：支持模块热更新，提高开发服从
  
• TypeScript支持：提供完备的类型定义，提高开发服从和代码质量
  
• 开发工具：提供丰富的开发工具，如调试工具、性能分析工具等
  

3. 项目结构

1. ├── build                 # 构建相关配置
2. ├── mock                  # Mock数据
3. ├── public                # 静态资源
4. ├── src                   # 源代码
5. │   ├── api               # API接口
6. │   ├── assets            # 静态资源
7. │   ├── components        # 公共组件
8. │   ├── design            # 样式文件
9. │   ├── enums             # 枚举定义
10. │   ├── hooks             # Vue Hooks
11. │   ├── layouts           # 布局组件
12. │   ├── locales           # 国际化资源
13. │   ├── router            # 路由配置
14. │   ├── settings          # 项目配置
15. │   ├── store              # 状态管理
16. │   ├── utils              # 工具函数
17. │   ├── views              # 页面组件
18. │   ├── App.vue            # 根组件
19. │   └── main.ts            # 入口文件
20. ├── types                  # 类型定义
21. ├── .env                   # 环境变量
22. ├── .eslintrc.js           # ESLint配置
23. ├── .prettierrc            # Prettier配置
24. ├── package.json           # 项目依赖
25. ├── tsconfig.json          # TypeScript配置
26. └── vite.config.ts         # Vite配置

复制代码

3.1 核心目次阐明

src/api

API接口定义，按模块划分，每个模块对应一个文件。

1. // src/api/sys/user.ts
2. import { defHttp } from '/@/utils/http/axios';
4. enum Api {
5.   UserList = '/system/user/list',
6.   UserInfo = '/system/user/info',
7.   UserAdd = '/system/user/add',
8.   UserEdit = '/system/user/edit',
9.   UserDelete = '/system/user/delete',
10. }
12. export const getUserList = (params) => defHttp.get({ url: Api.UserList, params });
13. export const getUserInfo = (id) => defHttp.get({ url: Api.UserInfo, params: { id } });
14. export const addUser = (data) => defHttp.post({ url: Api.UserAdd, data });
15. export const editUser = (data) => defHttp.post({ url: Api.UserEdit, data });
16. export const deleteUser = (id) => defHttp.delete({ url: Api.UserDelete, params: { id } });

复制代码

src/components

公共组件，包括基础组件和业务组件。

1. <!-- src/components/Button/src/BasicButton.vue -->
2. <template>
3.   <a-button v-bind="getBindValue" :class="getButtonClass" @click="handleClick">
4.     <template v-if="icon">
5.       <component :is="icon" />
6.     </template>
7.     <slot></slot>
8.   </a-button>
9. </template>
11. <script lang="ts">
12. import { defineComponent, computed, unref } from 'vue';
13. import { Button } from 'ant-design-vue';
14. import { useAttrs } from '/@/hooks/component/useAttrs';
15. import { useDesign } from '/@/hooks/web/useDesign';
17. export default defineComponent({
18.   name: 'BasicButton',
19.   components: { [Button.name]: Button },
20.   props: {
21.     type: {
22.       type: String,
23.       default: 'default',
24.     },
25.     icon: {
26.       type: String,
27.       default: '',
28.     },
29.   },
30.   emits: ['click'],
31.   setup(props, { emit }) {
32.     const { prefixCls } = useDesign('basic-button');
33.     const { getAttrs } = useAttrs();
35.     const getBindValue = computed(() => ({ ...getAttrs(), ...props }));
36.     const getButtonClass = computed(() => [prefixCls]);
38.     function handleClick(e: MouseEvent) {
39.       emit('click', e);
40.     }
42.     return {
43.       getBindValue,
44.       getButtonClass,
45.       handleClick,
46.     };
47.   },
48. });
49. </script>

复制代码

src/hooks

Vue Hooks，提供可复用的逻辑。

1. // src/hooks/web/usePermission.ts
2. import { useUserStoreWithOut } from '/@/store/modules/user';
4. export function usePermission() {
5.   const userStore = useUserStoreWithOut();
6.   const { role } = userStore.getUserInfo;
8.   function hasPermission(value: string | string[]): boolean {
9.     if (!value) {
10.       return true;
11.     }
12.     if (!role) {
13.       return false;
14.     }
15.     if (Array.isArray(value)) {
16.       return value.some((item) => role.includes(item));
17.     }
18.     return role.includes(value);
19.   }
21.   return {
22.     hasPermission,
23.   };
24. }

复制代码

src/router

路由设置，包括静态路由和动态路由。

1. // src/router/routes/index.ts
2. import type { AppRouteRecordRaw } from '/@/router/types';
3. import { PAGE_NOT_FOUND_ROUTE, REDIRECT_ROUTE } from '/@/router/routes/basic';
4. import { PageEnum } from '/@/enums/pageEnum';
5. import { t } from '/@/hooks/web/useI18n';
7. // 根路由
8. export const RootRoute: AppRouteRecordRaw = {
9.   path: '/',
10.   name: 'Root',
11.   redirect: PageEnum.BASE_HOME,
12.   meta: {
13.     title: 'Root',
14.   },
15. };
17. // 登录路由
18. export const LoginRoute: AppRouteRecordRaw = {
19.   path: '/login',
20.   name: 'Login',
21.   component: () => import('/@/views/sys/login/Login.vue'),
22.   meta: {
23.     title: t('routes.basic.login'),
24.   },
25. };
27. // 基础路由
28. export const basicRoutes = [
29.   LoginRoute,
30.   RootRoute,
31.   ...PAGE_NOT_FOUND_ROUTE,
32.   ...REDIRECT_ROUTE,
33. ];

复制代码

src/store

状态管理，使用Pinia进行状态管理。

1. // src/store/modules/user.ts
2. import { defineStore } from 'pinia';
3. import { store } from '/@/store';
4. import { UserInfo } from '/@/api/sys/model/userModel';
5. import { getAuthCache, setAuthCache } from '/@/utils/auth';
6. import { TOKEN_KEY, USER_INFO_KEY } from '/@/enums/cacheEnum';
8. interface UserState {
9.   userInfo: Nullable<UserInfo>;
10.   token?: string;
11.   roleList: string[];
12.   sessionTimeout?: boolean;
13. }
15. export const useUserStore = defineStore({
16.   id: 'app-user',
17.   state: (): UserState => ({
18.     userInfo: null,
19.     token: undefined,
20.     roleList: [],
21.     sessionTimeout: false,
22.   }),
23.   getters: {
24.     getUserInfo(): Nullable<UserInfo> {
25.       return this.userInfo || getAuthCache<UserInfo>(USER_INFO_KEY);
26.     },
27.     getToken(): string {
28.       return this.token || getAuthCache<string>(TOKEN_KEY);
29.     },
30.     getRoleList(): string[] {
31.       return this.roleList.length > 0 ? this.roleList : [];
32.     },
33.     getSessionTimeout(): boolean {
34.       return !!this.sessionTimeout;
35.     },
36.   },
37.   actions: {
38.     setToken(token: string | undefined) {
39.       this.token = token;
40.       setAuthCache(TOKEN_KEY, token);
41.     },
42.     setUserInfo(info: UserInfo | null) {
43.       this.userInfo = info;
44.       setAuthCache(USER_INFO_KEY, info);
45.     },
46.     setRoleList(roleList: string[]) {
47.       this.roleList = roleList;
48.     },
49.     setSessionTimeout(flag: boolean) {
50.       this.sessionTimeout = flag;
51.     },
52.     resetState() {
53.       this.userInfo = null;
54.       this.token = '';
55.       this.roleList = [];
56.       this.sessionTimeout = false;
57.     },
58.   },
59. });
61. // 在setup外使用
62. export function useUserStoreWithOut() {
63.   return useUserStore(store);
64. }

复制代码

src/utils

工具函数，提供常用的工具方法。

1. // src/utils/http/axios/index.ts
2. import type { AxiosRequestConfig, AxiosInstance, AxiosResponse, AxiosError } from 'axios';
3. import axios from 'axios';
4. import { clone } from 'lodash-es';
5. import { ContentTypeEnum } from '/@/enums/httpEnum';
6. import { useUserStoreWithOut } from '/@/store/modules/user';
7. import { joinTimestamp, formatRequestDate } from './helper';
8. import { createAxiosTransform } from './axiosTransform';
9. import { checkStatus } from './checkStatus';
10. import { useGlobSetting } from '/@/hooks/setting';
11. import { RequestOptions, Result } from '/@/types/axios';
12. import { AxiosRetry } from './axiosRetry';
13. import { getToken } from '/@/utils/auth';
15. const globSetting = useGlobSetting();
16. const urlPrefix = globSetting.urlPrefix;
18. export class VAxios {
19.   private axiosInstance: AxiosInstance;
20.   private readonly options: CreateAxiosOptions;
22.   constructor(options: CreateAxiosOptions) {
23.     this.options = options;
24.     this.axiosInstance = axios.create(options);
25.     this.setupInterceptors();
26.   }
28.   private createAxios(config: AxiosRequestConfig) {
29.     this.axiosInstance = axios.create(config);
30.   }
32.   private getTransform() {
33.     const { transform } = this.options;
34.     if (!transform) {
35.       return;
36.     }
37.     return transform;
38.   }
40.   getAxios(): AxiosInstance {
41.     return this.axiosInstance;
42.   }
44.   configAxios(config: AxiosRequestConfig) {
45.     if (!this.axiosInstance) {
46.       return;
47.     }
48.     this.createAxios(config);
49.   }
51.   setupInterceptors() {
52.     const transform = this.getTransform();
53.     if (!transform) {
54.       return;
55.     }
57.     const {
58.       requestInterceptors,
59.       requestInterceptorsCatch,
60.       responseInterceptors,
61.       responseInterceptorsCatch,
62.     } = transform;
64.     // 请求拦截器配置处理
65.     this.axiosInstance.interceptors.request.use((config: AxiosRequestConfig) => {
66.       // 请求之前处理config
67.       if (requestInterceptors) {
68.         config = requestInterceptors(config, this.options);
69.       }
70.       return config;
71.     }, undefined);
73.     // 请求拦截器错误捕获
74.     requestInterceptorsCatch &&
75.       this.axiosInstance.interceptors.request.use(undefined, requestInterceptorsCatch);
77.     // 响应结果拦截器处理
78.     this.axiosInstance.interceptors.response.use((res: AxiosResponse<any>) => {
79.       // 响应数据处理
80.       if (responseInterceptors) {
81.         res = responseInterceptors(res);
82.       }
83.       return res;
84.     }, undefined);
86.     // 响应结果拦截器错误捕获
87.     responseInterceptorsCatch &&
88.       this.axiosInstance.interceptors.response.use(undefined, responseInterceptorsCatch);
89.   }
91.   // 请求方法
92.   request<T = any>(config: AxiosRequestConfig, options?: RequestOptions): Promise<T> {
93.     let conf: AxiosRequestConfig = clone(config);
94.     const transform = this.getTransform();
96.     const { requestOptions } = this.options;
98.     const opt: RequestOptions = Object.assign({}, requestOptions, options);
100.     const { beforeRequestHook, requestCatchHook, transformResponseHook } = transform || {};
101.     if (beforeRequestHook) {
102.       conf = beforeRequestHook(conf, opt);
103.     }
104.     conf.requestOptions = opt;
106.     conf = this.supportFormData(conf);
108.     return new Promise((resolve, reject) => {
109.       this.axiosInstance
110.         .request<any, AxiosResponse<Result>>(conf)
111.         .then((res: AxiosResponse<Result>) => {
112.           if (transformResponseHook) {
113.             try {
114.               res = transformResponseHook(res, opt);
115.             } catch (err) {
116.               reject(err || new Error('request error!'));
117.             }
118.             return res;
119.           }
120.           resolve(res as unknown as Promise<T>);
121.         })
122.         .catch((e: Error | AxiosError) => {
123.           if (requestCatchHook && e) {
124.             reject(requestCatchHook(e, opt));
125.             return;
126.           }
127.           if (Axios.isAxiosError(e)) {
128.             // 这里对错误信息进行细分处理
129.             const error = this.handleAxiosError(e);
130.             reject(error);
131.           } else {
132.             let error = new Error(e.message) as Error & { code?: string };
133.             error.code = 'NO_AXIOS_ERROR';
134.             reject(error);
135.           }
136.         });
137.     });
138.   }
140.   // 支持FormData
141.   supportFormData(config: AxiosRequestConfig) {
142.     const { requestOptions } = config;
143.     const contentType = requestOptions?.headers?.['Content-Type'];
144.     const isFormData =
145.       contentType !== ContentTypeEnum.FORM_URLENCODED &&
146.       contentType !== ContentTypeEnum.FORM_DATA;
148.     if (isFormData && config.method?.toUpperCase() === 'GET') {
149.       config.params = Object.assign({}, config.params || {});
150.       Object.keys(config.params).forEach((key) => {
151.         if (
152.           config.params[key] !== null &&
153.           typeof config.params[key] === 'object' &&
154.           !Array.isArray(config.params[key])
155.         ) {
156.           config.params[key] = JSON.stringify(config.params[key]);
157.         }
158.       });
159.     } else {
160.       config.data = config.data || config.params;
161.     }
162.     return config;
163.   }
165.   // 处理Axios错误
166.   private handleAxiosError(error: AxiosError) {
167.     const { response } = error;
168.     let errorMessage = '请求错误';
169.     if (response) {
170.       const { status, data } = response;
171.       errorMessage = checkStatus(status, data);
172.     }
173.     const errorObj = new Error(errorMessage) as Error & { code?: string };
174.     errorObj.code = error.response?.status?.toString() || 'NO_STATUS';
175.     return errorObj;
176.   }
177. }
179. // 创建axios实例
180. export const createAxios = (opt?: Partial<CreateAxiosOptions>) => {
181.   return new VAxios(
182.     deepMerge(
183.       {
184.         timeout: 10 * 1000,
185.         headers: { 'Content-Type': ContentTypeEnum.JSON },
186.         // 数据处理方式
187.         transform: clone(createAxiosTransform()),
188.         // 配置项，下面的选项都可以在独立的接口请求中覆盖
189.         requestOptions: {
190.           // 默认将prefix 添加到url
191.           joinPrefix: true,
192.           // 是否返回原生响应头 比如：需要获取响应头时使用该属性
193.           isReturnNativeResponse: false,
194.           // 需要对返回数据进行处理
195.           isTransformResponse: true,
196.           // post请求的时候添加参数到url
197.           joinParamsToUrl: false,
198.           // 格式化提交参数时间
199.           formatDate: true,
200.           // 消息提示类型
201.           errorMessageMode: 'message',
202.           // 接口地址
203.           apiUrl: globSetting.apiUrl,
204.           // 请求拼接地址
205.           urlPrefix: urlPrefix,
206.           // 是否加入时间戳
207.           joinTime: true,
208.           // 忽略重复请求
209.           ignoreCancelToken: true,
210.           // 是否携带token
211.           withToken: true,
212.           retryRequest: {
213.             isOpenRetry: true,
214.             count: 5,
215.             waitTime: 100,
216.           },
217.         },
218.       },
219.       opt || {},
220.     ),
221.   );
222. };
224. // 导出axios实例
225. export const defHttp = createAxios();

复制代码

src/views

页面组件，按模块划分。

1. <!-- src/views/dashboard/analysis/index.vue -->
2. <template>
3.   <div>
4.     <PageHeader title="分析页" />
5.     <a-card :bordered="false">
6.       <a-row :gutter="16">
7.         <a-col :span="6">
8.           <a-statistic
9.             title="总销售额"
10.             :value="112893"
11.             :precision="2"
12.             :value-style="{ color: '#3f8600' }"
13.           >
14.             <template #prefix>
15.               <TrendCharts option="up" />
16.             </template>
17.           </a-statistic>
18.         </a-col>
19.         <a-col :span="6">
20.           <a-statistic
21.             title="访问人数"
22.             :value="8846"
23.             :value-style="{ color: '#cf1322' }"
24.           >
25.             <template #prefix>
26.               <UserOutlined />
27.             </template>
28.           </a-statistic>
29.         </a-col>
30.         <a-col :span="6">
31.           <a-statistic
32.             title="支付笔数"
33.             :value="6560"
34.             :value-style="{ color: '#3f8600' }"
35.           >
36.             <template #prefix>
37.               <ShoppingOutlined />
38.             </template>
39.           </a-statistic>
40.         </a-col>
41.         <a-col :span="6">
42.           <a-statistic
43.             title="运营活动效果"
44.             :value="78"
45.             :suffix="'%'"
46.             :value-style="{ color: '#3f8600' }"
47.           >
48.             <template #prefix>
49.               <LikeOutlined />
50.             </template>
51.           </a-statistic>
52.         </a-col>
53.       </a-row>
54.       <a-divider />
55.       <a-row :gutter="16">
56.         <a-col :span="12">
57.           <VisitData />
58.         </a-col>
59.         <a-col :span="12">
60.           <SalesData />
61.         </a-col>
62.       </a-row>
63.     </a-card>
64.   </div>
65. </template>
67. <script lang="ts">
68. import { defineComponent } from 'vue';
69. import { UserOutlined, ShoppingOutlined, LikeOutlined } from '@ant-design/icons-vue';
70. import { PageHeader } from '/@/components/Page';
71. import { TrendCharts } from '/@/components/Charts';
72. import VisitData from './components/VisitData.vue';
73. import SalesData from './components/SalesData.vue';
75. export default defineComponent({
76.   name: 'Analysis',
77.   components: {
78.     PageHeader,
79.     TrendCharts,
80.     VisitData,
81.     SalesData,
82.     UserOutlined,
83.     ShoppingOutlined,
84.     LikeOutlined,
85.   },
86. });
87. </script>

复制代码

4. 快速开始

4.1 环境准备

• Node.js >= 14.0.0
  
• pnpm >= 6.0.0 (保举使用pnpm作为包管理工具)
  

4.2 安装依赖

1. # 使用pnpm
2. pnpm install
4. # 使用yarn
5. yarn install
7. # 使用npm
8. npm install

复制代码

4.3 开发环境运行

1. # 使用pnpm
2. pnpm dev
4. # 使用yarn
5. yarn dev
7. # 使用npm
8. npm run dev

复制代码

4.4 生产环境构建

1. # 使用pnpm
2. pnpm build
4. # 使用yarn
5. yarn build
7. # 使用npm
8. npm run build

复制代码

4.5 代码格式检查

1. # 使用pnpm
2. pnpm lint
4. # 使用yarn
5. yarn lint
7. # 使用npm
8. npm run lint

复制代码

5. 核心功能详解

5.1 权限管理

Vben Admin接纳基于角色的权限管理系统，支持以下功能：

• 动态路由：根据用户角色动态生成路由
  
• 权限指令：提供v-auth指令控制元素表现
  
• 权限函数：提供hasPermission函数判断权限
  
• 菜单权限：根据用户角色表现对应菜单
  

1. // 权限指令使用示例
2. <button v-auth="'user:add'">添加用户</button>
4. // 权限函数使用示例
5. import { usePermission } from '/@/hooks/web/usePermission';
7. const { hasPermission } = usePermission();
8. if (hasPermission('user:edit')) {
9.   // 有编辑权限
10. }

复制代码

5.1.1 权限指令实现

1. // src/directives/auth/index.ts
2. import type { App } from 'vue';
3. import { usePermission } from '/@/hooks/web/usePermission';
5. function isAuth(el: Element, binding: any) {
6.   const { hasPermission } = usePermission();
7.   const { value } = binding;
8.   if (value && value instanceof Array && value.length > 0) {
9.     const hasAuth = value.some((item) => {
10.       return hasPermission(item);
11.     });
12.     if (!hasAuth) {
13.       el.parentNode && el.parentNode.removeChild(el);
14.     }
15.   } else {
16.     throw new Error('请设置操作权限标签值');
17.   }
18. }
20. export function setupAuthDirective(app: App) {
21.   app.directive('auth', {
22.     mounted(el: Element, binding: any) {
23.       isAuth(el, binding);
24.     },
25.     updated(el: Element, binding: any) {
26.       isAuth(el, binding);
27.     },
28.   });
29. }

复制代码

5.1.2 动态路由实现

1. // src/router/helper/permissionHelper.ts
2. import type { AppRouteRecordRaw } from '/@/router/types';
3. import { usePermissionStoreWithOut } from '/@/store/modules/permission';
4. import { useUserStoreWithOut } from '/@/store/modules/user';
5. import { toRaw } from 'vue';
6. import { unref } from 'vue';
7. import { getDynamicParams } from '/@/router/helper';
9. export function filterAsyncRoutes(routes: AppRouteRecordRaw[], roles: string[]) {
10.   const res: AppRouteRecordRaw[] = [];
12.   routes.forEach((route) => {
13.     const tmp = { ...route };
14.     if (hasPermission(roles, tmp)) {
15.       if (tmp.children) {
16.         tmp.children = filterAsyncRoutes(tmp.children, roles);
17.       }
18.       res.push(tmp);
19.     }
20.   });
22.   return res;
23. }
25. function hasPermission(roles: string[], route: AppRouteRecordRaw) {
26.   if (route.meta && route.meta.roles) {
27.     return roles.some((role) => route.meta?.roles?.includes(role));
28.   } else {
29.     return true;
30.   }
31. }
33. export async function generateDynamicRoutes() {
34.   const permissionStore = usePermissionStoreWithOut();
35.   const userStore = useUserStoreWithOut();
36.   const { roles } = userStore.getUserInfo;
38.   let accessedRoutes;
39.   if (roles.includes('admin')) {
40.     accessedRoutes = permissionStore.getRoutes;
41.   } else {
42.     accessedRoutes = filterAsyncRoutes(toRaw(permissionStore.getRoutes), roles);
43.   }
44.   return accessedRoutes;
45. }

复制代码

5.2 主题设置

支持多主题切换和自定义主题：

• 预设主题：提供多种预设主题
  
• 自定义主题：支持自定义主题色和布局
  
• 暗黑模式：支持暗黑模式切换
  
• 主题持久化：主题设置可持久化到本地存储
  

1. // 切换主题示例
2. import { useTheme } from '/@/hooks/web/useTheme';
4. const { setTheme } = useTheme();
5. setTheme('dark'); // 切换到暗黑主题

复制代码

5.2.1 主题设置实现

1. // src/hooks/web/useTheme.ts
2. import { useDesign } from '/@/hooks/web/useDesign';
3. import { useStorage } from '/@/hooks/web/useStorage';
4. import { ThemeEnum } from '/@/enums/appEnum';
6. const { prefixCls } = useDesign('app');
7. const { setStorage, getStorage } = useStorage();
9. export function useTheme() {
10.   const getTheme = () => {
11.     return getStorage(prefixCls + 'theme') || ThemeEnum.LIGHT;
12.   };
14.   const setTheme = (theme: ThemeEnum) => {
15.     setStorage(prefixCls + 'theme', theme);
16.     document.documentElement.setAttribute('data-theme', theme);
17.   };
19.   return {
20.     getTheme,
21.     setTheme,
22.   };
23. }

复制代码

5.3 国际化

内置国际化解决方案，支持多语言切换：

• 语言包：内置中文和英文语言包
  
• 动态加载：支持按需加载语言包
  
• 语言持久化：语言选择可持久化到本地存储
  

1. // 切换语言示例
2. import { useLocale } from '/@/hooks/web/useLocale';
4. const { setLocale } = useLocale();
5. setLocale('en'); // 切换到英文

复制代码

5.3.1 国际化实现

1. // src/locales/index.ts
2. import type { App } from 'vue';
3. import { createI18n } from 'vue-i18n';
4. import { useLocaleStoreWithOut } from '/@/store/modules/locale';
5. import { localeSetting } from '/@/settings/localeSetting';
6. import { setHtmlPageLang } from '/@/utils/locale';
7. import { getLocale } from './helper';
9. const { fallback, availableLocales } = localeSetting;
11. export let i18n: ReturnType<typeof createI18n>;
13. async function createI18nOptions() {
14.   const locale = getLocale();
15.   const defaultLocal = await import(`./lang/${locale}.ts`);
16.   const message = defaultLocal.default?.message ?? {};
18.   return {
19.     legacy: false,
20.     locale,
21.     fallbackLocale: fallback,
22.     messages: {
23.       [locale]: message,
24.     },
25.   };
26. }
28. export async function setupI18n(app: App) {
29.   const options = await createI18nOptions();
30.   i18n = createI18n(options) as ReturnType<typeof createI18n>;
31.   app.use(i18n);
32.   setHtmlPageLang(options.locale);
33.   return i18n;
34. }

复制代码

5.4 组件封装

封装了常用的业务组件，提高开发服从：

• 表格组件：支持自定义列、排序、筛选、分页等
  
• 表单组件：支持动态表单、表单验证、自定义校验等
  
• 图表组件：集成ECharts，提供常用图表组件
  
• 上传组件：支持单文件、多文件上传，支持图片预览等
  

1. <!-- 表格组件使用示例 -->
2. <template>
3.   <BasicTable @register="registerTable">
4.     <template #toolbar>
5.       <a-button type="primary" @click="handleCreate">新增</a-button>
6.     </template>
7.     <template #action="{ record }">
8.       <TableAction
9.         :actions="[
10.           {
11.             icon: 'clarity:note-edit-line',
12.             tooltip: '编辑',
13.             onClick: handleEdit.bind(null, record),
14.           },
15.           {
16.             icon: 'ant-design:delete-outlined',
17.             color: 'error',
18.             tooltip: '删除',
19.             popConfirm: {
20.               title: '是否确认删除',
21.               confirm: handleDelete.bind(null, record),
22.             },
23.           },
24.         ]"
25.       />
26.     </template>
27.   </BasicTable>
28. </template>
30. <script lang="ts">
31. import { defineComponent, ref, unref } from 'vue';
32. import { BasicTable, useTable, TableAction } from '/@/components/Table';
33. import { useMessage } from '/@/hooks/web/useMessage';
34. import { columns, searchFormSchema } from './user.data';
35. import { getUserList, deleteUser } from '/@/api/sys/user';
37. export default defineComponent({
38.   name: 'UserManagement',
39.   components: { BasicTable, TableAction },
40.   setup() {
41.     const { createMessage } = useMessage();
42.     const [registerTable, { reload }] = useTable({
43.       title: '用户列表',
44.       api: getUserList,
45.       columns,
46.       formConfig: {
47.         labelWidth: 120,
48.         schemas: searchFormSchema,
49.       },
50.       useSearchForm: true,
51.       showTableSetting: true,
52.       bordered: true,
53.       actionColumn: {
54.         width: 80,
55.         title: '操作',
56.         dataIndex: 'action',
57.         slots: { customRender: 'action' },
58.         fixed: false,
59.       },
60.     });
62.     function handleCreate() {
63.       // 处理创建用户
64.     }
66.     function handleEdit(record: Recordable) {
67.       // 处理编辑用户
68.     }
70.     async function handleDelete(record: Recordable) {
71.       await deleteUser(record.id);
72.       createMessage.success('删除成功');
73.       reload();
74.     }
76.     return {
77.       registerTable,
78.       handleCreate,
79.       handleEdit,
80.       handleDelete,
81.     };
82.   },
83. });
84. </script>

复制代码

5.4.1 表格组件实现

1. // src/components/Table/src/hooks/useTable.ts
2. import type { BasicTableProps, TableActionType } from '../types/table';
3. import { ref, onMounted, unref } from 'vue';
4. import { isProdMode } from '/@/utils/env';
5. import { error } from '/@/utils/log';
6. import { getDynamicProps } from '/@/utils';
8. export function useTable(
9.   getProps?: (props: Partial<BasicTableProps>) => Partial<BasicTableProps>,
10. ) {
11.   const tableRef = ref<Nullable<TableActionType>>(null);
12.   const loadedRef = ref<Nullable<boolean>>(false);
13.   const innerPropsRef = ref<Partial<BasicTableProps>>({});
15.   function register(instance: TableActionType) {
16.     isProdMode() &&
17.       tableRef.value &&
18.       tableRef.value.setProps(getDynamicProps(getProps, unref(innerPropsRef)));
19.     tableRef.value = instance;
20.   }
22.   function getTableInstance() {
23.     const table = unref(tableRef);
24.     if (!table) {
25.       error('表格实例尚未注册，请在onMounted后调用');
26.     }
27.     return table;
28.   }
30.   const methods: TableActionType = {
31.     reload: async (opt?: any) => {
32.       getTableInstance().reload(opt);
33.     },
34.     setProps: (props: Partial<BasicTableProps>) => {
35.       getTableInstance().setProps(props);
36.     },
37.     // 其他方法...
38.   };
40.   onMounted(() => {
41.     loadedRef.value = true;
42.   });
44.   return [register, methods];
45. }

复制代码

5.5 状态管理

使用Pinia进行状态管理，提供更好的TypeScript支持：

• 模块化：按功能模块划分状态
  
• 类型安全：提供完备的类型定义
  
• 持久化：支持状态持久化到本地存储
  
• 开发工具：支持Vue DevTools调试
  

1. // 状态管理使用示例
2. import { useUserStoreWithOut } from '/@/store/modules/user';
4. const userStore = useUserStoreWithOut();
5. const { userInfo } = userStore.getUserInfo;

复制代码

5.5.1 状态管理实现

1. // src/store/index.ts
2. import type { App } from 'vue';
3. import { createPinia } from 'pinia';
4. import { registerStores } from '/@/store/helper';
6. export function setupStore(app: App) {
7.   const store = createPinia();
8.   app.use(store);
9.   registerStores(store);
10.   return store;
11. }

复制代码

6. 最佳实践

6.1 项目初始化

1. # 克隆项目
2. git clone https://github.com/vbenjs/vue-vben-admin.git
4. # 进入项目目录
5. cd vue-vben-admin
7. # 安装依赖
8. pnpm install
10. # 启动项目
11. pnpm dev

复制代码

6.2 开发规范

• 定名规范：组件名使用PascalCase，文件名使用kebab-case
  
• 目次结构：按功能模块划分目次，保持结构清楚
  
• 代码风格：遵照ESLint和Prettier设置的代码风格
  
• Git提交：遵照commitlint规范的提交信息格式
  

6.3 性能优化

• 按需加载：路由和组件按需加载，减少首屏加载时间
  
• 缓存优化：合理使用keep-alive缓存组件
  
• 打包优化：设置splitChunks分割代码，减少包体积
  
• 图片优化：使用webp格式和懒加载优化图片加载
  

6.3.1 按需加载实现

1. // 路由按需加载
2. const routes = [
3.   {
4.     path: '/dashboard',
5.     name: 'Dashboard',
6.     component: () => import('/@/views/dashboard/index.vue'),
7.   },
8. ];

复制代码

6.3.2 打包优化实现

1. // vite.config.ts
2. export default defineConfig({
3.   build: {
4.     target: 'es2015',
5.     outDir: 'dist',
6.     assetsDir: 'assets',
7.     minify: 'terser',
8.     terserOptions: {
9.       compress: {
10.         keep_infinity: true,
11.         drop_console: true,
12.         drop_debugger: true,
13.       },
14.     },
15.     rollupOptions: {
16.       output: {
17.         manualChunks: {
18.           vue: ['vue', 'vue-router', 'pinia'],
19.           antd: ['ant-design-vue'],
20.         },
21.       },
22.     },
23.   },
24. });

复制代码

6.4 项目部署

• 环境设置：根据环境设置不同的变量
  
• 构建优化：优化构建设置，减少构建时间
  
• 部署脚本：提供部署脚本，简化部署流程
  
• 监控告警：集成监控告警系统，及时发现问题
  

6.4.1 环境设置实现

1. // .env.development
2. VITE_PORT=3100
3. VITE_USE_MOCK=true
4. VITE_USE_PWA=false
5. VITE_PUBLIC_PATH=/
6. VITE_PROXY=[["/basic-api","http://localhost:3000"],["/upload","http://localhost:3300/upload"]]
7. VITE_GLOB_APP_TITLE=Vben Admin Dev
8. VITE_GLOB_APP_SHORT_NAME=Vben Admin Dev
9. VITE_USE_CDN=false
10. VITE_DROP_CONSOLE=false
11. VITE_BUILD_COMPRESS="gzip"
12. VITE_BUILD_COMPRESS_DELETE_ORIGIN_FILE=false
13. VITE_LEGACY=false
14. VITE_USE_IMAGEMIN=false
15. VITE_GENERATE_UI=false

复制代码

7. 常见问题与解决方案

7.1 权限问题

问题：用户无法访问某些页面或功能。
解决方案：

• 检查用户角色是否正确
  
• 检查路由权限设置
  
• 检查菜单权限设置
  
• 使用权限调试工具排盘问题
  

7.2 性能问题

问题：页面加载速度慢或操作响应慢。
解决方案：

• 使用Chrome DevTools分析性能瓶颈
  
• 优化组件渲染，减少不必要的渲染
  
• 使用虚拟滚动优化长列表
  
• 优化API哀求，减少不必要的哀求
  

7.3 兼容性问题

问题：在某些浏览器中页面表现异常。
解决方案：

• 检查浏览器兼容性设置
  
• 使用polyfill解决兼容性问题
  
• 针对特定浏览器添加兼容性样式
  
• 使用babel-preset-env设置合适的浏览器目的
  

7.4 构建问题

问题：构建失败或构建产物异常。
解决方案：

• 检查依赖版本兼容性
  
• 检查构建设置是否正确
  
• 清理构建缓存，重新构建
  
• 使用更稳固的Node.js版本
  

8. 资源与社区

8.1 官方资源

• Vben Admin官网
  
• GitHub仓库
  
• 在线演示
  

8.2 社区资源

• Vben Admin社区
  
• 问题反馈
  
• 贡献指南
  

8.3 学习资源

• Vue 3文档
  
• Vite文档
  
• TypeScript文档
  
• Ant Design Vue文档
  

总结

Vben Admin是一个功能完满、易于使用的企业级管理系统框架，它基于最新的前端技术栈，提供了一套完备的解决方案，资助开发者快速搭建当代化的管理系统。通过使用Vben Admin，开发者可以专注于业务逻辑的开发，而不必耗费大量时间在基础架构的搭建上。
无论是小型项目照旧大型企业应用，Vben Admin都能提供精良的支持，是开发企业级管理系统的抱负选择。

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。