1370 lines
29 KiB
Markdown
1370 lines
29 KiB
Markdown
# Admin Framework 完整使用文档
|
||
|
||
通用后台管理系统框架 - 包含系统功能、登录、路由管理、布局等核心功能
|
||
|
||
---
|
||
|
||
## 🎯 Demo 项目
|
||
|
||
📦 **已提供完整的示例项目**：`demo-project/`
|
||
|
||
一个开箱即用的完整示例，包含：
|
||
- ✅ 框架集成配置
|
||
- ✅ 登录页面
|
||
- ✅ 主页欢迎页
|
||
- ✅ 业务页面示例（产品列表 CRUD）
|
||
- ✅ Webpack 配置
|
||
- ✅ 详细使用说明
|
||
|
||
**快速体验**：
|
||
```bash
|
||
cd demo-project
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
详细说明：[demo-project/README.md](./demo-project/README.md)
|
||
|
||
---
|
||
|
||
## 📑 目录
|
||
|
||
- [特性](#特性)
|
||
- [快速开始](#快速开始)
|
||
- [完整使用示例](#完整使用示例)
|
||
- [API 文档](#api-文档)
|
||
- [系统页面和 API](#系统页面和-api)
|
||
- [开发指南](#开发指南)
|
||
- [常见问题](#常见问题)
|
||
|
||
---
|
||
|
||
## ✨ 特性
|
||
|
||
✅ **主页组件**（欢迎页面，自动显示系统标题）
|
||
✅ **系统管理页面**（sys 开头的所有页面和功能）
|
||
✅ **系统 API**（system 和 system_high 所有 API）
|
||
✅ **全局组件**（Tables、Editor、Upload 等）
|
||
✅ **布局组件**（Main、ParentView）
|
||
✅ **登录和错误页面**（Login、401、404、500）
|
||
✅ **用户登录和权限管理**
|
||
✅ **动态路由管理**
|
||
✅ **工具库**（HTTP、日期、Token、Cookie 等）
|
||
✅ **Vuex 状态管理**
|
||
✅ **路由守卫**
|
||
✅ **内置样式**（base.less、animate.css、ivewExpand.less、iconfont）
|
||
|
||
---
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 🎯 方式一：使用 Demo 项目（推荐新手）
|
||
|
||
我们提供了一个完整的 **demo-project** 示例项目，可以直接运行查看效果！
|
||
|
||
```bash
|
||
# 1. 进入 demo 项目
|
||
cd demo-project
|
||
|
||
# 2. 安装依赖
|
||
npm install
|
||
|
||
# 3. 启动开发服务器
|
||
npm run dev
|
||
```
|
||
|
||
浏览器会自动打开 `http://localhost:8080`，查看：
|
||
- `/login` - 登录页面
|
||
- `/home` - 主页
|
||
- `/business/product` - 业务示例页面
|
||
|
||
**详细说明**：查看 `demo-project/README.md` 和 `demo-project/INSTALL.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_high）
|
||
- 所有系统 API（system、system_high）
|
||
- 所有全局组件（Tables、Editor、Upload 等）
|
||
- 布局组件（Main、ParentView）
|
||
- 登录和错误页面
|
||
- 工具库和 Store 模块
|
||
- **所有样式文件**（base.less、animate.css、ivewExpand.less）
|
||
- **字体图标文件**（iconfont）
|
||
|
||
**只需准备**：
|
||
```
|
||
├── config/index.js # 配置文件（根据你的项目修改）
|
||
└── App.vue # 应用根组件
|
||
```
|
||
|
||
#### 2. 创建 main.js（只需 10 行代码！）
|
||
|
||
```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
|
||
<template>
|
||
<div id="app">
|
||
<router-view/>
|
||
</div>
|
||
</template>
|
||
|
||
<script>
|
||
export default {
|
||
name: 'App'
|
||
}
|
||
</script>
|
||
```
|
||
|
||
### 步骤 4: 开发业务功能
|
||
|
||
#### 创建业务页面
|
||
|
||
```vue
|
||
<!-- src/view/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' }
|
||
]
|
||
}
|
||
},
|
||
async mounted() {
|
||
await this.loadData()
|
||
},
|
||
methods: {
|
||
async loadData() {
|
||
// 使用框架提供的 http 工具
|
||
const res = await this.$http.get('/product/list', { page: 1 })
|
||
this.list = res.data
|
||
}
|
||
}
|
||
}
|
||
</script>
|
||
```
|
||
|
||
#### 创建业务 API
|
||
|
||
```javascript
|
||
// src/api/business/productServer.js
|
||
import http from '@/utils/admin-framework.js'
|
||
|
||
class ProductServer {
|
||
async getList(params) {
|
||
return await http.http.get('/product/list', params)
|
||
}
|
||
|
||
async save(data) {
|
||
return await http.http.post('/product/save', data)
|
||
}
|
||
|
||
async delete(id) {
|
||
return await http.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, // 系统日志管理
|
||
SysParamSetup, // 参数设置
|
||
SysRole, // 角色管理
|
||
SysUser // 用户管理
|
||
} from 'admin-framework'
|
||
```
|
||
|
||
#### system_high 目录页面
|
||
```javascript
|
||
import {
|
||
SysControl, // 控制器管理
|
||
SysMenu, // 菜单管理
|
||
SysTitle // 系统标题设置
|
||
} from 'admin-framework'
|
||
```
|
||
|
||
#### 在路由中使用
|
||
```javascript
|
||
import { HomePage, SysUser, SysRole, SysMenu } 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_high/menu',
|
||
name: 'sys_menu',
|
||
component: SysMenu
|
||
}
|
||
]
|
||
```
|
||
|
||
### 已包含的系统 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_high API
|
||
```javascript
|
||
import { systemHighApi } from 'admin-framework'
|
||
|
||
// 使用示例
|
||
const {
|
||
menuServer,
|
||
paramSetupServer,
|
||
modelServer,
|
||
// ... 其他 API
|
||
} = systemHighApi
|
||
|
||
// 调用 API
|
||
const menus = await menuServer.getTree()
|
||
const params = await paramSetupServer.getOne('sys_title')
|
||
```
|
||
|
||
### 全局组件
|
||
|
||
框架已包含所有全局组件，打包后会自动注册：
|
||
|
||
```vue
|
||
<template>
|
||
<div>
|
||
<Tables :columns="columns" :data="data" />
|
||
<Editor v-model="content" />
|
||
<UploadSingle v-model="fileUrl" />
|
||
<TreeGrid :data="treeData" />
|
||
</div>
|
||
</template>
|
||
```
|
||
|
||
---
|
||
|
||
## 🛠️ 开发指南
|
||
|
||
### 开发模式
|
||
|
||
```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: 如何扩展 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
|
||
<!-- 已内置在框架中 -->
|
||
<template>
|
||
<div class="content-view">
|
||
<h1 class="home-title">
|
||
<span class="hy">欢迎登陆， </span>
|
||
{{ sysFormModel.title }}
|
||
</h1>
|
||
</div>
|
||
</template>
|
||
```
|
||
|
||
**特性**：
|
||
- ✅ 自动从 Vuex Store 获取系统标题（`app/sysFormModel`）
|
||
- ✅ 优雅的欢迎页面样式
|
||
- ✅ 无需额外配置
|
||
|
||
**使用方式**：
|
||
```javascript
|
||
// 不传入 HomePage，框架会使用内置组件
|
||
Vue.use(AdminFramework, {
|
||
config,
|
||
ViewUI,
|
||
VueRouter,
|
||
Vuex,
|
||
createPersistedState
|
||
})
|
||
```
|
||
|
||
#### 方式二：传入自定义首页组件（推荐）
|
||
|
||
**创建自定义首页组件**：
|
||
```vue
|
||
<!-- src/views/home/index.vue -->
|
||
<template>
|
||
<div class="custom-home">
|
||
<h1>欢迎使用 {{ sysFormModel.title }}</h1>
|
||
<p>这是自定义的首页内容</p>
|
||
<!-- 你的自定义内容 -->
|
||
</div>
|
||
</template>
|
||
|
||
<script>
|
||
import { mapGetters } from 'vuex'
|
||
|
||
export default {
|
||
computed: {
|
||
...mapGetters({
|
||
sysFormModel: 'app/sysFormModel'
|
||
})
|
||
}
|
||
}
|
||
</script>
|
||
|
||
<style scoped>
|
||
.custom-home {
|
||
padding: 20px;
|
||
}
|
||
</style>
|
||
```
|
||
|
||
**传入自定义组件**：
|
||
```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_high/sys_menu.vue` - 菜单管理
|
||
- ✅ `system_high/sys_control.vue` - 控制器管理
|
||
- ✅ `system_high/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')
|
||
```
|
||
|
||
---
|
||
|
||
**祝开发愉快！** 🎉
|
||
|