diff --git a/使用说明.md b/使用说明.md new file mode 100644 index 0000000..3811659 --- /dev/null +++ b/使用说明.md @@ -0,0 +1,595 @@ +# 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 + + + +``` + +## 🔧 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 + + + + +``` + +### 创建业务 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 项目示例或联系开发团队。