👊 Vue3.5+Element-plus+Vite通用后台管理系统

45,441 阅读12分钟

网上的后台管理系统模板很多,按需删改也需要一些时间。xjy_admin 是我自己搭建并持续完善的通用后台管理模板,希望把常用的基础功能整理好,方便自己复用,也给有同样需求的朋友一个参考。

🔥 前言

做这个模板的初衷,是把日常开发中经常用到的基础功能整理在一起,方便后续复用。经过一段时间的打磨,xjy_admin 已具备页面刷新、全屏、深色主题和移动端适配等功能,也加入了一些常用组件与页面示例。

这篇文章主要记录项目的基础配置、功能集成和运行方式,方便自己回顾,也希望能给正在学习 Vue 3 或准备搭建后台项目的朋友提供一些参考。项目会随着使用继续完善,遇到问题或有好的建议,欢迎交流。

😀 项目介绍

一个基于 Vue 3.5 + Element Plus + Vite 搭建的轻量级后台管理模板,使用 TypeScript 编写。项目提供登录和用户信息两个演示接口,通过 MockJS 模拟数据,并实现了管理员与普通用户的简单权限划分,方便直接运行和体验。

目前包含工作台、侧栏导航、页面标签、主题设置,以及 Canvas、分页器和富文本编辑器等示例。桌面端使用侧栏布局,小屏幕下切换为抽屉导航,页面内容也会按屏幕宽度调整。可以先熟悉现有示例,再按自己的业务需要补充页面和接口。

✨ 效果展示

在线预览

xjy_admin

Gitee 仓库地址

xjy_admin

首页

首页集中展示概览统计、访问趋势和项目相关信息,作为登录后的工作台入口。图表和统计数据用于界面演示,实际使用时可以替换为自己的业务数据。

dashboard-light.png

login-desktop.png

🏅 技术栈

项目以 Vue 3 和 Element Plus 为基础,使用 Pinia 管理状态,搭配 ECharts、VueUse 等工具完成图表展示与常用交互。下面列出项目中使用的主要技术及其文档入口,方便查阅。

技术栈描述官网
Vue 3渐进式 JavaScript 框架cn.vuejs.org/
Element Plus基于 Vue 3 的组件库element-plus.org/zh-CN/
Vite前端开发与构建工具cn.vite.dev/
PiniaVue 状态管理库pinia.vuejs.org/zh/
EChartsJavaScript 数据可视化图表库echarts.apache.org/zh/index.ht…
VueUse基于组合式 API 的实用工具集vueuse.org/
animate.css跨浏览器 CSS 动画库animate.style/
WangEditor开箱即用的 Web 富文本编辑器www.wangeditor.com/

🌈 项目基本配置

项目全局配置

项目名称、Logo、全屏入口和默认布局等基础配置集中在 src/config/setting.ts。更换项目名称或调整默认显示选项时,可以先从这个文件入手。

主题与页面显示选项可以通过设置抽屉调整,包括浅色、深色主题切换,以及标签栏、侧栏 Logo 和面包屑的显示。页面颜色、间距与圆角统一放在 src/styles/theme.scss,过渡时长集中在 src/styles/motion.scss,便于后续按自己的习惯调整。

image.png

代码统一规范

项目分别使用下面三个工具处理脚本、样式和格式问题。日常开发时配合编辑器使用,能减少手动整理格式的工作,也让不同页面的写法保持一致。

  • ESLint:检查脚本语法、Vue 模板与代码规范。
  • Prettier:统一代码与文档格式。
  • Stylelint:检查 CSS、SCSS 和 Vue 样式。

以下配置与当前项目文件保持一致。其中,ESLint 使用 eslint.config.mjs 配置,Vue 和 TypeScript 的解析规则也在这里统一设置。

eslint.config.mjs

import js from "@eslint/js"
import tsPlugin from "@typescript-eslint/eslint-plugin"
import tsParser from "@typescript-eslint/parser"
import prettier from "eslint-config-prettier"
import vue from "eslint-plugin-vue"
import vueParser from "vue-eslint-parser"
import globals from "globals"
import autoImports from "./.config/eslint-auto-import.json" with { type: "json" }

export default [
  { ignores: ["dist/**", "node_modules/**", "public/**", "src/assets/**"] },
  js.configs.recommended,
  ...vue.configs["flat/essential"],
  {
    files: ["src/**/*.{ts,vue}"],
    languageOptions: {
      parser: vueParser,
      parserOptions: { parser: tsParser, ecmaVersion: "latest", sourceType: "module" },
      globals: { ...globals.browser, ...globals.node, ...autoImports.globals },
    },
    plugins: { "@typescript-eslint": tsPlugin },
    rules: {
      ...tsPlugin.configs["eslint-recommended"].overrides[0].rules,
      ...tsPlugin.configs.recommended.rules,
      "no-var": "error",
      // Preserve the existing JavaScript style during this dependency update.
      "prefer-const": "off",
      "no-constant-binary-expression": "off",
      "no-useless-assignment": "off",
      "no-useless-escape": "off",
      "@typescript-eslint/no-unused-vars": "off",
      "@typescript-eslint/no-explicit-any": "off",
      "@typescript-eslint/no-non-null-assertion": "off",
      "@typescript-eslint/no-namespace": "off",
      "@typescript-eslint/no-unused-expressions": ["error", { allowShortCircuit: true }],
      "vue/multi-word-component-names": "off",
      "vue/no-mutating-props": "off",
    },
  },
  prettier,
]

.prettierrc.json

{
  "singleQuote": false,
  "semi": false,
  "bracketSpacing": true,
  "htmlWhitespaceSensitivity": "ignore",
  "endOfLine": "auto",
  "trailingComma": "all",
  "tabWidth": 2
}

.stylelintrc.cjs

module.exports = {
  extends: [
    "stylelint-config-standard-scss",
    "stylelint-config-recommended-vue/scss",
    "stylelint-config-recess-order",
  ],
  overrides: [
    { files: ["**/*.scss"], customSyntax: "postcss-scss" },
    { files: ["**/*.vue"], customSyntax: "postcss-html" },
  ],
  ignoreFiles: ["src/assets/**", "dist/**", "node_modules/**"],
  rules: {
    "no-empty-source": null,
    "no-descending-specificity": null,
    "selector-class-pattern": null,
    "scss/dollar-variable-pattern": null,
    "keyframes-name-pattern": null,
    "value-keyword-case": ["lower", { ignoreFunctions: ["v-bind"] }],
    "selector-pseudo-class-no-unknown": [
      true,
      { ignorePseudoClasses: ["global", "v-deep", "deep", "export"] },
    ],
    "selector-type-no-unknown": [true, { ignoreTypes: ["text", "view"] }],
  },
}

🎈 按钮主题色

项目在 src/styles/element/index.scss 中配置 Element Plus 的基础主题色,包含主色、成功、警告和错误等状态颜色。需要调整按钮及相关组件的配色时,可以统一修改这里的颜色值:

@forward "element-plus/theme-chalk/src/common/var.scss" with (
  $colors: (
    "primary": ("base": #646cff),
    "success": ("base": #52c41a),
    "info": ("base": #64748b),
    "warning": ("base": #faad14),
    "danger": ("base": #f5222d),
    "error": ("base": #f5222d)
  )
);

vite.config.ts 配置(节选)

下面通过 SCSS 预处理配置注入主题文件和公共样式,便于页面使用统一的样式配置。

css: {
  preprocessorOptions: {
    scss: {
      quietDeps: true,
      // 自动导入定制化样式文件进行样式覆盖
      additionalData: `@use "@/styles/element/index.scss" as *;\n@use "@/config/public.scss" as *;\n`,
    },
  },
},

🔑 项目集成

MockJS

MockJS 用于生成模拟数据并拦截 Ajax 请求,方便前端独立开发和调试。

项目中的登录和用户信息数据定义在 src/mock/index.ts,通过模拟不同角色的返回结果演示菜单权限。这样在后端接口准备好之前,也能先把登录流程和页面交互跑通;接入实际服务时,再根据接口约定替换对应数据。

参考:mock.js 官网

安装

pnpm add mockjs@1.1.0
pnpm add -D vite-plugin-mock@3.0.2

vite.config.ts 配置(节选)

import { viteMockServe } from "vite-plugin-mock"

plugins: [
  viteMockServe({
    mockPath: "./src/mock",
    // localEnabled: true,
  }),
]

UnoCSS

UnoCSS 是即时原子化 CSS 引擎,可以在模板中组合工具类,快速完成常见布局与样式。

项目把常用的居中、两端对齐和宽高铺满等写法整理成了快捷类,例如 flex-center 和 wh-full。页面中可以直接复用这些类,减少重复样式;涉及组件细节或响应式布局时,再配合 SCSS 处理。

参考:UnoCSS 文档

安装

pnpm add -D unocss@66.11.0

vite.config.ts 配置(节选)

import UnoCSS from "unocss/vite"

plugins: [
  UnoCSS(),
]

src/main.ts 中引入样式

import "virtual:uno.css"

uno.config.ts 中的配置

下面的配置包含常用快捷类、预设和转换器。主题色关联了 Element Plus 的 CSS 变量,便于在工具类中沿用项目配色。

// uno.config.ts
import {
  defineConfig,
  presetAttributify,
  presetIcons,
  presetTypography,
  presetWind3,
  presetWebFonts,
  transformerDirectives,
  transformerVariantGroup,
} from "unocss"

export default defineConfig({
  shortcuts: {
    "flex-center": "flex justify-center items-center",
    "flex-x-center": "flex justify-center",
    "flex-y-center": "flex items-center",
    "wh-full": "w-full h-full",
    "flex-x-between": "flex items-center justify-between",
    "flex-x-end": "flex items-center justify-end",
    "absolute-lt": "absolute left-0 top-0",
    "absolute-rt": "absolute right-0 top-0 ",
    "fixed-lt": "fixed left-0 top-0",
    "b1-red": "b-1 border-solid b-red",
  },
  theme: {
    colors: {
      primary: "var(--el-color-primary)",
      primary_dark: "var(--el-color-primary-light-5)",
    },
  },
  presets: [
    presetWind3({ dark: "class" }),
    presetAttributify(),
    presetIcons(),
    presetTypography(),
    presetWebFonts({
      fonts: {
        // ...
      },
    }),
  ],
  transformers: [transformerDirectives(), transformerVariantGroup()],
})

在 VS Code 中安装 UnoCSS 扩展,可以获得样式提示:

UnoCSS 编辑器扩展

插件提示效果:

UnoCSS 样式提示

Canvas 基本使用

通过一个简单案例演示 Canvas 的图片选择、背景配色、文案绘制和图片导出,体验从页面操作到生成图片的完整过程。

这个案例可以选择内置图片、切换背景颜色并输入文案,画布会随选择更新。绘制时先载入背景,再叠加颜色、文字和图片,最后通过导出按钮保存结果。输入变化使用防抖处理,适合用来熟悉 Canvas 的基础绘制流程,也可以在此基础上继续尝试海报或图片合成。

canvas-desktop.png

以下代码来自 src/views/Canvas/index.vue 的脚本部分:

<script setup lang="ts">
import debounce from "lodash/debounce"
import { message } from "@/Hooks/element"
import cat1 from "../../assets/image/cat1.png"
import cat2 from "../../assets/image/cat2.png"
import dog1 from "../../assets/image/dog1.png"
import dog2 from "../../assets/image/dog2.png"
import canvaas_bg from "../../assets/image/canvas.webp"
const picList = [dog1, cat2, dog2, cat1] as string[]
const colorList = [
  "#fbd04f",
  "#a8a1dc",
  "#83b6da",
  "#92c7ba",
  "#f6a356 ",
  "#5e5f61",
  "#f98787 ",
] as string[]
// canvas实例
const canvas = ref()
// 画布
const ctx = ref()
// 初始化背景图片
const initCanvas_bg = async () => {
  await new Promise((resolve, reject) => {
    // 初始化画布
    ctx.value = canvas.value.getContext("2d")!
    const width = 700
    const height = 800
    canvas.value.width = width
    canvas.value.height = height
    const img = new Image()

    img.onload = () => {
      ctx.value.drawImage(img, 0, 0, canvas.value.width, canvas.value.height) // 绘制第一张图片
      resolve("ok")
    }
    img.src = canvaas_bg
    img.onerror = () => {
      reject("失败")
    }
  })
}
onMounted(async () => {
  try {
    // 初始化背景canvas
    await initCanvas_bg()
  } catch (err: any) {
    message("error", "初始化背景失败")
  }
})

// 选择图片
const pic_val = ref("")
const imgIndex = ref<number>()
const selectImg = async (pic: string, i: number) => {
  pic_val.value = pic
  imgIndex.value = i
}
// 选择背景色
const color_val = ref("")
const colorIndex = ref<number>()
const selectBg = async (color: string, i: number) => {
  color_val.value = color
  colorIndex.value = i
}
// 输入值改变
const input_val = ref("")

watch(
  [() => pic_val.value, () => color_val.value, () => input_val.value],
  debounce(async (newVal: any) => {
    try {
      // 初始化背景canvas
      await initCanvas_bg()
      let [newPic_val, newColor_val, newInut_val] = newVal
      // 先看背景颜色有没有
      if (newColor_val) {
        // 设置填充色
        ctx.value.fillStyle = newColor_val
        // 绘制正方形
        ctx.value.fillRect(99, 75, 342, 477)
        // 再看文本
        if (newInut_val) {
          ctx.value.fillStyle = "black"
          ctx.value.font = `35px 隶书`
          ctx.value.fillText("名:" + newInut_val, 190, 180)
        }
        // 先铺背景在画图片
        if (newPic_val) {
          const img = new Image()
          img.src = newPic_val
          img.onload = () => {
            ctx.value.drawImage(img, 100, 202, 350, 350) // 绘制选择的图片
          }
        }
      } else {
        // 再看文本
        if (newInut_val) {
          ctx.value.fillStyle = "black"
          ctx.value.font = `35px 隶书`
          ctx.value.fillText("名:" + newInut_val, 190, 180)
        }
        // 先铺背景在画图片
        if (newPic_val) {
          const img = new Image()
          img.src = newPic_val
          img.onload = () => {
            ctx.value.drawImage(img, 100, 202, 350, 350) // 绘制选择的图片
          }
        }
      }
    } catch (err: any) {
      message("error", "初始化背景失败")
    }
  }, 100),
)
// 导出图片
const outPic = () => {
  let base64 = canvas.value.toDataURL()
  let link = document.createElement("a")
  link.textContent = "download image"
  link.href = base64
  link.download = "mypainting.jpeg"
  link.click()
}
</script>

🏆 功能封装

SVG 使用

项目封装了 SvgIcon 组件,通过 icon 指定图标名称,使用 width、height 和 color 调整尺寸与颜色。页面里只需传入对应参数,就能复用相同的图标写法:

<SvgIcon icon="" width="15px" height="15px" color="#fff" />

构建时使用 vite-plugin-svg-icons 读取指定目录,相关配置如下:

createSvgIconsPlugin({
  iconDirs: [path.resolve(process.cwd(), "src/assets/svgs")],
  symbolId: "icon-[dir]-[name]",
})

SVG 图标目录示意

SVG 图标目录在 vite.config.ts 中配置为 src/assets/svgs/,可按需创建目录并添加图标。上面的用法展示了组件参数,实际使用时需要把 icon 的空值替换为对应图标名称;使用子目录时,名称还需包含配置中的目录前缀。

WangEditor 编辑器集成

官网

富文本编辑器封装在 src/components/WangEditor/index.vue 中,页面通过 v-model 读写内容,通过 height 设置编辑区域高度。下面是当前示例页面的用法,后续接入表单时可以沿用这个方式:

<template>
  <WangEditor v-model="editVal" height="calc(100vh - 180px)" />
</template>

<script setup lang="ts">

const editVal = ref("Hello! WangEditor")
watchEffect(() => {
  console.log(editVal.value)
})
</script>

<style scoped></style>

组件内部把工具栏和编辑区域放在一起,编辑器实例使用 shallowRef 保存,并在组件卸载时销毁。样式沿用项目的主题变量,让编辑区域与浅色、深色页面保持协调。图片上传部分预留了 customUpload 方法,接入自己的上传接口并调用 insertFn 后,即可将返回的图片地址插入内容。

<template>
  <div class="wang_edit" :class="{ dark: useSetting.dark }">
    <Toolbar
      id="toolbar-container"
      :editor="editorRef"
      :defaultConfig="toolbarConfig"
      mode="default"
    />
    <Editor
      id="editor-container"
      v-model="valueHtml"
      :defaultConfig="editorConfig"
      mode="default"
      @onCreated="handleCreated"
    />
  </div>
</template>

<script setup lang="ts">
import { useSettingStore } from "@/stores/modules/setting"
import "@wangeditor/editor/dist/css/style.css" // 引入 css
import { onBeforeUnmount, ref, shallowRef, onMounted } from "vue"
import { Editor, Toolbar } from "@wangeditor/editor-for-vue"
const useSetting = useSettingStore()
const props = withDefaults(
  defineProps<{
    height: string
  }>(),
  {
    height: "560px",
  },
)

const valueHtml = defineModel()
// 编辑器实例,必须用 shallowRef
const editorRef = shallowRef()
const toolbarConfig = {}
const editorConfig = {
  placeholder: "请输入内容...",
  MENU_CONF: {
    uploadImage: {
      // 自定义图片上传
      async customUpload(file: any, insertFn: any) {
        console.log(file, insertFn)
        // 调用后端接口,上传图片
        // 拿到上传路劲插入编辑器
        // insertFn(url)
      },
    },
  },
}

// 组件销毁时,也及时销毁编辑器
onBeforeUnmount(() => {
  const editor = editorRef.value
  if (editor == null) return
  editor.destroy()
})

const handleCreated = (editor: any) => {
  editorRef.value = editor // 记录 editor 实例,重要!
}
</script>

<style scoped lang="scss">
.wang_edit {
  overflow: hidden;
  background: var(--app-surface);
  border: 1px solid var(--app-border);
  border-radius: var(--app-radius);
  box-shadow: var(--app-shadow);

  --w-e-textarea-bg-color: var(--app-surface);
  --w-e-textarea-color: var(--app-text);
  --w-e-toolbar-bg-color: var(--app-surface);
  --w-e-toolbar-color: var(--app-text-secondary);
  --w-e-toolbar-border-color: var(--app-border);
  --w-e-toolbar-active-color: var(--el-color-primary);
  --w-e-toolbar-active-bg-color: var(--app-primary-soft);
  --w-e-toolbar-disabled-color: var(--app-text-muted);
  --w-e-modal-button-bg-color: var(--app-surface-soft);
  --w-e-modal-button-border-color: var(--app-border);
  --w-e-textarea-border-color: var(--app-border);
  --w-e-textarea-slight-bg-color: var(--app-surface-soft);
  --w-e-textarea-slight-color: var(--app-text-secondary);
  --w-e-textarea-selected-border-color: var(--el-color-primary);

  #toolbar-container {
    border-bottom: 1px solid var(--app-border);
  }

  #editor-container {
    height: v-bind("props.height") !important;
    min-height: 320px;
    overflow: hidden;
  }
}
</style>

👻 项目运行

项目启动

使用 Node.js 22.13+(22.x)或 24+、pnpm 12.14.0,在项目根目录执行以下命令。依赖版本由锁文件固定,按锁文件安装可以让本地环境与项目配置保持一致:

# 安装 pnpm
npm install -g pnpm@12.14.0

# 按锁文件安装依赖
pnpm install --frozen-lockfile

# 启动开发服务
pnpm dev

启动成功后访问 http://localhost:9000。管理员演示账号为 admin,普通用户账号为 user,密码均为 123456,可以切换账号查看不同角色的菜单。

项目语法检查

修改页面或配置后,可以按需要执行脚本、样式和类型检查。自动修复与格式化命令会写入文件,适合在提交前配合查看改动;类型检查则用于发现 TypeScript 和 Vue 模板中的类型问题。

# 脚本与模板检查
pnpm lint

# 自动修复脚本与模板规范
pnpm fix

# 样式检查与修复
pnpm lint:style
pnpm lint:style:fix

# 格式化源码与文档
pnpm format

# 类型检查
pnpm type-check

项目打包

页面开发完成后,执行下面的命令进行类型检查并生成生产构建:

pnpm build

构建产物位于 dist/,可以通过 pnpm preview 在本地预览。项目使用 Hash 路由,部署时上传 dist/ 中的完整文件,并保留原有资源目录结构即可。

✍️ 写在最后

以上就是 xjy_admin 的基础配置和几个功能示例,从项目启动、样式配置到组件使用,都是开发过程中会反复遇到的内容。把它们整理在一起,也是给自己的学习和实践留一份记录。

后续我会继续结合使用体验完善这个模板,也欢迎大家提出问题和建议。如果其中某一处配置或封装能帮你少花一点时间,这篇分享就有意义。感谢阅读,欢迎交流。