項目配置詳細說明 · 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, }, }; ```