zc/admin_core

Fork 0

Files

张成 463d7921c1 1

2025-11-26 17:50:14 +08:00

18 KiB

Raw Blame History

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 项目，可以直接运行查看效果：

# 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 对象

🎨 全局组件使用

FloatPanel - 浮动面板组件

FloatPanel 是一个浮动在父窗体上的面板组件，类似于抽屉效果，常用于详情展示、表单编辑等场景。

基本使用：

<template>
  <div>
    <Button @click="showPanel">打开浮动面板</Button>
    
    <FloatPanel
      ref="floatPanel"
      title="详情面板"
      position="right"
      :show-back="true"
      back-text="返回"
      @back="handleBack"
    >
      <div>这里是面板内容</div>
    </FloatPanel>
  </div>
</template>

<script>
export default {
  methods: {
    showPanel() {
      // 通过 ref 调用 show 方法显示面板
      this.$refs.floatPanel.show()
    },
    hidePanel() {
      // 通过 ref 调用 hide 方法隐藏面板
      this.$refs.floatPanel.hide()
    },
    handleBack() {
      console.log('返回按钮被点击')
      this.hidePanel()
    }
  }
}
</script>

属性说明：

属性	类型	默认值	说明
`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: 居中显示，带缩放动画

完整示例：

<template>
  <div>
    <Button @click="openDetailPanel">查看详情</Button>
    
    <FloatPanel
      ref="detailPanel"
      title="用户详情"
      position="right"
      :show-back="true"
      :show-close="true"
      back-text="返回"
      @back="handleBack"
    >
      <template #header-right>
        <Button type="primary" @click="handleSave">保存</Button>
      </template>
      
      <div class="detail-content">
        <Form :model="formData" :label-width="100">
          <FormItem label="用户名">
            <Input v-model="formData.username" />
          </FormItem>
          <FormItem label="邮箱">
            <Input v-model="formData.email" />
          </FormItem>
        </Form>
      </div>
    </FloatPanel>
  </div>
</template>

<script>
export default {
  data() {
    return {
      formData: {
        username: '',
        email: ''
      }
    }
  },
  methods: {
    openDetailPanel() {
      this.$refs.detailPanel.show()
    },
    handleBack() {
      this.$refs.detailPanel.hide()
    },
    handleSave() {
      // 保存逻辑
      console.log('保存数据', this.formData)
      this.$Message.success('保存成功')
      this.$refs.detailPanel.hide()
    }
  }
}
</script>

特性说明：

✅ 基于父元素定位，不会遮挡菜单
✅ 宽度和高度默认 100%，占满父容器
✅ 无遮罩背景，完全浮在父页面上
✅ 路由切换或组件销毁时自动关闭
✅ 支持多种位置和动画效果
✅ 支持自定义头部右侧内容

📝 业务开发示例

创建业务页面

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

18 KiB Raw Blame History Unescape Escape