网上的后台管理系统模板很多,按需删改也需要一些时间。
xjy_admin是我自己搭建并持续完善的通用后台管理模板,希望把常用的基础功能整理好,方便自己复用,也给有同样需求的朋友一个参考。
🔥 前言
做这个模板的初衷,是把日常开发中经常用到的基础功能整理在一起,方便后续复用。经过一段时间的打磨,xjy_admin 已具备页面刷新、全屏、深色主题和移动端适配等功能,也加入了一些常用组件与页面示例。
这篇文章主要记录项目的基础配置、功能集成和运行方式,方便自己回顾,也希望能给正在学习 Vue 3 或准备搭建后台项目的朋友提供一些参考。项目会随着使用继续完善,遇到问题或有好的建议,欢迎交流。
😀 项目介绍
一个基于 Vue 3.5 + Element Plus + Vite 搭建的轻量级后台管理模板,使用 TypeScript 编写。项目提供登录和用户信息两个演示接口,通过 MockJS 模拟数据,并实现了管理员与普通用户的简单权限划分,方便直接运行和体验。
目前包含工作台、侧栏导航、页面标签、主题设置,以及 Canvas、分页器和富文本编辑器等示例。桌面端使用侧栏布局,小屏幕下切换为抽屉导航,页面内容也会按屏幕宽度调整。可以先熟悉现有示例,再按自己的业务需要补充页面和接口。
✨ 效果展示
在线预览
Gitee 仓库地址
首页
首页集中展示概览统计、访问趋势和项目相关信息,作为登录后的工作台入口。图表和统计数据用于界面演示,实际使用时可以替换为自己的业务数据。
🏅 技术栈
项目以 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/ |
| Pinia | Vue 状态管理库 | pinia.vuejs.org/zh/ |
| ECharts | JavaScript 数据可视化图表库 | 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,便于后续按自己的习惯调整。
代码统一规范
项目分别使用下面三个工具处理脚本、样式和格式问题。日常开发时配合编辑器使用,能减少手动整理格式的工作,也让不同页面的写法保持一致。
- 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 扩展,可以获得样式提示:
插件提示效果:
Canvas 基本使用
通过一个简单案例演示 Canvas 的图片选择、背景配色、文案绘制和图片导出,体验从页面操作到生成图片的完整过程。
这个案例可以选择内置图片、切换背景颜色并输入文案,画布会随选择更新。绘制时先载入背景,再叠加颜色、文字和图片,最后通过导出按钮保存结果。输入变化使用防抖处理,适合用来熟悉 Canvas 的基础绘制流程,也可以在此基础上继续尝试海报或图片合成。
以下代码来自 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 图标目录在 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 的基础配置和几个功能示例,从项目启动、样式配置到组件使用,都是开发过程中会反复遇到的内容。把它们整理在一起,也是给自己的学习和实践留一份记录。
后续我会继续结合使用体验完善这个模板,也欢迎大家提出问题和建议。如果其中某一处配置或封装能帮你少花一点时间,这篇分享就有意义。感谢阅读,欢迎交流。