目录说明
.├── build # 打包脚本相关│ ├── config # 配置文件│ ├── generate # 生成器│ ├── script # 脚本│ └── vite # vite配置├── mock # mock文件夹├── public # 公共静态资源目录├── src # 主目录│ ├── api # 接口文件│ ├── assets # 资源文件│ │ ├── icons # icon sprite 图标文件夹│ │ ├── images # 项目存放图片的文件夹│ │ └── svg # 项目存放svg图片的文件夹│ ├── components # 公共组件│ ├── design # 样式文件│ ├── directives # 指令│ ├── enums # 枚举/常量│ ├── hooks # hook│ │ ├── component # 组件相关hook│ │ ├── core # 基础hook│ │ ├── event # 事件相关hook│ │ ├── setting # 配置相关hook│ │ └── web # web相关hook│ ├── layouts # 布局文件│ │ ├── default # 默认布局│ │ ├── iframe # iframe布局│ │ └── page # 页面布局│ ├── locales # 多语言│ ├── logics # 逻辑│ ├── main.ts # 主入口│ ├── router # 路由配置│ ├── settings # 项目配置│ │ ├── componentSetting.ts # 组件配置│ │ ├── designSetting.ts # 样式配置│ │ ├── encryptionSetting.ts # 加密配置│ │ ├── localeSetting.ts # 多语言配置│ │ ├── projectSetting.ts # 项目配置│ │ └── siteSetting.ts # 站点配置│ ├── store # 数据仓库│ ├── utils # 工具类│ └── views # 页面├── types # 类型文件└── vite.config.ts # vite配置文件
项目配置项
用于修改项目的配色、布局、缓存、多语言、组件默认配置
#环境变量配置
项目的环境变量配置位于项目根目录下的 .env、.env.development、.env.production
具体可以参考 Vite 文档
.env # 在所有的环境中被载入.env.local # 在所有的环境中被载入,但会被 git 忽略.env.[mode] # 只在指定的模式中被载入.env.[mode].local # 只在指定的模式中被载入,但会被 git 忽略
温馨提醒
只有以VITE_
开头的变量会被嵌入到客户端侧的包中,你可以在项目代码中这样访问它们: console.log(import.meta.env.VITE_PROT);
以 VITE_GLOB_*
开头的的变量,在打包的时候,会被加入_app.config.js配置文件当中. #配置项说明
#.env
所有环境适用
# 端口号VITE_PORT=3100# 网站标题VITE_GLOB_APP_TITLE=vben admin# 简称,用于配置文件名字 不要出现空格、数字开头等特殊字符VITE_GLOB_APP_SHORT_NAME=vben_admin
#.env.development
开发环境适用
# 是否开启mock数据,关闭时需要自行对接后台接口VITE_USE_MOCK=true# 资源公共路径,需要以 /开头和结尾VITE_PUBLIC_PATH=/# 是否删除Console.logVITE_DROP_CONSOLE=false# 本地开发代理,可以解决跨域及多地址代理# 如果接口地址匹配到,则会转发到http://localhost:3000,防止本地出现跨域问题# 可以有多个,注意多个不能换行,否则代理将会失效VITE_PROXY=[["/api","http://localhost:3000"],["api1","http://localhost:3001"],["/upload","http://localhost:3001/upload"]]::: tipv3.0.0开始,作者重构了vite.config.ts,新版本不再支持VITE_PROXY环境变量。:::# 接口地址# 如果没有跨域问题,直接在这里配置即可VITE_GLOB_API_URL=/api# 文件上传接口 可选VITE_GLOB_UPLOAD_URL=/upload# 接口地址前缀,有些系统所有接口地址都有前缀,可以在这里统一加,方便切换VITE_GLOB_API_URL_PREFIX=
注意
这里配置的 VITE_PROXY
以及 VITE_GLOB_API_URL
, /api 需要是唯一的,不要和接口有的名字冲突
如果你的接口是 http://localhost:3000/api
之类的,请考虑将 VITE_GLOB_API_URL=/xxxx
换成别的名字
#.env.production
生产环境适用
# 是否开启mockVITE_USE_MOCK=true# 接口地址 可以由nginx做转发或者直接写实际地址VITE_GLOB_API_URL=/api# 文件上传地址 可以由nginx做转发或者直接写实际地址VITE_GLOB_UPLOAD_URL=/upload# 接口地址前缀,有些系统所有接口地址都有前缀,可以在这里统一加,方便切换VITE_GLOB_API_URL_PREFIX=# 是否删除Console.logVITE_DROP_CONSOLE=true# 资源公共路径,需要以 / 开头和结尾VITE_PUBLIC_PATH=/# 打包是否输出gz|br文件# 可选: gzip | brotli | none# 也可以有多个, 例如 ‘gzip’|'brotli',这样会同时生成 .gz和.br文件VITE_BUILD_COMPRESS = 'gzip'# 打包是否压缩图片VITE_USE_IMAGEMIN = false# 打包是否开启pwa功能VITE_USE_PWA = false# 是否兼容旧版浏览器。开启后打包时间会慢一倍左右。会多打出旧浏览器兼容包,且会根据浏览器兼容性自动使用相应的版本VITE_LEGACY = false
#生产环境动态配置
#说明
当执行yarn build
构建项目之后,会自动生成 _app.config.js
文件并插入 index.html
。
注意: 开发环境不会生成
// _app.config.js// 变量名命名规则 __PRODUCTION__xxx_CONF__ xxx:为.env配置的VITE_GLOB_APP_SHORT_NAMEwindow.__PRODUCTION__VUE_VBEN_ADMIN__CONF__ = { VITE_GLOB_APP_TITLE: 'vben admin', VITE_GLOB_APP_SHORT_NAME: 'vue_vben_admin', VITE_GLOB_API_URL: '/app', VITE_GLOB_API_URL_PREFIX: '/', VITE_GLOB_UPLOAD_URL: '/upload',};
#作用
_app.config.js
用于项目在打包后,需要动态修改配置的需求,如接口地址。不用重新进行打包,可在打包后修改 /dist/_app.config.js
内的变量,刷新即可更新代码内的局部变量。
#如何获取全局变量
想要获取 _app.config.js
内的变量,可以使用 src/hooks/setting/index.ts 提供的函数来进行获取
#如何新增(新增一个可动态修改的配置项)
首先在 .env
或者对应的开发环境配置文件内,新增需要可动态配置的变量,需要以 VITE_GLOB_
开头
VITE_GLOB_
开头的变量会自动加入环境变量,通过在 types/config.d.ts
内修改 GlobEnvConfig
和 GlobConfig
两个环境变量的值来定义新添加的类型
useGlobSetting 函数中添加刚新增的返回值即可
const { VITE_GLOB_APP_TITLE, VITE_GLOB_API_URL, VITE_GLOB_APP_SHORT_NAME, VITE_GLOB_API_URL_PREFIX, VITE_GLOB_UPLOAD_URL,} = ENV;export const useGlobSetting = (): SettingWrap => { // Take global configuration const glob: Readonly<GlobConfig> = { title: VITE_GLOB_APP_TITLE, apiUrl: VITE_GLOB_API_URL, shortName: VITE_GLOB_APP_SHORT_NAME, urlPrefix: VITE_GLOB_API_URL_PREFIX, uploadUrl: VITE_GLOB_UPLOAD_URL }; return glob as Readonly<GlobConfig>;};
#项目配置
WARNING
项目配置文件用于配置项目内展示的内容、布局、文本等效果,存于localStorage
中。如果更改了项目配置,需要手动清空 localStorage
缓存,刷新重新登录后方可生效。
#配置文件路径
src/settings/projectSetting.ts
#说明
// ! 改动后需要清空浏览器缓存const setting: ProjectConfig = { // 是否显示SettingButton showSettingButton: true, // 是否显示主题切换按钮 showDarkModeToggle: true, // 设置按钮位置 可选项 // SettingButtonPositionEnum.AUTO: 自动选择 // SettingButtonPositionEnum.HEADER: 位于头部 // SettingButtonPositionEnum.FIXED: 固定在右侧 settingButtonPosition: SettingButtonPositionEnum.AUTO, // 权限模式,默认前端角色权限模式 // ROUTE_MAPPING: 前端模式(菜单由路由生成,默认) // ROLE:前端模式(菜单路由分开) permissionMode: PermissionModeEnum.ROUTE_MAPPING, // 权限缓存存放位置。默认存放于localStorage permissionCacheType: CacheTypeEnum.LOCAL, // 会话超时处理方案 // SessionTimeoutProcessingEnum.ROUTE_JUMP: 路由跳转到登录页 // SessionTimeoutProcessingEnum.PAGE_COVERAGE: 生成登录弹窗,覆盖当前页面 sessionTimeoutProcessing: SessionTimeoutProcessingEnum.ROUTE_JUMP, // 项目主题色 themeColor: primaryColor, // 网站灰色模式,用于可能悼念的日期开启 grayMode: false, // 色弱模式 colorWeak: false, // 是否取消菜单,顶部,多标签页显示, 用于可能内嵌在别的系统内 fullContent: false, // 主题内容宽度 contentMode: ContentEnum.FULL, // 是否显示logo showLogo: true, // 是否显示底部信息 copyright showFooter: true, // 头部配置 headerSetting: { // 背景色 bgColor: '#ffffff', // 固定头部 fixed: true, // 是否显示顶部 show: true, // 主题 theme: MenuThemeEnum.LIGHT, // 开启锁屏功能 useLockPage: true, // 显示全屏按钮 showFullScreen: true, // 显示文档按钮 showDoc: true, // 显示消息中心按钮 showNotice: true, // 显示菜单搜索按钮 showSearch: true, }, // 菜单配置 menuSetting: { // 背景色 bgColor: '#273352', // 是否固定住菜单 fixed: true, // 菜单折叠 collapsed: false, // 折叠菜单时候是否显示菜单名 collapsedShowTitle: false, // 是否可拖拽 canDrag: true, // 是否显示 show: true, // 菜单宽度 menuWidth: 180, // 菜单模式 mode: MenuModeEnum.INLINE, // 菜单类型 type: MenuTypeEnum.SIDEBAR, // 菜单主题 theme: MenuThemeEnum.DARK, // 分割菜单 split: false, // 顶部菜单布局 topMenuAlign: 'start', // 折叠触发器的位置 trigger: TriggerEnum.HEADER, // 手风琴模式,只展示一个菜单 accordion: true, // 在路由切换的时候关闭左侧混合菜单展开菜单 closeMixSidebarOnChange: false, // 左侧混合菜单模块切换触发方式 mixSideTrigger: MixSidebarTriggerEnum.CLICK, // 是否固定左侧混合菜单 mixSideFixed: false, }, // 多标签 multiTabsSetting: { // 刷新后是否保留已经打开的标签页 cache: false, // 开启 show: true, // 开启快速操作 showQuick: true, // 是否可以拖拽 canDrag: true, // 是否显示刷新按钮 showRedo: true, // 是否显示折叠按钮 showFold: true, }, // 动画配置 transitionSetting: { // 是否开启切换动画 enable: true, // 动画名 basicTransition: RouterTransitionEnum.FADE_SIDE, // 是否打开页面切换loading openPageLoading: true, // 是否打开页面切换顶部进度条 openNProgress: false, }, // 是否开启KeepAlive缓存 开发时候最好关闭,不然每次都需要清除缓存 openKeepAlive: true, // 自动锁屏时间,为0不锁屏。 单位分钟 默认1个小时 lockTime: 0, // 显示面包屑 showBreadCrumb: true, // 显示面包屑图标 showBreadCrumbIcon: false, // 是否使用全局错误捕获 useErrorHandle: false, // 是否开启回到顶部 useOpenBackTop: true, // 是否可以嵌入iframe页面 canEmbedIFramePage: true, // 切换界面的时候是否删除未关闭的message及notify closeMessageOnSwitch: true, // 切换界面的时候是否取消已经发送但是未响应的http请求。 // 如果开启,想对单独接口覆盖。可以在单独接口设置 removeAllHttpPending: true,};
#缓存配置
用于配置缓存内容加密信息,对缓存到浏览器的信息进行 AES 加密
在 /@/settings/encryptionSetting.ts 内可以配置 localStorage
及 sessionStorage
缓存信息
前提: 使用项目自带的缓存工具类 /@/utils/cache 来进行缓存操作
import { isDevMode } from '/@/utils/env';// 缓存默认过期时间export const DEFAULT_CACHE_TIME = 60 * 60 * 24 * 7;// 开启缓存加密后,加密密钥。采用aes加密export const cacheCipher = { key: '_11111000001111@', iv: '@11111000001111_',};// 是否加密缓存,默认生产环境加密export const enableStorageEncryption = !isDevMode();
#多语言配置
用于配置多语言信息
在 src/settings/localeSetting.ts 内配置
export const LOCALE: { [key: string]: LocaleType } = { ZH_CN: 'zh_CN', EN_US: 'en',};export const localeSetting: LocaleSetting = { // 是否显示语言选择器 showPicker: true, // 当前语言 locale: LOCALE.ZH_CN, // 默认语言 fallback: LOCALE.ZH_CN, // 允许的语言 availableLocales: [LOCALE.ZH_CN, LOCALE.EN_US],};// 语言列表export const localeList: DropMenu[] = [ { text: '简体中文', event: LOCALE.ZH_CN, }, { text: 'English', event: LOCALE.EN_US, },];
#主题色配置
默认全局主题色配置位于 build/config/glob/themeConfig.ts 内
只需要修改 primaryColor 为您需要的配色,然后重新执行 yarn serve
即可
/** * less global variable */export const primaryColor = '#0960bd';
#样式配置
#css 前缀设置
用于修改项目内组件 class 的统一前缀
在 src/settings/designSetting.ts 内配置export const prefixCls = 'vben';
在 src/design/var/index.less 配置 css 前缀 @namespace: vben;
#前缀使用
在 css 内
<style lang="less" scoped> /* namespace已经全局注入,不需要额外再引入 */ @prefix-cls: ~'@{namespace}-app-logo'; .@{prefix-cls} { width: 100%; }</style>
在 vue/ts 内
import { useDesign } from '/@/hooks/web/useDesign';const { prefixCls } = useDesign('app-logo');// prefixCls => vben-app-logo
#颜色配置
用于预设一些颜色数组
在 src/settings/designSetting.ts 内配置
// app主题色预设export const APP_PRESET_COLOR_LIST: string[] = [ '#0960bd', '#0084f4', '#009688', '#536dfe', '#ff5c93', '#ee4f12', '#0096c7', '#9c27b0', '#ff9800',];// 顶部背景色预设export const HEADER_PRESET_BG_COLOR_LIST: string[] = [ '#ffffff', '#009688', '#5172DC', '#1E9FFF', '#018ffb', '#409eff', '#4e73df', '#e74c3c', '#24292e', '#394664', '#001529', '#383f45',];// 左侧菜单背景色预设export const SIDE_BAR_BG_COLOR_LIST: string[] = [ '#001529', '#273352', '#ffffff', '#191b24', '#191a23', '#304156', '#001628', '#28333E', '#344058', '#383f45',];
#组件默认参数配置
在 src/settings/componentSetting.ts 内配置
// 用于配置某些组件的常规配置,而无需修改组件import type { SorterResult } from '../components/Table';export default { // 表格配置 table: { // 表格接口请求通用配置,可在组件prop覆盖 // 支持 xxx.xxx.xxx格式 fetchSetting: { // 传给后台的当前页字段 pageField: 'page', // 传给后台的每页显示多少条的字段 sizeField: 'pageSize', // 接口返回表格数据的字段 listField: 'items', // 接口返回表格总数的字段 totalField: 'total', }, // 可选的分页选项 pageSizeOptions: ['10', '50', '80', '100'], //默认每页显示多少条 defaultPageSize: 10, // 默认排序方法 defaultSortFn: (sortInfo: SorterResult) => { const { field, order } = sortInfo; return { // 排序字段 field, // 排序方式 asc/desc order, }; }, // 自定义过滤方法 defaultFilterFn: (data: Partial<Recordable<string[]>>) => { return data; }, }, // 滚动组件配置 scrollbar: { // 是否使用原生滚动样式 // 开启后,菜单,弹窗,抽屉会使用原生滚动条组件 native: false, },};