Vben Admin

项目配置项

用于修改项目的配色、布局、缓存、多语言、组件默认配置以适配自身项目需求

环境变量配置

项目的环境变量配置位于 项目根目录 .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配置文件当中.

配置项说明

vue-vite-admin\build\utils.ts

npm dotenv 不用各處加入新的環境變數，要集中在 .env 檔中管理它

package.json

  "devDependencies": {
    "dotenv": "^10.0.0",
  }

.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.log
VITE_DROP_CONSOLE=false
# 本地开发代理，可以解决跨域及多地址代理
# 如果接口地址匹配到，则会转发到http://localhost:3000，防止本地出现跨域问题
# 可以有多个，注意多个不能换行，否则代理将会失效
VITE_PROXY=[["/api","http://localhost:3000"],["api1","http://localhost:3001"],["/upload","http://localhost:3001/upload"]]
# 接口地址
# 如果没有跨域问题，直接在这里配置即可
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

生产环境适用

# 是否开启mock
VITE_USE_MOCK=true
# 接口地址 可以由nginx做转发或者直接写实际地址
VITE_GLOB_API_URL=/api
# 文件上传地址 可以由nginx做转发或者直接写实际地址
VITE_GLOB_UPLOAD_URL=/upload
# 接口地址前缀，有些系统所有接口地址都有前缀，可以在这里统一加，方便切换
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

测试配置

src\App.vue

<template>
  <div>{{ vitePort }}</div>
</template>

<script lang="ts">
import { defineComponent, ref } from "vue";

export default defineComponent({
  name: "App",
  setup() {
    const vitePort = ref(import.meta.env.VITE_PORT);
    return {
      vitePort,
    };
  },
});
</script>

生产环境动态配置

说明

当执行yarn build构建项目之后，会自动生成_app.config.js文件并插入index.html。

注意:开发环境不会生成

// _app.config.js
// 变量名命名规则  __PRODUCTION__xxx_CONF__   xxx：为.env配置的VITE_GLOB_APP_SHORT_NAME
window.__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提供的函数来进行获取

如何新增(新增一个可动态修改的配置项)

  1. 首先在.env或者对应的开发环境配置文件内新增需要可动态配置的变量 需要以 VITE_GLOB_开头

  2. VITE_GLOB_开头的变量会自动加入环境变量，通过在 src/types/config.d.ts内修改 GlobEnvConfig和GlobConfig两个环境变量的值来定义新添加的类型

  3. 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缓存

如果更改了项目配置，需要手动清空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 的统一前缀

export const prefixCls = 'vben';

@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

样式检查

yarn add stylelint stylelint-config-standard stylelint-config-prettier stylelint-order -D

stylelint是对我们编写的样式进行检查的插件。

stylelint-config-standard是stylelint扩展的检查标准库。

stylelint-config-prettier是用来解决冲突的（估计又和ESLint冲突了，参考之前的prettier）。

stylelint-order是检查我们样式编写顺序的。

stylelint官网
stylelint的配置规则

stylelint.config.js

module.exports = {
  // ↓这个好像是没有用的，但是VbenAdmin是这么写的
  root: true,
  // ↓插件
  plugins: ['stylelint-order'],
  // ↓扩展
  extends: ['stylelint-config-standard', 'stylelint-config-prettier'],
  // ↓自定义规则
  rules: {},
  // ↓忽略检查的文件
  ignoreFiles: ['**/*.js', '**/*.jsx', '**/*.tsx', '**/*.ts'],
};

module.exports = {
  // ...
  rules: {
    // ↓禁止使用未知的伪类选择器。
    'selector-pseudo-class-no-unknown': [
      true,
      {
        ignorePseudoClasses: ['global'],
      },
    ],
    // ↓禁止使用未知规则。
    'at-rule-no-unknown': [
      true,
      {
        ignoreAtRules: ['function', 'if', 'each', 'include', 'mixin'],
      },
    ],
    // ↓禁止空来源。
    'no-empty-source': null,
    // ↓禁止使用无效的命名网格区域。
    'named-grid-areas-no-invalid': null,
    // ↓要求或不允许使用Unicode字节顺序标记。
    'unicode-bom': 'never',
    // ↓禁止较低特异性的选择器在覆盖较高特异性的选择器之后出现。
    'no-descending-specificity': null,
    // ↓禁止在字体系列名称列表中缺少通用系列。
    'font-family-no-missing-generic-family-keyword': null,
    // ↓在声明的冒号后面需要一个空格或禁止空格。
    'declaration-colon-space-after': 'always-single-line',
    // ↓在声明的冒号之前需要一个空格或禁止使用空格。
    'declaration-colon-space-before': 'never',
    // ↓在声明块内要求或不允许尾随分号。
    'declaration-block-trailing-semicolon': 'always',
    // ↓在规则之前要求或禁止使用空行。
    'rule-empty-line-before': [
      'always',
      {
        ignore: ['after-comment', 'first-nested'],
      },
    ],
    // ↓禁止使用未知单位。
    'unit-no-unknown': [true, { ignoreUnits: ['rpx'] }],
    // Specify the alphabetical order of the attributes in the declaration block
    // ↓样式顺序
    'order/properties-order': [
      'position',
      'top',
      'right',
      'bottom',
      'left',
      'z-index',
      'display',
      'float',
       ...
    ],
  },
  // ...
};

.stylelintignore

/dist/*
/public/*
public/*

PostCSS

安装两个库postcss、autoprefixer。要现实的效果就是我们编写一般的样式，渲染都页面的dom节点有面向各种浏览器厂商的样式。

postcss就像一个管子。autoprefixer是里面的过滤器。你写的css从管子中流过，经过他们的处理就出现了不同的结果。

Vite配置PostCss
官网postcss

yarn add postcss autoprefixer -D

postcss.config.js

module.exports = {
  plugins: {
    autoprefixer: {},
  },
};

颜色配置

用于预设一些颜色数组

在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,
  },
};

vite路径参数配置

src\main.ts

import router, { setupRouter } from "/@/router";

vite.config.ts

export default ({ command, mode }: ConfigEnv): UserConfig => {
  return {
    base: VITE_PUBLIC_PATH,
    root,
    resolve: {
      alias: [

        // /@/xxxx => src/xxxx
        {
          find: /\/@\//,
          replacement: pathResolve('src') + '/',
        },
        // /#/xxxx => types/xxxx
        {
          find: /\/#\//,
          replacement: pathResolve('types') + '/',
        },
        // ['@vue/compiler-sfc', '@vue/compiler-sfc/dist/compiler-sfc.esm-browser.js'],
      ],
    },

tsconfig.json

{
  "compilerOptions": {
    ...
    "baseUrl": ".",
    "paths": {
      "/@/*": ["src/*"],
      "/#/*": ["types/*"]
    }
  },