From 6de4936012ed4880e8cb4a15bc216c8f9eda2b38 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=BC=A0=E6=88=90?= Date: Tue, 24 Mar 2026 11:10:14 +0800 Subject: [PATCH] 1 --- _doc/使用说明.md | 781 --------------------- _doc/完整使用文档.md | 1582 ------------------------------------------ _doc/快速开始.md | 325 --------- 3 files changed, 2688 deletions(-) delete mode 100644 _doc/使用说明.md delete mode 100644 _doc/完整使用文档.md delete mode 100644 _doc/快速开始.md diff --git a/_doc/使用说明.md b/_doc/使用说明.md deleted file mode 100644 index c9f3c8a..0000000 --- a/_doc/使用说明.md +++ /dev/null @@ -1,781 +0,0 @@ -# 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 - - - -``` - -## 🔧 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 - - - -``` - -**属性说明：** - -| 属性 | 类型 | 默认值 | 说明 | -|------|------|--------|------| -| `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 - - - -``` - -**特性说明：** - -- ✅ 基于父元素定位，不会遮挡菜单 -- ✅ 宽度和高度默认 100%，占满父容器 -- ✅ 无遮罩背景，完全浮在父页面上 -- ✅ 路由切换或组件销毁时自动关闭 -- ✅ 支持多种位置和动画效果 -- ✅ 支持自定义头部右侧内容 - -## 📝 业务开发示例 - -### 创建业务页面 - -```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 项目示例或联系开发团队。 diff --git a/_doc/完整使用文档.md b/_doc/完整使用文档.md deleted file mode 100644 index 12aa056..0000000 --- a/_doc/完整使用文档.md +++ /dev/null @@ -1,1582 +0,0 @@ -# Admin Framework 完整使用文档 - -通用后台管理系统框架 - 包含系统功能、登录、路由管理、布局等核心功能 - ---- - -## 🎯 Demo 项目 - -📦 **已提供完整的示例项目**：`demo/` - -一个开箱即用的完整示例，包含： -- ✅ 框架集成配置 -- ✅ 登录页面 -- ✅ 主页欢迎页 -- ✅ 业务页面示例（产品列表 CRUD） -- ✅ Webpack 配置 -- ✅ 详细使用说明 - -**快速体验**： -```bash -cd demo -npm install -npm run dev -``` - -详细说明：[demo/README.md](./demo/README.md) - ---- - -## 📑 目录 - -- [特性](#特性) -- [快速开始](#快速开始) -- [完整使用示例](#完整使用示例) -- [API 文档](#api-文档) -- [系统页面和 API](#系统页面和-api) -- [开发指南](#开发指南) -- [常见问题](#常见问题) - ---- - -## ✨ 特性 - -✅ **极简 API** - 只需调用 `createApp()` 即可完成所有初始化 -✅ **模块化设计** - 组件、路由、状态管理等功能按模块组织 -✅ **主页组件**（欢迎页面，自动显示系统标题） -✅ **系统管理页面**（sys 开头的所有页面和功能） -✅ **系统 API**（system 和 system 所有 API） -✅ **全局组件**（Tables、Editor、Upload、FieldRenderer、FloatPanel 等） -✅ **布局组件**（Main、ParentView） -✅ **文件下载**（支持 CSV 等格式，自动处理换行符） -✅ **登录和错误页面**（Login、401、404、500） -✅ **用户登录和权限管理** -✅ **动态路由管理** -✅ **工具库**（HTTP、日期、Token、Cookie 等） -✅ **Vuex 状态管理** -✅ **路由守卫** -✅ **内置样式**（base.less、animate.css、ivewExpand.less、iconfont） - ---- - -## 🚀 快速开始 - -### 🎯 方式一：使用 Demo 项目（推荐新手） - -我们提供了一个完整的 **demo** 示例项目，可以直接运行查看效果！ - -```bash -# 1. 进入 demo 项目 -cd demo - -# 2. 安装依赖 -npm install - -# 3. 启动开发服务器 -npm run dev -``` - -浏览器会自动打开 `http://localhost:8080`，查看： -- `/login` - 登录页面 -- `/home` - 主页 -- `/business/product` - 业务示例页面 - -**详细说明**：查看 `demo/README.md` - ---- - -### 🔧 方式二：手动集成到项目 - -### 一、打包框架 - -#### 1. 进入框架目录 -```bash -cd admin-framework -``` - -#### 2. 安装依赖 -```bash -npm install -``` - -#### 3. 打包 -```bash -npm run build -``` - -打包完成后，会在 `dist` 目录生成 `admin-framework.js` 文件（约 200-300KB）。 - -### 二、在新项目中使用 - -#### 方式一：直接复制打包文件（推荐） - -1. 将 `dist/admin-framework.js` 复制到新项目的 `src/libs/` 目录 - -2. 在 `main.js` 中引入： -```javascript -import AdminFramework from './libs/admin-framework.js' -``` - -#### 方式二：作为 npm 包使用 - -1. 在 `admin-framework` 目录执行： -```bash -npm link -``` - -2. 在新项目目录执行： -```bash -npm link admin-framework -``` - -3. 在 `main.js` 中引入： -```javascript -import AdminFramework from 'admin-framework' -``` - -### 三、最小化使用示例 - -#### 1. 框架已包含的内容 - -**无需从原项目复制**： - -✅ **已包含**： -- **主页组件**（HomePage - 欢迎页面，显示系统标题） -- 所有系统页面（system、system） -- 所有系统 API（system、system） -- 所有全局组件（Tables、Editor、Upload、FieldRenderer 等） -- 布局组件（Main、ParentView） -- 登录和错误页面 -- 工具库和 Store 模块 -- **所有样式文件**（base.less、animate.css、ivewExpand.less） -- **字体图标文件**（iconfont） - -**只需准备**： -``` -├── App.vue # 应用根组件（可选） -``` - -#### 2. 创建 main.js（新版本 - 只需 8 行代码！） - -```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 - // 添加更多业务组件... - }, - - HomePage: CustomHomePage, // 可选：自定义首页组件，覆盖整个首页 - onReady() { - console.log('应用已启动!') - } -}) - -// 挂载应用 -app.$mount('#app') -``` - -#### 2.1 传统方式（兼容旧版本） - -```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 实例 -window.rootVue = 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) -``` - -**就这么简单！** 框架会自动： -- ✅ 注册 ViewUI（自动调用 `Vue.use(ViewUI)`） -- ✅ 注册 VueRouter（自动调用 `Vue.use(VueRouter)`） -- ✅ 注册 Vuex（自动调用 `Vue.use(Vuex)`） -- ✅ 创建 Store（包含用户、应用模块） -- ✅ 创建 Router（包含所有基础路由和动态路由） -- ✅ 初始化 HTTP -- ✅ 注册全局组件 -- ✅ 配置路由守卫 -- ✅ 支持自定义首页组件（通过 HomePage 参数传入） - -#### 3. 安装依赖 - -```bash -npm install vue vue-router vuex view-design axios dayjs js-cookie vuex-persistedstate -``` - -#### 4. 运行项目 - -```bash -npm run dev -``` - ---- - -## 📖 完整使用示例 - -### 步骤 1: 准备项目结构 - -``` -your-project/ -├── src/ -│ ├── config/ -│ │ └── index.js -│ ├── libs/ -│ │ └── admin-framework.js ← 框架文件 -│ ├── App.vue -│ └── main.js -├── package.json -└── webpack.config.js -``` - -### 步骤 2: 创建配置文件 - -在 `src/config/index.js` 中： - -```javascript -module.exports = { - title: '你的系统名称', - homeName: '首页', - apiUrl: 'http://localhost:9090/admin_api/', - 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/' - } -} -``` - -### 步骤 3: 创建 App.vue - -```vue - - - -``` - -### 步骤 4: 开发业务功能 - -#### 创建业务页面 - -```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 }) - } -} - -export default new ProductServer() -``` - ---- - -## 📚 API 文档 - -### 框架实例方法 - -#### install(Vue, options) -安装 Vue 插件 - -```javascript -Vue.use(AdminFramework, { - config: yourConfig, - ViewUI: ViewUI, - VueRouter: VueRouter, - Vuex: Vuex, - createPersistedState: createPersistedState, - HomePage: HomePage // 可选：自定义首页组件 -}) -``` - -**参数说明：** -- `config`: 项目配置对象（必需） -- `ViewUI`: ViewUI 实例（必需） -- `VueRouter`: VueRouter 类（必需） -- `Vuex`: Vuex 类（必需） -- `createPersistedState`: vuex-persistedstate 插件（必需） -- `HomePage`: 自定义首页组件（可选，不传则使用框架内置组件） - -#### initHttp(config, store) -初始化 HTTP 配置 - -```javascript -AdminFramework.initHttp({ - apiUrl: 'http://localhost:9090/admin_api/', - timeout: 300000 -}, store) -``` - -#### createRouter(Router, components, customRoutes, ViewUI, homeName) -创建路由实例 - -```javascript -const router = AdminFramework.createRouter( - VueRouter, - { LoginPage, Page401, Page404, Page500 }, - customRoutes, // 自定义业务路由 - ViewUI, - 'home' -) -``` - -#### createStore(Vuex, customModules, createPersistedState) -创建 Store 实例 - -```javascript -const store = AdminFramework.createStore( - Vuex, - { business: businessModule }, // 自定义业务模块 - createPersistedState -) -``` - -#### getRoutes(components) -获取动态路由 - -```javascript -const mainRoutes = AdminFramework.getRoutes({ - Main, - ParentView, - Page404 -}) -``` - -#### registerComponents(Vue, components) -注册全局组件 - -```javascript -AdminFramework.registerComponents(Vue, { - 'my-component': MyComponent -}) -``` - -### 工具库 - -#### http - HTTP 请求工具 - -```javascript -// GET 请求 -AdminFramework.http.get('/api/users', { page: 1 }) - -// POST 请求 -AdminFramework.http.post('/api/users', { name: 'test' }) - -// 文件导出 -AdminFramework.http.fileExport('/api/export', { type: 'excel' }) -``` - -**在组件中使用：** -```javascript -export default { - async mounted() { - const res = await this.$http.get('/api/users') - } -} -``` - -#### util - 工具函数 - -```javascript -// Token 管理 -AdminFramework.util.setToken(token) -AdminFramework.util.getToken() - -// 路由工具 -AdminFramework.util.getBreadCrumbList(route, homeRoute) -AdminFramework.util.getHomeRoute(routes, 'home') -``` - -**在组件中使用：** -```javascript -export default { - methods: { - getToken() { - return this.$util.getToken() - } - } -} -``` - -#### tools - 功能工具 - -```javascript -// 日期格式化 -AdminFramework.tools.formatDate(new Date(), 'YYYY-MM-DD HH:mm:ss') - -// UUID 生成 -AdminFramework.tools.generateUUID() - -// Cookie 操作 -AdminFramework.tools.setCookie('name', 'value') -AdminFramework.tools.getCookie('name') -``` - -**在组件中使用：** -```javascript -export default { - methods: { - formatDate() { - return this.$tools.formatDate(new Date(), 'YYYY-MM-DD') - } - } -} -``` - -#### uiTool - UI 工具 - -```javascript -// 设置响应式字体 -AdminFramework.uiTool.setRem() - -// 删除确认 -AdminFramework.uiTool.delConfirm(() => { - // 删除逻辑 -}) - -// 树形转换 -AdminFramework.uiTool.transformTree(treeData) -``` - -**在组件中使用：** -```javascript -export default { - methods: { - handleDelete() { - this.$uiTool.delConfirm(() => { - // 执行删除 - }) - } - } -} -``` - -### Store 模块 - -#### user 模块 - -```javascript -// 登录 -this.$store.dispatch('user/handleLogin', { - userFrom: { username, password }, - Main, - ParentView, - Page404 -}) - -// 登出 -this.$store.dispatch('user/handleLogOut') - -// 设置权限菜单 -this.$store.dispatch('user/setAuthorityMenus', { - Main, - ParentView, - Page404 -}) - -// 获取用户信息 -this.$store.getters['user/userName'] -this.$store.state.user.token -``` - -#### app 模块 - -```javascript -// 设置面包屑 -this.$store.commit('app/setBreadCrumb', route) - -// 获取系统标题 -this.$store.dispatch('app/getSysTitle', { - defaultTitle: '系统名称', - defaultLogo: '/logo.png' -}) - -// 获取系统配置 -this.$store.getters['app/sysFormModel'] -``` - ---- - -## 🗂️ 系统页面和 API - -### 已包含的系统页面 - -框架已内置所有系统管理页面，可直接从框架导入使用： - -#### 主页 -```javascript -import { - HomePage // 主页欢迎页面（显示系统标题） -} from 'admin-framework' -``` - -#### system 目录页面 -```javascript -import { - SysLog, // 系统日志管理 - SysLogOperate, // 系统操作日志 - SysParamSetup, // 参数设置 - SysRole, // 角色管理 - SysUser // 用户管理 -} from 'admin-framework' -``` - -#### system 目录页面 -```javascript -import { - SysControl, // 控制器管理 - SysMenu, // 菜单管理 - SysTitle // 系统标题设置 -} from 'admin-framework' -``` - -#### 在路由中使用 -```javascript -import { HomePage, SysUser, SysRole, SysMenu, SysLog, SysLogOperate } from 'admin-framework' - -const routes = [ - { - path: '/home', - name: 'home', - component: HomePage // 框架自动注册，也可手动使用 - }, - { - path: '/system/user', - name: 'sys_user', - component: SysUser - }, - { - path: '/system/role', - name: 'sys_role', - component: SysRole - }, - { - path: '/system/menu', - name: 'sys_menu', - component: SysMenu - }, - { - path: '/system/log', - name: 'sys_log', - component: SysLog - }, - { - path: '/system/log_operate', - name: 'sys_log_operate', - component: SysLogOperate - } -] -``` - -### 已包含的系统 API - -#### system API -```javascript -import { systemApi } from 'admin-framework' - -// 使用示例 -const { - userServer, - roleServer, - sysLogServe, - fileServe, - // ... 其他 API -} = systemApi - -// 调用 API -const users = await userServer.getList({ page: 1 }) -const roles = await roleServer.getList() -``` - -#### system API（所有 API 都在 systemApi 中） -```javascript -import { systemApi } from 'admin-framework' - -// 使用示例 -const { - userServer, - roleServer, - sysLogServe, - fileServe, - menuServer, - paramSetupServer, - modelServer, - formServer, - formFieldServer, - modelFieldServer, - tableServer, - rolePermissionServer, - sysControlTypeServer, - sysModuleServer, - sysAddressServer, - systemTypeServer, - plaAccountServer, - // ... 其他 API -} = systemApi - -// 调用 API -const users = await userServer.getList({ page: 1 }) -const roles = await roleServer.getList() -const menus = await menuServer.getTree() -const params = await paramSetupServer.getOne('sys_title') -``` - -### 全局组件 - -框架已包含所有全局组件，打包后会自动注册： - -```vue - -``` - -#### FloatPanel - 浮动面板组件 - -`FloatPanel` 是一个浮动在父窗体上的面板组件，类似于抽屉效果，调用方式和 `AsyncModal` 类似。 - -**基本使用：** - -```vue - - - -``` - -**调用方式（类似 AsyncModal）：** - -```vue - - - -``` - -**属性说明：** - -| 属性 | 类型 | 默认值 | 说明 | -|------|------|--------|------| -| `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`: 居中显示，带缩放动画 - -**特性说明：** - -- ✅ 基于父元素定位，不会遮挡菜单 -- ✅ 宽度和高度默认 100%，占满父容器 -- ✅ 无遮罩背景，完全浮在父页面上 -- ✅ 路由切换或组件销毁时自动关闭 -- ✅ 支持多种位置和动画效果 - ---- - -## 🛠️ 开发指南 - -### 开发模式 - -```bash -npm run dev -``` - -### 生产构建 - -```bash -npm run build -``` - -### 目录结构 - -``` -admin-framework/ -├── src/ -│ ├── utils/ # 工具库 -│ │ ├── tools.js # 功能工具 -│ │ ├── http.js # HTTP 工具 -│ │ ├── tools.js # 通用工具 -│ │ ├── uiTool.js # UI 工具 -│ │ └── util.js # 工具函数 -│ ├── store/ # Vuex 模块 -│ │ ├── user.js # 用户模块 -│ │ ├── app.js # 应用模块 -│ │ └── index.js # 导出 -│ ├── router/ # 路由配置 -│ │ └── index.js # 路由配置 -│ └── index.js # 入口文件 -├── dist/ # 打包输出 -│ └── admin-framework.js # 打包后的文件 -├── webpack.config.js # Webpack 配置 -├── package.json # 依赖配置 -└── README.md # 说明文档 -``` - -### 依赖说明 - -#### peerDependencies（需要在使用项目中安装） - -- vue: ^2.6.0 -- vue-router: ^3.0.0 -- vuex: ^3.0.0 -- view-design: ^4.0.0 -- axios: ^0.21.0 - -#### dependencies - -- dayjs: ^1.10.0 -- js-cookie: ^2.2.1 -- vuex-persistedstate: ^4.0.0 - ---- - -## ❓ 常见问题 - -### Q1: 打包后文件太大怎么办？ - -A: 框架已经将 Vue、VueRouter、Vuex、ViewUI、Axios 设置为外部依赖，不会打包进去。确保在项目中单独安装这些依赖。 - -### Q2: 如何只使用部分功能？ - -A: 可以按需导入： -```javascript -import { http, util, tools } from './libs/admin-framework.js' -``` - -### Q3: 如何自定义配置？ - -A: 修改 `config/index.js` 文件： -```javascript -module.exports = { - title: '你的系统名称', - apiUrl: 'http://your-api-url/', - // ... 其他配置 -} -``` - -### Q4: 如何添加业务路由？ - -A: 在创建路由时传入： -```javascript -const businessRoutes = [ - { - path: '/business/product', - component: () => import('@/view/business/product.vue') - } -] - -const router = AdminFramework.createRouter( - VueRouter, - { LoginPage, Page401, Page404, Page500 }, - businessRoutes, // ← 传入业务路由 - ViewUI -) -``` - -### Q5: 如何自定义路由守卫？ - -A: 你可以在创建路由后添加自己的守卫： - -```javascript -const router = AdminFramework.createRouter(...) - -router.beforeEach((to, from, next) => { - // 你的自定义逻辑 - next() -}) -``` - -### Q6: 如何使用文件下载功能？ - -A: 框架提供了便捷的文件下载方法： - -```javascript -// 在 Vue 组件中使用 -export default { - methods: { - exportData() { - // 调用 API 获取数据 - this.$http.fileExport('/api/export', params).then(res => { - // 下载文件（自动处理换行符） - this.$uiTool.downloadFile(res, '数据导出.csv') - this.$Message.success('导出成功！') - }).catch(error => { - this.$Message.error('导出失败：' + error.message) - }) - } - } -} -``` - -**特性：** -- ✅ 自动处理 CSV 换行符 -- ✅ 支持多种文件格式 -- ✅ 浏览器兼容性好 -- ✅ 自动清理临时 URL 对象 - -### Q7: 如何扩展 Store 模块？ - -A: 在创建 Store 时传入自定义模块： - -```javascript -const store = AdminFramework.createStore(Vuex, { - myModule: { - namespaced: true, - state: { ... }, - mutations: { ... }, - actions: { ... } - } -}) -``` - -### Q7: 如何使用登录功能？ - -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' }) - } - } -} -``` - -### Q8: 需要复制哪些文件到新项目？ - -A: **框架已包含所有系统功能，只需准备：** -- `config/index.js` - 配置文件 -- `App.vue` - 应用根组件 -- `main.js` - 入口文件 - -其他所有系统页面、API、组件都已在框架中，无需复制！ - -### Q9: 报错 `must call Vue.use(Vuex) before creating a store instance` 怎么办？ - -A: **这个问题已在框架 v1.0.0+ 中修复！** - -如果你使用的是旧版本框架，请重新构建： -```bash -cd admin-framework -npm run build -``` - -然后将新的 `dist/admin-framework.js` 复制到项目中替换旧文件。 - -新版本框架会自动调用 `Vue.use(Vuex)` 和 `Vue.use(VueRouter)`，无需手动注册！ - -### Q13: `this.$store.dispatch` 报错怎么办？ - -A: **常见原因和解决方案**： - -**1. Store 未正确挂载** - -确保在创建 Vue 实例时使用了框架的 store： -```javascript -new Vue({ - el: '#app', - router: AdminFramework.router, - store: AdminFramework.store, // ✅ 必须挂载 store - render: h => h(App) -}) -``` - -**2. 命名空间路径错误** - -框架的 store 模块都使用了 `namespaced: true`，必须带上模块名： -```javascript -// ❌ 错误 - 缺少命名空间 -this.$store.dispatch('setAuthorityMenus', data) - -// ✅ 正确 - 带上模块名 user/ -this.$store.dispatch('user/setAuthorityMenus', data) - -// ✅ 正确 - app 模块 -this.$store.dispatch('app/getSysTitle', { defaultTitle: '系统' }) -``` - -**3. Store 在 setup/install 时未创建** - -确保在 Vue.use() 时传入了 Vuex： -```javascript -// ✅ 正确 - 框架会自动创建 store -Vue.use(AdminFramework, { - config, - ViewUI, - VueRouter, - Vuex, // ✅ 必须传入 Vuex - createPersistedState -}) -``` - -**4. 可用的 Store Actions** - -**user 模块**（需要加 `user/` 前缀）： -- `user/setAuthorityMenus` - 设置权限菜单 -- `user/handleLogin` - 处理登录 -- `user/handleLogOut` - 处理登出 - -**app 模块**（需要加 `app/` 前缀）： -- `app/getSysTitle` - 获取系统标题和 Logo - -**完整示例**： -```javascript -export default { - mounted() { - // 设置权限菜单 - this.$store.dispatch('user/setAuthorityMenus', { - Main: AdminFramework.Main, - ParentView: AdminFramework.ParentView, - Page404: AdminFramework.Page404 - }) - - // 获取系统标题 - this.$store.dispatch('app/getSysTitle', { - defaultTitle: '智能代码平台', - defaultLogo: '' - }) - }, - 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' }) - }, - logout() { - // 处理登出 - this.$store.dispatch('user/handleLogOut') - } - } -} -``` - -### Q11: 主页 HomePage 组件说明 - -A: **框架支持两种方式使用首页组件：使用内置组件或传入自定义组件。** - -#### 方式一：使用框架内置的主页组件（默认） - -**默认主页组件**： -```vue - - -``` - -**特性**： -- ✅ 自动从 Vuex Store 获取系统标题（`app/sysFormModel`） -- ✅ 优雅的欢迎页面样式 -- ✅ 无需额外配置 - -**使用方式**： -```javascript -// 不传入 HomePage，框架会使用内置组件 -Vue.use(AdminFramework, { - config, - ViewUI, - VueRouter, - Vuex, - createPersistedState -}) -``` - -#### 方式二：传入自定义首页组件（推荐） - -**创建自定义首页组件**： -```vue - - - - - - -``` - -**传入自定义组件**： -```javascript -import HomePage from './views/home/index.vue' - -Vue.use(AdminFramework, { - config, - ViewUI, - VueRouter, - Vuex, - createPersistedState, - HomePage // ✅ 传入自定义首页组件 -}) -``` - -#### 首页路由配置 - -**重要说明**： -- ⚠️ **首页路由完全由后端权限菜单返回** -- ⚠️ 后端必须返回 `path: '/home'` 的菜单配置 -- ⚠️ 后端返回的 `component` 字段会映射到实际组件 - -**后端菜单配置示例**： -```json -{ - "id": 1, - "name": "首页", - "path": "/home", - "component": "home/index", // 映射到 src/views/home/index.vue - "parent_id": 0, - "type": "页面", - "is_show_menu": 1, - "icon": "md-home", - "sort": 1 -} -``` - -**组件映射规则**： -```javascript -// 后端返回: "component": "home/index" -// 实际加载: src/views/home/index.vue - -// 后端返回: "component": "system/user" -// 实际加载: src/views/system/user.vue -``` - -#### 降级方案 - -如果后端接口失败，框架会使用默认菜单配置（`src/config/menuConfig.js`）： -```javascript -export const defaultMenus = [ - { - id: 1, - name: '首页', - path: '/home', - component: 'home/index', - parent_id: 0, - type: '页面', - is_show_menu: 1, - icon: 'md-home', - sort: 1 - }, - // ... 其他菜单 -] -``` - -#### 直接使用 HomePage 组件 - -```javascript -// 获取框架内置的 HomePage 组件 -import AdminFramework from './libs/admin-framework.js' -const HomePage = AdminFramework.HomePage - -// 在路由中使用 -const routes = [ - { - path: '/home', - name: 'home', - component: HomePage - } -] -``` - -#### 最佳实践 - -**推荐做法**： -1. ✅ 创建自定义首页组件 `src/views/home/index.vue` -2. ✅ 在 `Vue.use()` 时传入 `HomePage` 参数 -3. ✅ 确保后端返回首页菜单配置 -4. ✅ 在 `defaultMenus` 中包含首页配置作为降级方案 - -**完整示例**： -```javascript -// main.js -import HomePage from './views/home/index.vue' - -Vue.use(AdminFramework, { - config, - ViewUI, - VueRouter, - Vuex, - createPersistedState, - HomePage // 传入自定义首页组件 -}) - -new Vue({ - el: '#app', - router: AdminFramework.router, - store: AdminFramework.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 管理系统' - } - } -}) -``` - -### Q12: 需要单独引入样式文件吗？ - -A: **不需要！框架已内置所有样式。** - -框架打包时已自动包含以下样式： -- ✅ `base.less` - 基础样式 -- ✅ `animate.css` - 动画样式 -- ✅ `ivewExpand.less` - ViewUI 扩展样式 -- ✅ `iconfont.css` - 字体图标样式 - -**无需在项目中**： -```javascript -// ❌ 不需要这些导入 -import 'admin-framework/assets/css/base.less' -import 'admin-framework/assets/css/animate.css' -``` - -**只需引入框架即可**： -```javascript -// ✅ 样式已自动包含 -import AdminFramework from './libs/admin-framework.js' -Vue.use(AdminFramework, { ... }) -``` - -框架使用时样式会自动注入到页面中，无需任何额外配置！ - -### Q14: 权限菜单中的业务页面显示 404 怎么办？ - -A: **需要配置组件映射表。** - -**问题原因**： -后端权限菜单接口返回的组件路径（如 `ball/games.vue`）需要映射到实际组件。 - -**解决方案**： - -#### 方式一：在 Vue.use 时配置（推荐） - -```javascript -// 1. 导入业务组件 -import GamesComponent from './views/ball/games.vue' -import PayOrdersComponent from './views/order/pay_orders.vue' - -// 2. 配置映射 -Vue.use(AdminFramework, { - config, - ViewUI, - VueRouter, - Vuex, - createPersistedState, - // ✅ 配置组件映射 - componentMap: { - 'ball/games': GamesComponent, - 'order/pay_orders': PayOrdersComponent - // 根据权限菜单接口的 component 字段添加... - } -}) -``` - -#### 方式二：使用 addComponentMap 方法 - -```javascript -// 先使用框架 -Vue.use(AdminFramework, { config, ViewUI, VueRouter, Vuex, createPersistedState }) - -// 然后添加映射 -AdminFramework.addComponentMap({ - 'ball/games': GamesComponent, - 'order/pay_orders': PayOrdersComponent -}) -``` - -#### 框架已自动映射的系统组件 - -以下组件**无需配置**，框架已自动映射： -- ✅ `home/index.vue` - 主页 -- ✅ `system/sys_user.vue` - 用户管理 -- ✅ `system/sys_role.vue` - 角色管理 -- ✅ `system/sys_log.vue` - 日志管理 -- ✅ `system/sys_param_setup.vue` - 参数设置 -- ✅ `system/sys_menu.vue` - 菜单管理 -- ✅ `system/sys_control.vue` - 控制器管理 -- ✅ `system/sys_title.vue` - 系统标题设置 - -#### 配置技巧 - -**路径规则**： -- 后端返回：`"component": "ball/games.vue"` -- 配置映射：`'ball/games': GamesComponent`（不需要 `.vue` 后缀） -- 框架会自动处理带和不带 `.vue` 的路径 - -**完整示例**： -```javascript -// 根据你的权限菜单接口，导入所有可能用到的组件 -import GamesComponent from './views/ball/games.vue' -import WchUsersComponent from './views/ball/wch_users.vue' -import PayOrdersComponent from './views/order/pay_orders.vue' - -Vue.use(AdminFramework, { - config, - ViewUI, - VueRouter, - Vuex, - createPersistedState, - componentMap: { - 'ball/games': GamesComponent, - 'ball/wch_users': WchUsersComponent, - 'order/pay_orders': PayOrdersComponent - } -}) -``` - -**未映射的组件**： -会显示友好提示：`页面组件未加载: xxx.vue，请在项目中创建此组件或在组件映射表中注册` - ---- - -## 📦 完整的项目结构示例 - -``` -your-project/ -├── src/ -│ ├── api/ -│ │ └── business/ # 你的业务 API -│ ├── assets/ -│ │ └── images/ # 你的业务图片（框架样式已内置） -│ ├── config/ -│ │ └── index.js # 配置文件 -│ ├── libs/ -│ │ └── admin-framework.js # 框架文件（已包含所有样式） -│ ├── view/ -│ │ └── business/ # 你的业务页面 -│ ├── App.vue -│ └── main.js -├── package.json -└── webpack.config.js -``` - -**说明**： -- 框架已内置所有系统样式，无需创建 `assets/css` 目录 -- 只需要准备你自己的业务图片和业务样式（如有需要） - ---- - -## 📝 版本信息 - -**当前版本**: 1.0.0 - -**更新日志**: -- v1.0.0 - 初始版本，包含所有核心功能 - ---- - -## 📄 许可证 - -MIT License - ---- - -## 💬 技术支持 - -如有问题，请查看本文档或联系开发团队。 - ---- - -## 🎯 快速参考 - -### 最小化代码示例 - -```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' - -// 框架会自动调用 Vue.use(ViewUI/VueRouter/Vuex) -Vue.use(AdminFramework, { config, ViewUI, VueRouter, Vuex, createPersistedState }) - -new Vue({ - el: '#app', - router: AdminFramework.router, // 框架自动创建 - store: AdminFramework.store, // 框架自动创建 - render: h => h(App) -}) -``` - -### 常用API速查 - -```javascript -// HTTP请求 -this.$http.get(url, params) -this.$http.post(url, data) - -// Token操作 -this.$util.setToken(token) -this.$util.getToken() - -// 日期格式化 -this.$tools.formatDate(date, 'YYYY-MM-DD') - -// 删除确认 -this.$uiTool.delConfirm(() => { /* 删除逻辑 */ }) - -// 登录 -this.$store.dispatch('user/handleLogin', { userFrom, Main, ParentView, Page404 }) - -// 登出 -this.$store.dispatch('user/handleLogOut') -``` - ---- - -**祝开发愉快！** 🎉 - diff --git a/_doc/快速开始.md b/_doc/快速开始.md deleted file mode 100644 index 1fa2abe..0000000 --- a/_doc/快速开始.md +++ /dev/null @@ -1,325 +0,0 @@ -# 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. 全局组件 -- ✅ `` - 增强型表格 -- ✅ `` - 单图上传 -- ✅ `` - 多图上传 -- ✅ `` - 树形表格 -- ✅ `` - 异步弹窗 -- ✅ `` - 富文本编辑器 -- ✅ `` - 图标选择器 -- ✅ `` - 浮动面板 - -### 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 - - - - -``` - -### 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. **利用内置组件** - 如 ``、`` 等，提高开发效率 -4. **使用 `onReady` 回调** - 在应用启动后执行初始化逻辑 - -## 🎉 开始开发吧！ - -现在你已经了解了 AdminFramework 的快速使用方法，开始构建你的管理系统吧！