Files
admin_core/完整使用文档.md
张成 88093ad4bc 1
2025-10-08 15:22:34 +08:00

880 lines
17 KiB
Markdown
Raw 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 完整使用文档
通用后台管理系统框架 - 包含系统功能、登录、路由管理、布局等核心功能
---
## 📑 目录
- [特性](#特性)
- [快速开始](#快速开始)
- [完整使用示例](#完整使用示例)
- [API 文档](#api-文档)
- [系统页面和 API](#系统页面和-api)
- [开发指南](#开发指南)
- [常见问题](#常见问题)
---
## ✨ 特性
**系统管理页面**sys 开头的所有页面和功能)
**系统 API**system 和 system_high 所有 API
**全局组件**Tables、Editor、Upload 等)
**布局组件**Main、ParentView
**登录和错误页面**Login、401、404、500
**用户登录和权限管理**
**动态路由管理**
**工具库**HTTP、日期、Token、Cookie 等)
**Vuex 状态管理**
**路由守卫**
---
## 🚀 快速开始
### 一、打包框架
#### 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. 框架已包含的内容
**无需从原项目复制**
**已包含**
- 所有系统页面system、system_high
- 所有系统 APIsystem、system_high
- 所有全局组件Tables、Editor、Upload 等)
- 布局组件Main、ParentView
- 登录和错误页面
- 工具库和 Store 模块
**只需准备**
```
├── config/index.js # 配置文件(根据你的项目修改)
└── App.vue # 应用根组件
```
#### 2. 创建 main.js只需 10 行代码222222
```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(AdminFramework, {
config,
ViewUI,
VueRouter,
Vuex,
createPersistedState
})
// 创建 Vue 实例
window.rootVue = new Vue({
el: '#app',
router: AdminFramework.router, // 使用框架自动创建的 router
store: AdminFramework.store, // 使用框架自动创建的 store
render: h => h(App),
mounted() {
AdminFramework.uiTool.setRem()
this.$store.dispatch('user/setAuthorityMenus', {
Main: AdminFramework.Main,
ParentView: AdminFramework.ParentView,
Page404: AdminFramework.Page404
})
}
})
// 响应式适配
window.addEventListener('load', AdminFramework.uiTool.setRem)
window.addEventListener('resize', AdminFramework.uiTool.setRem)
```
**就这么简单!** 框架会自动:
- ✅ 注册 ViewUI
- ✅ 创建 Store包含用户、应用模块
- ✅ 创建 Router包含所有基础路由和动态路由
- ✅ 初始化 HTTP
- ✅ 设置 API 服务
- ✅ 注册全局组件
- ✅ 配置路由守卫
#### 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
})
```
**参数说明:**
- `config`: 项目配置对象
- `ViewUI`: ViewUI 实例
- `VueRouter`: VueRouter 类
- `Vuex`: Vuex 类
- `createPersistedState`: vuex-persistedstate 插件
#### initHttp(config, store)
初始化 HTTP 配置
```javascript
AdminFramework.initHttp({
apiUrl: 'http://localhost:9090/admin_api/',
timeout: 300000
}, store)
```
#### setUserServer(userServer)
设置用户服务实例
```javascript
AdminFramework.setUserServer(userServer)
```
#### setParamSetupServer(paramSetupServer)
设置参数设置服务实例
```javascript
AdminFramework.setParamSetupServer(paramSetupServer)
```
#### 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
### 已包含的系统页面
框架已内置所有系统管理页面,可直接从框架导入使用:
#### system 目录页面
```javascript
import {
SysLog, // 系统日志管理
SysParamSetup, // 参数设置
SysRole, // 角色管理
SysUser, // 用户管理
WchCities, // 城市管理
WchProfessions // 职业管理
} from 'admin-framework'
```
#### system_high 目录页面
```javascript
import {
SysControl, // 控制器管理
SysMenu, // 菜单管理
SysTitle // 系统标题设置
} from 'admin-framework'
```
#### 在路由中使用
```javascript
import { SysUser, SysRole, SysMenu } from 'admin-framework'
const routes = [
{
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、组件都已在框架中无需复制
---
## 📦 完整的项目结构示例
```
your-project/
├── src/
│ ├── api/
│ │ └── business/ # 你的业务 API
│ ├── assets/
│ │ ├── css/ # 样式文件
│ │ └── images/ # 图片
│ ├── config/
│ │ └── index.js # 配置文件
│ ├── libs/
│ │ └── admin-framework.js # 框架文件
│ ├── view/
│ │ └── business/ # 你的业务页面
│ ├── App.vue
│ └── main.js
├── package.json
└── webpack.config.js
```
---
## 📝 版本信息
**当前版本**: 1.0.0
**更新日志**:
- v1.0.0 - 初始版本,包含所有核心功能
---
## 📄 许可证
MIT License
---
## 💬 技术支持
如有问题,请查看本文档或联系开发团队。
---
## 🎯 快速参考
### 最小化代码示例10行
```javascript
import Vue from 'vue'
import AdminFramework from './libs/admin-framework.js'
import App from './App.vue'
import config from './config'
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')
```
---
**祝开发愉快!** 🎉