项目配置详细说明 · JeecgBoot Vue3前端文档

# 项目配置项说明用于修改项目的配色、布局、缓存、多语言、组件默认配置 [TOC] ## 环境变量配置项目的环境变量配置位于项目根目录下的 [.env]、[.env.development])、[.env.production] ```bash .env # 在所有的环境中被载入 .env.local # 在所有的环境中被载入，但会被 git 忽略 .env.[mode] # 只在指定的模式中被载入 .env.[mode].local # 只在指定的模式中被载入，但会被 git 忽略 ``` >[info] > - 只有以 `VITE_ ` 开头的变量会被嵌入到客户端侧的包中，你可以项目代码中这样访问它们： > ```js > console.log(import.meta.env.VITE_PROT); > ``` > - 以 `VITE_GLOB_*` 开头的的变量，在打包的时候，会被加入[\_app.config.js](#生产环境动态配置)配置文件当中. ### 配置项说明 | 模式 | 配置文件 | | --- | --- | | 基础配置（开发、生产、测试）共用 | .env | | 开发环境 | .env.development | | 生产环境 | .env.production | | 测试环境 | .env.test | ### .env 所有环境适用 ```bash # 端口号 VITE_PORT=3100 # 网站标题 VITE_GLOB_APP_TITLE=JeecgBoot企业级低代码平台 # 简称，用于配置文件名字不要出现空格、数字开头等特殊字符 VITE_GLOB_APP_SHORT_NAME=JeecgBootAdmin # 文件预览地址 VITE_GLOB_ONLINE_VIEW_URL=http://fileview.jeecg.com/onlinePreview # 是否开启单点登录 VITE_GLOB_APP_OPEN_SSO = false # 单点登录服务端地址 VITE_GLOBE_APP_CAS_BASE_URL=http://cas.test.com:8443/cas # 开启微前端模式 VITE_GLOB_APP_OPEN_QIANKUN=true ``` ### .env.development 开发环境适用 ```bash #后台接口父地址(必填) VITE_GLOB_API_URL=/jeecgboot #后台接口全路径地址(必填) VITE_GLOB_DOMAIN_URL=http://localhost:8080/jeecg-boot # 本地开发代理，可以解决跨域及多地址代理 # 如果接口地址匹配到，则会转发到http://localhost:3000，防止本地出现跨域问题 # 可以有多个，注意多个不能换行，否则代理将会失效 VITE_PROXY=[["/jeecgboot","http://localhost:8080/jeecg-boot"],["api1","http://localhost:3001"],["/upload","http://localhost:3001/upload"]] # 是否开启mock数据，关闭时需要自行对接后台接口 VITE_USE_MOCK=true # 资源公共路径,需要以 /开头和结尾 VITE_PUBLIC_PATH=/ # 是否删除Console.log VITE_DROP_CONSOLE=false # 是否开启单点登录 VITE_GLOB_APP_OPEN_SSO = false # 接口父路径前缀，有些系统所有接口地址都有前缀，可以在这里统一加，方便切换 VITE_GLOB_API_URL_PREFIX= ``` ~~作废参数~~ ~~~ # 文件上传地址可以由nginx做转发或者直接写实际地址[作废了] # VITE_GLOB_UPLOAD_URL更名为VITE_GLOB_DOMAIN_URL VITE_GLOB_UPLOAD_URL=/upload ~~~ >[warning] >这里配置的 `VITE_PROXY` 以及 `VITE_GLOB_API_URL`, /api 需要是唯一的，不要和接口有的名字冲突 >如果你的接口是 `http://localhost:3000/api` 之类的，请考虑将 `VITE_GLOB_API_URL=/xxxx` 换成别的名字 ### .env.production 生产环境适用 ```bash # 是否开启mock VITE_USE_MOCK=true # 接口地址可以由nginx做转发或者直接写实际地址 VITE_GLOB_API_URL=/jeecgboot #后台接口全路径地址(必填) VITE_GLOB_DOMAIN_URL=http://localhost:8080/jeecg-boot # 接口地址前缀，有些系统所有接口地址都有前缀，可以在这里统一加，方便切换 VITE_GLOB_API_URL_PREFIX= # 是否删除Console.log VITE_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 # 是否开启单点登录 VITE_GLOB_APP_OPEN_SSO = false ``` ### mock项目前缀如果修改了.env.development的属性`VITE_GLOB_API_URL`，则需要同步修改mock项目前缀 `mock/_util.ts` ~~~ //接口父路径 export const baseUrl = '/jeecgboot/mock'; ~~~ ## 生产环境动态配置 ### 说明当执行`yarn build`构建项目之后，会自动生成 `_app.config.js` 文件并插入 `index.html`。 **注意: 开发环境不会生成** ```js // _app.config.js // 变量名命名规则 __PRODUCTION__xxx_CONF__ xxx：为.env配置的VITE_GLOB_APP_SHORT_NAME window.__PRODUCTION__JEECGBOOTADMIN__CONF__= { VITE_GLOB_APP_TITLE: 'JeecgBoot企业级低代码平台', VITE_GLOB_APP_SHORT_NAME: 'JeecgBootAdmin', VITE_GLOB_API_URL: '/jeecgboot', VITE_GLOB_DOMAIN_URL: 'http://localhost:8080/jeecg-boot', VITE_GLOB_API_URL_PREFIX: '', VITE_GLOB_ONLINE_VIEW_URL: 'http://fileview.jeecg.com/onlinePreview', }; ``` ### 作用 `_app.config.js` 用于项目在打包后，需要动态修改配置的需求，如接口地址。不用重新进行打包，可在打包后修改 `/dist/_app.config.js` 内的变量，刷新即可更新代码内的局部变量。 ### 如何获取全局变量想要获取 `_app.config.js` 内的变量，可以使用 [src/hooks/setting/index.ts]提供的函数来进行获取 ### 如何新增(新增一个可动态修改的配置项) 1. 首先在 `.env` 或者对应的开发环境配置文件内，新增需要可动态配置的变量，需要以 `VITE_GLOB_`开头 2. `VITE_GLOB_` 开头的变量会自动加入环境变量，通过在 `src/types/config.d.ts` 内修改 `GlobEnvConfig` 和 `GlobConfig` 两个环境变量的值来定义新添加的类型 3. [useGlobSetting] 函数中添加刚新增的返回值即可 ```js 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] ### 说明 ```js // ! 改动后需要清空浏览器缓存 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]来进行缓存操作 ```ts 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]内配置 ```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` 即可 ```js /** * less global variable */ export const primaryColor = '#0960bd'; ``` ## 样式配置 ### css 前缀设置用于修改项目内组件 class 的统一前缀 - 在 [src/settings/designSetting.ts] 内配置 ```ts export const prefixCls = 'jeecg'; ``` - 在 [src/design/var/index.less] 配置 css 前缀 ```less @namespace: jeecg; ``` ### 前缀使用 **在 css 内** ```vue <style lang="less" scoped> /* namespace已经全局注入，不需要额外在引入 */ @prefix-cls: ~'@{namespace}-app-logo'; .@{prefix-cls} { width: 100%; } </style> ``` **在 vue/ts 内** ```ts import { useDesign } from '/@/hooks/web/useDesign'; const { prefixCls } = useDesign('app-logo'); // prefixCls => jeecg-app-logo ``` ## 颜色配置用于预设一些颜色数组在 [src/settings/designSetting.ts] 内配置 ```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] 内配置 ```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, }, }; ```