admin_core/_doc/使用说明.md

Admin Framework 使用说明

一个基于 Vue2 的通用后台管理系统框架，包含完整的系统功能、登录、路由管理、布局等核心功能。

📦 框架特性

✨ 核心功能

• ✅ 简化的 API - 只需调用 createApp() 即可完成所有初始化
• ✅ 模块化设计 - 组件、路由、状态管理等功能按模块组织
• ✅ 完整的系统管理页面 - 用户、角色、菜单、日志等管理
• ✅ 登录和权限管理 - 完整的登录流程和权限控制
• ✅ 动态路由管理 - 基于权限菜单的动态路由生成
• ✅ Vuex 状态管理 - 用户、应用状态管理
• ✅ 全局组件库 - Tables、Editor、Upload、TreeGrid、FieldRenderer 等
• ✅ 工具库 - 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 项目，可以直接运行查看效果：

# 1. 进入 demo 项目
cd demo

# 2. 安装依赖
npm install

# 3. 启动开发服务器
npm run dev

浏览器会自动打开 http://localhost:8080，查看：

• /login - 登录页面
• /home - 主页
• /system/user - 用户管理
• /ball/games - 业务示例页面

方式二：构建框架

# 1. 安装依赖
npm install

# 2. 构建框架
npm run build

# 3. 产物在 dist/admin-framework.js

🎯 极简使用方式

只需 3 步即可完成集成！

1. 引入框架

import AdminFramework from './admin-framework.js'

2. 创建应用

const app = AdminFramework.createApp({
  title: '我的管理系统',
  apiUrl: 'http://localhost:9098/admin_api/',
  componentMap: {
    'business/product': ProductComponent,
    'business/order': OrderComponent
  }
})

3. 挂载应用

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. 安装依赖

npm install vue vue-router vuex view-design axios dayjs js-cookie vuex-persistedstate

3. 创建配置文件

在 src/config/index.js 中：

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（新版本 - 推荐）

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

<template>
  <div id="app">
    <router-view/>
  </div>
</template>

<script>
export default {
  name: 'App'
}
</script>

🔧 API 使用指南

框架实例方法

createApp(config) - 推荐使用

创建应用实例（新版本 API）

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 工具

// 在组件中使用
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 工具

// 在组件中使用
export default {
  methods: {
    handleDelete() {
      // 删除确认
      this.$uiTool.delConfirm(() => {
        // 执行删除逻辑
      })
      
      // 设置响应式字体
      this.$uiTool.setRem()
      
      // 树形转换
      const treeData = this.$uiTool.transformTree(flatData)
    }
  }
}

功能工具

// 在组件中使用
export default {
  methods: {
    downloadFile() {
      // 文件下载
      this.$uiTool.downloadFile(response, 'filename.csv')
    }
  }
}

通用工具

// 在组件中使用
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 模块

// 登录
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 模块

// 设置面包屑
this.$store.commit('app/setBreadCrumb', route)

// 获取系统标题
this.$store.dispatch('app/getSysTitle', {
  defaultTitle: '系统名称',
  defaultLogo: '/logo.png'
})

// 获取系统配置
const sysFormModel = this.$store.getters['app/sysFormModel']

🗂️ 组件映射配置

业务组件映射

当后端权限菜单接口返回组件路径时，需要配置映射表：

// 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

框架实例会自动暴露到全局，可以在任何地方访问：

// 在非 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 组件中可以直接使用：

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 等格式：

// 在 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 对象

📝 业务开发示例

创建业务页面

<!-- src/views/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' },
        { title: '价格', key: 'price' }
      ]
    }
  },
  async mounted() {
    await this.loadData()
  },
  methods: {
    async loadData() {
      // 使用框架提供的 http 工具
      const res = await this.$http.get('/product/list', { page: 1 })
      this.list = res.data
    },
    
    async handleDelete(id) {
      // 使用框架提供的 UI 工具
      this.$uiTool.delConfirm(async () => {
        await this.$http.post('/product/delete', { id })
        this.$Message.success('删除成功')
        await this.loadData()
      })
    }
  }
}
</script>

创建业务 API

// 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: 可以按需导入：

import { http, uiTool, tools } from './libs/admin-framework.js'

Q3: 权限菜单中的业务页面显示 404 怎么办？

A: 需要配置组件映射表：

Vue.use(AdminFramework, {
  // ... 其他配置
  componentMap: {
    'ball/games': GamesComponent,
    'order/pay_orders': PayOrdersComponent
  }
})

Q4: 如何自定义配置？

A: 修改 config/index.js 文件：

module.exports = {
  title: '你的系统名称',
  apiUrl: 'http://your-api-url/',
  // ... 其他配置
}

Q5: 如何使用登录功能？

A: 在组件中：

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 - 字体图标样式

只需引入框架即可：

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 项目示例或联系开发团队。