autoAiWorkSys/_doc/framework_使用文档.md

徽标
工单管理
合并请求
里程碑
探索
zc
/
admin_core
代码
工单
合并请求
Actions
软件包
项目
版本发布
百科
动态
设置
文件
使用说明.md
完整使用文档.md
快速开始.md
.gitignore
README.md
babel.config.js
package-lock.json
package.json
postcss.config.js
webpack.config.js
admin_core
/
_doc
/
使用说明.md

张成
463d7921c1
1
1分钟前
18 KiB
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 项目示例或联系开发团队。

Powered by Gitea
当前版本:
1.24.6
页面:
273ms
模板:
13ms
许可证
API