596 lines
13 KiB
Markdown
596 lines
13 KiB
Markdown
# Admin Framework 使用说明
|
||
|
||
一个基于 Vue2 的通用后台管理系统框架，包含完整的系统功能、登录、路由管理、布局等核心功能。
|
||
|
||
## 📦 框架特性
|
||
|
||
### ✨ 核心功能
|
||
- ✅ **完整的系统管理页面** - 用户、角色、菜单、日志等管理
|
||
- ✅ **登录和权限管理** - 完整的登录流程和权限控制
|
||
- ✅ **动态路由管理** - 基于权限菜单的动态路由生成
|
||
- ✅ **Vuex 状态管理** - 用户、应用状态管理
|
||
- ✅ **全局组件库** - Tables、Editor、Upload、TreeGrid 等
|
||
- ✅ **工具库** - HTTP、日期、Token、Cookie 等工具
|
||
- ✅ **内置样式** - base.less、animate.css、iconfont 等
|
||
- ✅ **响应式布局** - 支持移动端适配
|
||
|
||
### 🎯 内置页面组件
|
||
- **主页组件** (`HomePage`) - 欢迎页面，显示系统标题
|
||
- **系统管理页面** (`SysUser`, `SysRole`, `SysLog`, `SysParamSetup`)
|
||
- **高级管理页面** (`SysMenu`, `SysControl`, `SysTitle`)
|
||
- **登录页面** (`LoginPage`)
|
||
- **错误页面** (`Page401`, `Page404`, `Page500`)
|
||
|
||
### 🛠️ 内置工具
|
||
- **HTTP 工具** (`http`) - 封装了 axios，支持拦截器
|
||
- **UI 工具** (`uiTool`) - 删除确认、树形转换、响应式设置
|
||
- **功能工具** (`funTool`) - 文件下载等
|
||
- **通用工具** (`tools`) - 日期格式化、UUID 生成、Cookie 操作
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 方式一：使用 Demo 项目（推荐）
|
||
|
||
我们提供了一个完整的 demo 项目，可以直接运行查看效果：
|
||
|
||
```bash
|
||
# 1. 进入 demo 项目
|
||
cd demo
|
||
|
||
# 2. 安装依赖
|
||
npm install
|
||
|
||
# 3. 启动开发服务器
|
||
npm run dev
|
||
```
|
||
|
||
浏览器会自动打开 `http://localhost:8080`，查看：
|
||
- `/login` - 登录页面
|
||
- `/home` - 主页
|
||
- `/system/user` - 用户管理
|
||
- `/ball/games` - 业务示例页面
|
||
|
||
### 方式二：构建框架
|
||
|
||
```bash
|
||
# 1. 安装依赖
|
||
npm install
|
||
|
||
# 2. 构建框架
|
||
npm run build
|
||
|
||
# 3. 产物在 dist/admin-framework.js
|
||
```
|
||
|
||
## 📖 完整使用指南
|
||
|
||
### 1. 项目结构准备
|
||
|
||
```
|
||
your-project/
|
||
├── src/
|
||
│ ├── config/
|
||
│ │ └── index.js # 配置文件
|
||
│ ├── libs/
|
||
│ │ └── admin-framework.js # 框架文件
|
||
│ ├── views/
|
||
│ │ └── business/ # 业务页面
|
||
│ ├── api/
|
||
│ │ └── business/ # 业务 API
|
||
│ ├── App.vue
|
||
│ └── main.js
|
||
├── package.json
|
||
└── webpack.config.js
|
||
```
|
||
|
||
### 2. 安装依赖
|
||
|
||
```bash
|
||
npm install vue vue-router vuex view-design axios dayjs js-cookie vuex-persistedstate
|
||
```
|
||
|
||
### 3. 创建配置文件
|
||
|
||
在 `src/config/index.js` 中：
|
||
|
||
```javascript
|
||
module.exports = {
|
||
title: '你的系统名称',
|
||
homeName: '首页',
|
||
apiUrl: 'http://localhost:9090/admin_api/',
|
||
uploadUrl: 'http://localhost:9090/admin_api/upload',
|
||
cookieExpires: 7,
|
||
uploadMaxLimitSize: 10,
|
||
oss: {
|
||
region: 'oss-cn-shanghai',
|
||
accessKeyId: 'your-key',
|
||
accessKeySecret: 'your-secret',
|
||
bucket: 'your-bucket',
|
||
url: 'http://your-bucket.oss-cn-shanghai.aliyuncs.com',
|
||
basePath: 'your-path/'
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4. 创建 main.js
|
||
|
||
```javascript
|
||
import Vue from 'vue'
|
||
import VueRouter from 'vue-router'
|
||
import Vuex from 'vuex'
|
||
import ViewUI from 'view-design'
|
||
import createPersistedState from 'vuex-persistedstate'
|
||
import AdminFramework from './libs/admin-framework.js'
|
||
import App from './App.vue'
|
||
import config from './config'
|
||
|
||
// 可选：导入业务组件（根据权限菜单接口的 component 字段）
|
||
import GamesComponent from './views/ball/games.vue'
|
||
import PayOrdersComponent from './views/order/pay_orders.vue'
|
||
|
||
// 🎉 只需这一行！框架自动完成所有初始化
|
||
Vue.use(AdminFramework, {
|
||
config,
|
||
ViewUI,
|
||
VueRouter,
|
||
Vuex,
|
||
createPersistedState,
|
||
// ✅ 可选：配置业务组件映射（用于权限菜单）
|
||
componentMap: {
|
||
'ball/games': GamesComponent,
|
||
'order/pay_orders': PayOrdersComponent
|
||
// 添加更多业务组件...
|
||
}
|
||
})
|
||
|
||
// 创建 Vue 实例
|
||
new Vue({
|
||
el: '#app',
|
||
router: AdminFramework.router, // 使用框架自动创建的 router
|
||
store: AdminFramework.store, // 使用框架自动创建的 store
|
||
render: h => h(App),
|
||
mounted() {
|
||
// 设置响应式字体
|
||
AdminFramework.uiTool.setRem()
|
||
|
||
// 只在已登录时获取系统标题
|
||
const token = this.$store.state.user.token
|
||
if (token) {
|
||
this.$store.dispatch('app/getSysTitle', {
|
||
defaultTitle: 'Demo 管理系统',
|
||
defaultLogo: ''
|
||
})
|
||
} else {
|
||
document.title = 'Demo 管理系统'
|
||
}
|
||
}
|
||
})
|
||
|
||
// 响应式适配
|
||
window.addEventListener('load', AdminFramework.uiTool.setRem)
|
||
window.addEventListener('resize', AdminFramework.uiTool.setRem)
|
||
```
|
||
|
||
### 5. 创建 App.vue
|
||
|
||
```vue
|
||
<template>
|
||
<div id="app">
|
||
<router-view/>
|
||
</div>
|
||
</template>
|
||
|
||
<script>
|
||
export default {
|
||
name: 'App'
|
||
}
|
||
</script>
|
||
```
|
||
|
||
## 🔧 API 使用指南
|
||
|
||
### 框架实例方法
|
||
|
||
#### install(Vue, options)
|
||
安装 Vue 插件
|
||
|
||
```javascript
|
||
Vue.use(AdminFramework, {
|
||
config: yourConfig, // 项目配置对象（必需）
|
||
ViewUI: ViewUI, // ViewUI 实例（必需）
|
||
VueRouter: VueRouter, // VueRouter 类（必需）
|
||
Vuex: Vuex, // Vuex 类（必需）
|
||
createPersistedState: createPersistedState, // vuex-persistedstate 插件（必需）
|
||
componentMap: componentMap // 业务组件映射（可选）
|
||
})
|
||
```
|
||
|
||
#### 其他方法
|
||
```javascript
|
||
// 初始化 HTTP 配置
|
||
AdminFramework.initHttp(config, store)
|
||
|
||
// 创建路由实例
|
||
AdminFramework.createRouter(Router, components, customRoutes, ViewUI, homeName)
|
||
|
||
// 创建 Store 实例
|
||
AdminFramework.createStore(Vuex, customModules, createPersistedState)
|
||
|
||
// 添加组件映射
|
||
AdminFramework.addComponentMap(customMap)
|
||
```
|
||
|
||
### 工具库使用
|
||
|
||
#### HTTP 工具
|
||
```javascript
|
||
// 在组件中使用
|
||
export default {
|
||
async mounted() {
|
||
// GET 请求
|
||
const res = await this.$http.get('/api/users', { page: 1 })
|
||
|
||
// POST 请求
|
||
const result = await this.$http.post('/api/users', { name: 'test' })
|
||
|
||
// 文件导出
|
||
await this.$http.fileExport('/api/export', { type: 'excel' })
|
||
}
|
||
}
|
||
|
||
// 在非 Vue 组件中使用
|
||
import AdminFramework from './libs/admin-framework.js'
|
||
const res = await AdminFramework.http.get('/api/users')
|
||
```
|
||
|
||
#### UI 工具
|
||
```javascript
|
||
// 在组件中使用
|
||
export default {
|
||
methods: {
|
||
handleDelete() {
|
||
// 删除确认
|
||
this.$uiTool.delConfirm(() => {
|
||
// 执行删除逻辑
|
||
})
|
||
|
||
// 设置响应式字体
|
||
this.$uiTool.setRem()
|
||
|
||
// 树形转换
|
||
const treeData = this.$uiTool.transformTree(flatData)
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 功能工具
|
||
```javascript
|
||
// 在组件中使用
|
||
export default {
|
||
methods: {
|
||
downloadFile() {
|
||
// 文件下载
|
||
this.$funTool.downloadFile(response, 'filename.csv')
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 通用工具
|
||
```javascript
|
||
// 在组件中使用
|
||
export default {
|
||
methods: {
|
||
formatDate() {
|
||
// 日期格式化
|
||
return this.$tools.formatDate(new Date(), 'YYYY-MM-DD HH:mm:ss')
|
||
},
|
||
|
||
generateId() {
|
||
// UUID 生成
|
||
return this.$tools.generateUUID()
|
||
},
|
||
|
||
setCookie() {
|
||
// Cookie 操作
|
||
this.$tools.setCookie('name', 'value')
|
||
const value = this.$tools.getCookie('name')
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### Store 模块使用
|
||
|
||
#### user 模块
|
||
```javascript
|
||
// 登录
|
||
await this.$store.dispatch('user/handleLogin', {
|
||
userFrom: { username, password },
|
||
Main: AdminFramework.Main,
|
||
ParentView: AdminFramework.ParentView,
|
||
Page404: AdminFramework.Page404
|
||
})
|
||
|
||
// 登出
|
||
this.$store.dispatch('user/handleLogOut')
|
||
|
||
// 设置权限菜单
|
||
this.$store.dispatch('user/setAuthorityMenus', {
|
||
Main: AdminFramework.Main,
|
||
ParentView: AdminFramework.ParentView,
|
||
Page404: AdminFramework.Page404
|
||
})
|
||
|
||
// 获取用户信息
|
||
const userName = this.$store.getters['user/userName']
|
||
const token = this.$store.state.user.token
|
||
```
|
||
|
||
#### app 模块
|
||
```javascript
|
||
// 设置面包屑
|
||
this.$store.commit('app/setBreadCrumb', route)
|
||
|
||
// 获取系统标题
|
||
this.$store.dispatch('app/getSysTitle', {
|
||
defaultTitle: '系统名称',
|
||
defaultLogo: '/logo.png'
|
||
})
|
||
|
||
// 获取系统配置
|
||
const sysFormModel = this.$store.getters['app/sysFormModel']
|
||
```
|
||
|
||
## 🗂️ 组件映射配置
|
||
|
||
### 业务组件映射
|
||
|
||
当后端权限菜单接口返回组件路径时，需要配置映射表：
|
||
|
||
```javascript
|
||
// 1. 导入业务组件
|
||
import GamesComponent from './views/ball/games.vue'
|
||
import PayOrdersComponent from './views/order/pay_orders.vue'
|
||
|
||
// 2. 配置映射
|
||
const componentMap = {
|
||
'ball/games': GamesComponent,
|
||
'ball/games.vue': GamesComponent, // 支持带 .vue 后缀
|
||
'order/pay_orders': PayOrdersComponent,
|
||
'order/pay_orders.vue': PayOrdersComponent
|
||
}
|
||
|
||
// 3. 在 Vue.use 时传入
|
||
Vue.use(AdminFramework, {
|
||
config,
|
||
ViewUI,
|
||
VueRouter,
|
||
Vuex,
|
||
createPersistedState,
|
||
componentMap // 传入组件映射表
|
||
})
|
||
```
|
||
|
||
### 框架已自动映射的系统组件
|
||
|
||
以下组件**无需配置**，框架已自动映射：
|
||
- ✅ `home/index` - 主页
|
||
- ✅ `system/sys_user` - 用户管理
|
||
- ✅ `system/sys_role` - 角色管理
|
||
- ✅ `system/sys_log` - 日志管理
|
||
- ✅ `system/sys_param_setup` - 参数设置
|
||
- ✅ `system_high/sys_menu` - 菜单管理
|
||
- ✅ `system_high/sys_control` - 控制器管理
|
||
- ✅ `system_high/sys_title` - 系统标题设置
|
||
|
||
## 🌐 全局访问
|
||
|
||
### window.framework
|
||
|
||
框架实例会自动暴露到全局，可以在任何地方访问：
|
||
|
||
```javascript
|
||
// 在非 Vue 组件中使用
|
||
const http = window.framework.http
|
||
const uiTool = window.framework.uiTool
|
||
const config = window.framework.config
|
||
|
||
// HTTP 请求
|
||
const res = await window.framework.http.get('/api/users')
|
||
|
||
// UI 工具
|
||
window.framework.uiTool.delConfirm(() => {
|
||
// 删除逻辑
|
||
})
|
||
```
|
||
|
||
### Vue 原型方法
|
||
|
||
在 Vue 组件中可以直接使用：
|
||
|
||
```javascript
|
||
export default {
|
||
methods: {
|
||
async loadData() {
|
||
// 直接使用 this.$xxx
|
||
const res = await this.$http.get('/api/users')
|
||
this.$uiTool.delConfirm(() => {})
|
||
this.$tools.formatDate(new Date())
|
||
this.$funTool.downloadFile(response, 'file.csv')
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 📝 业务开发示例
|
||
|
||
### 创建业务页面
|
||
|
||
```vue
|
||
<!-- src/views/business/product.vue -->
|
||
<template>
|
||
<div>
|
||
<h1>产品管理</h1>
|
||
<Button @click="loadData">加载数据</Button>
|
||
<Tables :columns="columns" :data="list" />
|
||
</div>
|
||
</template>
|
||
|
||
<script>
|
||
export default {
|
||
data() {
|
||
return {
|
||
list: [],
|
||
columns: [
|
||
{ title: 'ID', key: 'id' },
|
||
{ title: '名称', key: 'name' },
|
||
{ title: '价格', key: 'price' }
|
||
]
|
||
}
|
||
},
|
||
async mounted() {
|
||
await this.loadData()
|
||
},
|
||
methods: {
|
||
async loadData() {
|
||
// 使用框架提供的 http 工具
|
||
const res = await this.$http.get('/product/list', { page: 1 })
|
||
this.list = res.data
|
||
},
|
||
|
||
async handleDelete(id) {
|
||
// 使用框架提供的 UI 工具
|
||
this.$uiTool.delConfirm(async () => {
|
||
await this.$http.post('/product/delete', { id })
|
||
this.$Message.success('删除成功')
|
||
await this.loadData()
|
||
})
|
||
}
|
||
}
|
||
}
|
||
</script>
|
||
```
|
||
|
||
### 创建业务 API
|
||
|
||
```javascript
|
||
// src/api/business/productServer.js
|
||
// 注意：不需要 import http，直接使用 http
|
||
|
||
class ProductServer {
|
||
async getList(params) {
|
||
return await http.get('/product/list', params)
|
||
}
|
||
|
||
async save(data) {
|
||
return await http.post('/product/save', data)
|
||
}
|
||
|
||
async delete(id) {
|
||
return await http.post('/product/delete', { id })
|
||
}
|
||
|
||
async exportCsv(params) {
|
||
return await http.fileExport('/product/export', params)
|
||
}
|
||
}
|
||
|
||
export default new ProductServer()
|
||
```
|
||
|
||
## ❓ 常见问题
|
||
|
||
### Q1: 打包后文件太大怎么办？
|
||
|
||
A: 框架已经将 Vue、VueRouter、Vuex、ViewUI、Axios 设置为外部依赖，不会打包进去。确保在项目中单独安装这些依赖。
|
||
|
||
### Q2: 如何只使用部分功能？
|
||
|
||
A: 可以按需导入：
|
||
```javascript
|
||
import { http, uiTool, tools } from './libs/admin-framework.js'
|
||
```
|
||
|
||
### Q3: 权限菜单中的业务页面显示 404 怎么办？
|
||
|
||
A: 需要配置组件映射表：
|
||
```javascript
|
||
Vue.use(AdminFramework, {
|
||
// ... 其他配置
|
||
componentMap: {
|
||
'ball/games': GamesComponent,
|
||
'order/pay_orders': PayOrdersComponent
|
||
}
|
||
})
|
||
```
|
||
|
||
### Q4: 如何自定义配置？
|
||
|
||
A: 修改 `config/index.js` 文件：
|
||
```javascript
|
||
module.exports = {
|
||
title: '你的系统名称',
|
||
apiUrl: 'http://your-api-url/',
|
||
// ... 其他配置
|
||
}
|
||
```
|
||
|
||
### Q5: 如何使用登录功能？
|
||
|
||
A: 在组件中：
|
||
```javascript
|
||
export default {
|
||
methods: {
|
||
async login() {
|
||
await this.$store.dispatch('user/handleLogin', {
|
||
userFrom: { username: 'admin', password: '123456' },
|
||
Main: AdminFramework.Main,
|
||
ParentView: AdminFramework.ParentView,
|
||
Page404: AdminFramework.Page404
|
||
})
|
||
this.$router.push({ name: 'home' })
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### Q6: 需要单独引入样式文件吗？
|
||
|
||
A: **不需要！** 框架已内置所有样式：
|
||
- ✅ `base.less` - 基础样式
|
||
- ✅ `animate.css` - 动画样式
|
||
- ✅ `ivewExpand.less` - ViewUI 扩展样式
|
||
- ✅ `iconfont.css` - 字体图标样式
|
||
|
||
只需引入框架即可：
|
||
```javascript
|
||
import AdminFramework from './libs/admin-framework.js'
|
||
Vue.use(AdminFramework, { ... })
|
||
```
|
||
|
||
## 📦 技术栈
|
||
|
||
- Vue 2.6+
|
||
- Vue Router 3.x
|
||
- Vuex 3.x
|
||
- View Design (iView) 4.x
|
||
- Axios
|
||
- Less
|
||
- Webpack 5
|
||
|
||
## 📄 许可证
|
||
|
||
MIT License
|
||
|
||
## 👨💻 作者
|
||
|
||
light
|
||
|
||
---
|
||
|
||
**祝开发愉快！** 🎉
|
||
|
||
如有问题，请查看 Demo 项目示例或联系开发团队。
|