admin_core/使用说明.md

Admin Framework 使用说明

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

📦 框架特性

✨ 核心功能

• ✅ 完整的系统管理页面 - 用户、角色、菜单、日志等管理
• ✅ 登录和权限管理 - 完整的登录流程和权限控制
• ✅ 动态路由管理 - 基于权限菜单的动态路由生成
• ✅ Vuex 状态管理 - 用户、应用状态管理
• ✅ 全局组件库 - Tables、Editor、Upload、TreeGrid 等
• ✅ 工具库 - HTTP、日期、Token、Cookie 等工具
• ✅ 内置样式 - base.less、animate.css、iconfont 等
• ✅ 响应式布局 - 支持移动端适配

🎯 内置页面组件

• 主页组件 (HomePage) - 欢迎页面，显示系统标题
• 系统管理页面 (SysUser, SysRole, SysLog, SysParamSetup)
• 高级管理页面 (SysMenu, SysControl, SysTitle)
• 登录页面 (LoginPage)
• 错误页面 (Page401, Page404, Page500)

🛠️ 内置工具

• HTTP 工具 (http) - 封装了 axios，支持拦截器
• UI 工具 (uiTool) - 删除确认、树形转换、响应式设置
• 功能工具 (funTool) - 文件下载等
• 通用工具 (tools) - 日期格式化、UUID 生成、Cookie 操作

🚀 快速开始

方式一：使用 Demo 项目（推荐）

我们提供了一个完整的 demo 项目，可以直接运行查看效果：

# 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

📖 完整使用指南

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 Vue from 'vue'
import VueRouter from 'vue-router'
import Vuex from 'vuex'
import ViewUI from 'view-design'
import createPersistedState from 'vuex-persistedstate'
import AdminFramework from './libs/admin-framework.js'
import App from './App.vue'
import config from './config'

// 可选：导入业务组件（根据权限菜单接口的 component 字段）
import GamesComponent from './views/ball/games.vue'
import PayOrdersComponent from './views/order/pay_orders.vue'

// 🎉 只需这一行！框架自动完成所有初始化
Vue.use(AdminFramework, {
  config,
  ViewUI,
  VueRouter,
  Vuex,
  createPersistedState,
  // ✅ 可选：配置业务组件映射（用于权限菜单）
  componentMap: {
    'ball/games': GamesComponent,
    'order/pay_orders': PayOrdersComponent
    // 添加更多业务组件...
  }
})

// 创建 Vue 实例
new Vue({
  el: '#app',
  router: AdminFramework.router,  // 使用框架自动创建的 router
  store: AdminFramework.store,    // 使用框架自动创建的 store
  render: h => h(App),
  mounted() {
    // 设置响应式字体
    AdminFramework.uiTool.setRem()

    // 只在已登录时获取系统标题
    const token = this.$store.state.user.token
    if (token) {
      this.$store.dispatch('app/getSysTitle', {
        defaultTitle: 'Demo 管理系统',
        defaultLogo: ''
      })
    } else {
      document.title = 'Demo 管理系统'
    }
  }
})

// 响应式适配
window.addEventListener('load', AdminFramework.uiTool.setRem)
window.addEventListener('resize', AdminFramework.uiTool.setRem)

5. 创建 App.vue

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

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

🔧 API 使用指南

框架实例方法

install(Vue, options)

安装 Vue 插件

Vue.use(AdminFramework, {
  config: yourConfig,           // 项目配置对象（必需）
  ViewUI: ViewUI,              // ViewUI 实例（必需）
  VueRouter: VueRouter,        // VueRouter 类（必需）
  Vuex: Vuex,                  // Vuex 类（必需）
  createPersistedState: createPersistedState, // vuex-persistedstate 插件（必需）
  componentMap: componentMap   // 业务组件映射（可选）
})

其他方法

// 初始化 HTTP 配置
AdminFramework.initHttp(config, store)

// 创建路由实例
AdminFramework.createRouter(Router, components, customRoutes, ViewUI, homeName)

// 创建 Store 实例
AdminFramework.createStore(Vuex, customModules, createPersistedState)

// 添加组件映射
AdminFramework.addComponentMap(customMap)

工具库使用

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.$funTool.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_high/sys_menu - 菜单管理
• ✅ system_high/sys_control - 控制器管理
• ✅ system_high/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.$funTool.downloadFile(response, 'file.csv')
    }
  }
}

📝 业务开发示例

创建业务页面

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