325 lines
7.5 KiB
Markdown
325 lines
7.5 KiB
Markdown
# AdminFramework 快速开始
|
||
|
||
## 🚀 3 分钟上手
|
||
|
||
### 第一步：引入框架
|
||
|
||
```javascript
|
||
import AdminFramework from './admin-framework.js'
|
||
```
|
||
|
||
### 第二步：创建应用
|
||
|
||
```javascript
|
||
const app = AdminFramework.createApp({
|
||
title: '我的管理系统',
|
||
apiUrl: 'http://localhost:9098/admin_api/',
|
||
componentMap: {
|
||
'business/product': ProductComponent,
|
||
'business/order': OrderComponent
|
||
}
|
||
})
|
||
```
|
||
|
||
### 第三步：挂载应用1
|
||
|
||
```javascript
|
||
app.$mount('#app')
|
||
```
|
||
|
||
## ✨ 就这么简单！
|
||
|
||
**完整代码只需 12 行：**
|
||
|
||
## 📁 文件下载功能
|
||
|
||
框架内置了便捷的文件下载功能：
|
||
|
||
```javascript
|
||
// 在组件中使用
|
||
export default {
|
||
methods: {
|
||
exportData() {
|
||
// 调用 API 获取数据
|
||
this.$http.fileExport('/api/export', params).then(res => {
|
||
// 下载文件（自动处理换行符）
|
||
this.$uiTool.downloadFile(res, '数据导出.csv')
|
||
})
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**特性：**
|
||
- ✅ 自动处理 CSV 换行符
|
||
- ✅ 支持多种文件格式
|
||
- ✅ 浏览器兼容性好
|
||
|
||
```javascript
|
||
// main.js
|
||
import AdminFramework from './admin-framework.js'
|
||
import ProductComponent from './views/business/product.vue'
|
||
import OrderComponent from './views/business/order.vue'
|
||
|
||
const app = AdminFramework.createApp({
|
||
title: '我的管理系统',
|
||
apiUrl: 'http://localhost:9098/admin_api/',
|
||
componentMap: {
|
||
'business/product': ProductComponent,
|
||
'business/order': OrderComponent
|
||
}
|
||
})
|
||
|
||
app.$mount('#app')
|
||
```
|
||
|
||
## 📋 组件映射表配置
|
||
|
||
`componentMap` 用于定义业务页面的动态路由。
|
||
|
||
**重要提示：** 只需传递不带 `.vue` 后缀的路径，框架会自动处理带后缀和不带后缀的两种情况！
|
||
|
||
```javascript
|
||
// 直接在 createApp 中配置
|
||
const app = AdminFramework.createApp({
|
||
title: '我的管理系统',
|
||
apiUrl: 'http://localhost:9098/admin_api/',
|
||
componentMap: {
|
||
// ✅ 正确：只传递不带 .vue 的路径
|
||
'business/product': ProductComponent,
|
||
'business/order': OrderComponent,
|
||
'system/user': UserComponent,
|
||
|
||
// ❌ 错误：不要同时传递带和不带 .vue 的路径（多余）
|
||
// 'business/product.vue': ProductComponent, // 框架会自动添加
|
||
}
|
||
})
|
||
```
|
||
|
||
**说明：** 框架内部会自动为每个组件创建两个映射：
|
||
- `'business/product'` → ProductComponent
|
||
- `'business/product.vue'` → ProductComponent（自动添加）
|
||
|
||
所以后台菜单配置 `business/product` 或 `business/product.vue` 都可以正常工作！
|
||
|
||
## ⚙️ 配置说明
|
||
|
||
### 必填参数
|
||
|
||
| 参数 | 说明 | 示例 |
|
||
|------|------|------|
|
||
| `title` | 应用标题 | `'我的管理系统'` |
|
||
| `apiUrl` | API 基础地址 | `'http://localhost:9098/admin_api/'` |
|
||
| `componentMap` | 组件映射表 | 见上方示例 |
|
||
|
||
### 可选参数
|
||
|
||
| 参数 | 说明 | 默认值 |
|
||
|------|------|--------|
|
||
| `uploadUrl` | 上传文件地址 | `apiUrl + 'upload'` |
|
||
| `onReady` | 应用启动回调 | - |
|
||
|
||
## 🎯 完整示例
|
||
|
||
```javascript
|
||
import AdminFramework from './admin-framework.js'
|
||
import componentMap from './router/component-map.js'
|
||
|
||
const app = AdminFramework.createApp({
|
||
// 必填配置
|
||
title: '我的管理系统',
|
||
apiUrl: 'http://localhost:9098/admin_api/',
|
||
componentMap: componentMap,
|
||
|
||
// 可选配置
|
||
uploadUrl: 'http://cdn.example.com/upload', // 可选，默认为 apiUrl + 'upload'
|
||
|
||
// 应用启动完成回调
|
||
onReady() {
|
||
console.log('应用已启动!')
|
||
console.log('当前登录用户:', this.$store.state.user)
|
||
}
|
||
})
|
||
|
||
app.$mount('#app')
|
||
```
|
||
|
||
## 📦 框架内置功能
|
||
|
||
使用 `createApp()` 后，框架会自动提供：
|
||
|
||
### 1. 内置页面
|
||
- ✅ 登录页面 (`/login`)
|
||
- ✅ 主页 (`/home`)
|
||
- ✅ 404 页面 (`/404`)
|
||
- ✅ 401 页面 (`/401`)
|
||
- ✅ 500 页面 (`/500`)
|
||
|
||
### 2. 系统管理页面
|
||
- ✅ 用户管理 (`/system/user`)
|
||
- ✅ 角色管理 (`/system/role`)
|
||
- ✅ 日志管理 (`/system/log`)
|
||
- ✅ 参数设置 (`/system/param`)
|
||
- ✅ 菜单管理 (`/system/menu`)
|
||
- ✅ 权限控制 (`/system/control`)
|
||
- ✅ 标题设置 (`/system/title`)
|
||
|
||
### 3. 全局组件
|
||
- ✅ `<Tables>` - 增强型表格
|
||
- ✅ `<UploadSingle>` - 单图上传
|
||
- ✅ `<UploadMultiple>` - 多图上传
|
||
- ✅ `<TreeGrid>` - 树形表格
|
||
- ✅ `<AsyncModal>` - 异步弹窗
|
||
- ✅ `<Editor>` - 富文本编辑器
|
||
- ✅ `<CommonIcon>` - 图标选择器
|
||
|
||
### 4. 工具方法
|
||
|
||
在任何组件中可以使用：
|
||
|
||
```javascript
|
||
// HTTP 请求
|
||
this.$http.get('/api/users')
|
||
this.$http.post('/api/users', data)
|
||
|
||
// UI 工具
|
||
this.$uiTool.showLoading()
|
||
this.$uiTool.hideLoading()
|
||
this.$uiTool.showSuccess('操作成功')
|
||
|
||
// 通用工具
|
||
this.$tools.formatDate(new Date())
|
||
this.$tools.deepClone(obj)
|
||
|
||
// 文件下载
|
||
this.$uiTool.downloadFile(response, 'filename.xlsx')
|
||
|
||
// 配置信息
|
||
this.$config.title
|
||
this.$config.apiUrl
|
||
this.$config.uploadUrl
|
||
|
||
// 状态管理
|
||
this.$store.state.user.token
|
||
this.$store.state.app.sysTitle
|
||
```
|
||
|
||
## 🎨 自定义页面
|
||
|
||
### 1. 创建页面组件
|
||
|
||
```vue
|
||
<!-- views/business/product-list.vue -->
|
||
<template>
|
||
<div>
|
||
<Tables :columns="columns" :data="list" />
|
||
</div>
|
||
</template>
|
||
|
||
<script>
|
||
export default {
|
||
data() {
|
||
return {
|
||
list: [],
|
||
columns: [
|
||
{ title: '产品名称', key: 'name' },
|
||
{ title: '价格', key: 'price' }
|
||
]
|
||
}
|
||
},
|
||
created() {
|
||
this.loadData()
|
||
},
|
||
methods: {
|
||
async loadData() {
|
||
const res = await this.$http.get('/products')
|
||
this.list = res.data
|
||
}
|
||
}
|
||
}
|
||
</script>
|
||
```
|
||
|
||
### 2. 添加到组件映射表
|
||
|
||
```javascript
|
||
// router/component-map.js
|
||
import ProductList from '../views/business/product-list.vue'
|
||
|
||
export default {
|
||
'business/product': ProductList // 路径对应后台菜单的 component 字段
|
||
}
|
||
```
|
||
|
||
### 3. 在后台配置菜单
|
||
|
||
在"菜单管理"中添加菜单项：
|
||
- 菜单名称: `产品列表`
|
||
- 路由路径: `/business/product`
|
||
- 组件路径: `business/product`（对应 componentMap 的 key）
|
||
|
||
## 📝 常见问题
|
||
|
||
### Q1: uploadUrl 如何配置？
|
||
|
||
**A:** 默认情况下无需配置，框架会自动设置为 `apiUrl + 'upload'`。
|
||
|
||
如果需要自定义（如使用 CDN），可以手动传入：
|
||
|
||
```javascript
|
||
AdminFramework.createApp({
|
||
apiUrl: 'http://localhost:9098/admin_api/',
|
||
uploadUrl: 'http://cdn.example.com/upload' // 自定义上传地址
|
||
})
|
||
```
|
||
|
||
### Q2: 如何访问框架实例？
|
||
|
||
**A:** 框架实例会自动暴露到全局：
|
||
|
||
```javascript
|
||
// 浏览器控制台
|
||
window.framework // 框架实例
|
||
window.app // Vue 实例
|
||
window.rootVue // Vue 实例（别名）
|
||
```
|
||
|
||
### Q3: 如何添加自定义 Vuex 模块？
|
||
|
||
**A:** 使用旧的 `install()` 方式：
|
||
|
||
```javascript
|
||
import AdminFramework from './admin-framework.js'
|
||
|
||
AdminFramework.install(Vue, {
|
||
config: { ... },
|
||
ViewUI,
|
||
VueRouter,
|
||
Vuex,
|
||
customModules: {
|
||
myModule: myModuleConfig
|
||
}
|
||
})
|
||
```
|
||
|
||
### Q4: 框架文件太大怎么办？
|
||
|
||
**A:** 新版框架（3.6 MB）内置了所有依赖，使用更方便。如果需要减小文件大小，可以使用旧的 `install()` 方式，手动引入依赖。
|
||
|
||
## 🔗 相关文档
|
||
|
||
- [简化使用说明.md](./简化使用说明.md) - 详细的使用说明和对比
|
||
- [README.md](./README.md) - 项目介绍和特性
|
||
- [demo/src/main.js](./demo/src/main.js) - 完整示例代码
|
||
|
||
## 💡 最佳实践
|
||
|
||
1. **推荐使用 `createApp()`** - 代码更简洁，减少 77% 的代码量
|
||
2. **组件映射表单独管理** - 方便维护和扩展
|
||
3. **利用内置组件** - 如 `<Tables>`、`<UploadSingle>` 等，提高开发效率
|
||
4. **使用 `onReady` 回调** - 在应用启动后执行初始化逻辑
|
||
|
||
## 🎉 开始开发吧！
|
||
|
||
现在你已经了解了 AdminFramework 的快速使用方法，开始构建你的管理系统吧！
|