Files
admin_core/_doc/使用说明.md
张成 463d7921c1 1
2025-11-26 17:50:14 +08:00

782 lines
18 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Admin Framework 使用说明
一个基于 Vue2 的通用后台管理系统框架,包含完整的系统功能、登录、路由管理、布局等核心功能。
## 📦 框架特性
### ✨ 核心功能
-**简化的 API** - 只需调用 `createApp()` 即可完成所有初始化
-**模块化设计** - 组件、路由、状态管理等功能按模块组织
-**完整的系统管理页面** - 用户、角色、菜单、日志等管理
-**登录和权限管理** - 完整的登录流程和权限控制
-**动态路由管理** - 基于权限菜单的动态路由生成
-**Vuex 状态管理** - 用户、应用状态管理
-**全局组件库** - Tables、Editor、Upload、TreeGrid、FieldRenderer、FloatPanel 等
-**工具库** - 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`) - 删除确认、树形转换、响应式设置、文件下载
- **通用工具** (`tools`) - 日期格式化、UUID 生成、Cookie 操作、深拷贝等
- **文件下载** - 支持 CSV 等格式的文件下载,自动处理换行符
## 🚀 快速开始
### 方式一:使用 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
```
## 🎯 极简使用方式
### 只需 3 步即可完成集成!
#### 1. 引入框架
```javascript
import AdminFramework from './admin-framework.js'
```
#### 2. 创建应用
```javascript
const app = AdminFramework.createApp({
title: '我的管理系统',
apiUrl: 'http://localhost:9098/admin_api/',
componentMap: {
'business/product': ProductComponent,
'business/order': OrderComponent
}
})
```
#### 3. 挂载应用
```javascript
app.$mount('#app')
```
**就这么简单!** 框架会自动完成所有初始化工作。
## 📖 完整使用指南
### 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 AdminFramework from './libs/admin-framework.js'
// 导入业务组件(根据权限菜单接口的 component 字段)
import GamesComponent from './views/ball/games.vue'
import PayOrdersComponent from './views/order/pay_orders.vue'
// 🎉 只需一行代码!框架自动完成所有初始化
const app = AdminFramework.createApp({
title: '我的管理系统',
apiUrl: 'http://localhost:9098/admin_api/',
componentMap: {
'ball/games': GamesComponent,
'order/pay_orders': PayOrdersComponent
// 添加更多业务组件...
},
onReady() {
console.log('应用已启动!')
// 应用启动完成后的回调
}
})
// 挂载应用
app.$mount('#app')
```
### 5. 创建 App.vue
```vue
<template>
<div id="app">
<router-view/>
</div>
</template>
<script>
export default {
name: 'App'
}
</script>
```
## 🔧 API 使用指南
### 框架实例方法
#### createApp(config) - 推荐使用
创建应用实例(新版本 API
```javascript
const app = AdminFramework.createApp({
title: '我的管理系统', // 应用标题(必需)
apiUrl: 'http://localhost:9098/admin_api/', // API 基础地址(必需)
uploadUrl: 'http://localhost:9098/admin_api/upload', // 上传地址(可选,默认为 apiUrl + 'upload'
componentMap: { // 业务组件映射(可选)
'business/product': ProductComponent,
'business/order': OrderComponent
},
onReady() { // 应用启动完成回调(可选)
console.log('应用已启动!')
}
})
```
### 工具库使用
#### 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.$uiTool.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/sys_menu` - 菜单管理
-`system/sys_control` - 控制器管理
-`system/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.$uiTool.downloadFile(response, 'file.csv')
}
}
}
```
## 📁 文件下载功能
### 使用 downloadFile 方法
框架提供了便捷的文件下载功能,支持 CSV 等格式:
```javascript
// 在 Vue 组件中使用
export default {
methods: {
// 导出数据
exportData() {
// 调用 API 获取数据
this.$http.fileExport('/api/export', params).then(res => {
// 使用 downloadFile 下载
this.$uiTool.downloadFile(res, '数据导出.csv')
this.$Message.success('导出成功!')
}).catch(error => {
this.$Message.error('导出失败:' + error.message)
})
}
}
}
```
### 支持的数据格式
- **CSV 格式**:自动处理换行符,保持表格格式
- **Blob 对象**:支持二进制文件下载
- **文本数据**:支持纯文本文件下载
### 自动处理特性
-**换行符保持**CSV 文件的换行符会被正确保持
-**文件名处理**:自动清理文件名中的特殊字符
-**浏览器兼容**:支持所有现代浏览器
-**内存管理**:自动清理临时 URL 对象
## 🎨 全局组件使用
### FloatPanel - 浮动面板组件
`FloatPanel` 是一个浮动在父窗体上的面板组件,类似于抽屉效果,常用于详情展示、表单编辑等场景。
**基本使用:**
```vue
<template>
<div>
<Button @click="showPanel">打开浮动面板</Button>
<FloatPanel
ref="floatPanel"
title="详情面板"
position="right"
:show-back="true"
back-text="返回"
@back="handleBack"
>
<div>这里是面板内容</div>
</FloatPanel>
</div>
</template>
<script>
export default {
methods: {
showPanel() {
// 通过 ref 调用 show 方法显示面板
this.$refs.floatPanel.show()
},
hidePanel() {
// 通过 ref 调用 hide 方法隐藏面板
this.$refs.floatPanel.hide()
},
handleBack() {
console.log('返回按钮被点击')
this.hidePanel()
}
}
}
</script>
```
**属性说明:**
| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `title` | String | `''` | 面板标题 |
| `width` | String/Number | `'100%'` | 面板宽度(字符串或数字),默认占满父容器 |
| `height` | String/Number | `'100%'` | 面板高度(字符串或数字),默认占满父容器 |
| `position` | String | `'right'` | 面板位置:`left``right``top``bottom``center` |
| `showBack` | Boolean | `true` | 是否显示返回按钮 |
| `showClose` | Boolean | `false` | 是否显示关闭按钮 |
| `backText` | String | `'返回'` | 返回按钮文字 |
| `closeOnClickBackdrop` | Boolean | `false` | 点击遮罩是否关闭 |
| `mask` | Boolean | `false` | 是否显示遮罩(默认不显示) |
| `zIndex` | Number | `1000` | 层级 |
**方法:**
| 方法 | 说明 | 参数 |
|------|------|------|
| `show(callback)` | 显示面板 | `callback`: 可选的回调函数 |
| `hide()` | 隐藏面板 | - |
**事件:**
| 事件 | 说明 | 参数 |
|------|------|------|
| `back` | 点击返回按钮时触发 | - |
**插槽:**
| 插槽 | 说明 |
|------|------|
| `default` | 面板主体内容 |
| `header-right` | 头部右侧内容(可用于添加自定义按钮) |
**位置说明:**
- `left`: 从左侧滑入
- `right`: 从右侧滑入(默认)
- `top`: 从顶部滑入
- `bottom`: 从底部滑入
- `center`: 居中显示,带缩放动画
**完整示例:**
```vue
<template>
<div>
<Button @click="openDetailPanel">查看详情</Button>
<FloatPanel
ref="detailPanel"
title="用户详情"
position="right"
:show-back="true"
:show-close="true"
back-text="返回"
@back="handleBack"
>
<template #header-right>
<Button type="primary" @click="handleSave">保存</Button>
</template>
<div class="detail-content">
<Form :model="formData" :label-width="100">
<FormItem label="用户名">
<Input v-model="formData.username" />
</FormItem>
<FormItem label="邮箱">
<Input v-model="formData.email" />
</FormItem>
</Form>
</div>
</FloatPanel>
</div>
</template>
<script>
export default {
data() {
return {
formData: {
username: '',
email: ''
}
}
},
methods: {
openDetailPanel() {
this.$refs.detailPanel.show()
},
handleBack() {
this.$refs.detailPanel.hide()
},
handleSave() {
// 保存逻辑
console.log('保存数据', this.formData)
this.$Message.success('保存成功')
this.$refs.detailPanel.hide()
}
}
}
</script>
```
**特性说明:**
- ✅ 基于父元素定位,不会遮挡菜单
- ✅ 宽度和高度默认 100%,占满父容器
- ✅ 无遮罩背景,完全浮在父页面上
- ✅ 路由切换或组件销毁时自动关闭
- ✅ 支持多种位置和动画效果
- ✅ 支持自定义头部右侧内容
## 📝 业务开发示例
### 创建业务页面
```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 项目示例或联系开发团队。