Admin Framework（admin-framework）

基于 Vue 2、Vue Router 3、Vuex 3、View Design（iView 4） 的后台管理框架：登录、布局、动态菜单与路由、权限、HTTP 封装、系统管理页面等。

---

1. 依赖与环境

1.1 Peer 依赖（由业务项目安装）

框架不打包以下依赖，需在宿主项目中安装并与框架版本兼容：

包	说明
vue ^2.6	运行时
vue-router ^3	路由
vuex ^3	状态
view-design ^4	UI 组件库
axios	HTTP（与框架内封装配合）

1.2 构建产物（dist/）

文件	说明
admin-framework.js	UMD，Terser 压缩，对外默认导出为框架单例；浏览器中为 window.AdminFramework，也可由 Webpack 等从该文件解析 import

在项目根目录执行：

npm run build

---

2. 引入方式

2.1 与 Webpack / Vue CLI 等业务工程配合

先安装 peer 依赖，将构建好的 dist/admin-framework.js 拷贝到业务项目或通过路径引用；在入口中：

import AdminFramework from './vendor/admin-framework.js'
// 若已将包发布到 npm 且 package.json 的 main 指向 dist，则：
// import AdminFramework from 'admin-framework'

打包器需将 vue、vue-router、vuex、view-design、axios 作为外部依赖或正常解析（与 UMD 的 externals 一致）。

2.2 页面中通过 <script> 引入

按顺序引入 Vue、VueRouter、Vuex、View Design、axios 的 UMD 脚本，再引入 admin-framework.js，使用全局 AdminFramework 调用 createApp 等 API。

---

3. 核心 API：一键创建应用

3.1 AdminFramework.createApp(config)

创建并配置 Vue 根实例：注册插件、全局属性、componentMap、Store、Router、布局等。返回 Vue 实例，需自行 $mount。

config 常用字段：

字段	类型	说明
title	string	站点标题；未登录或接口失败时用作默认 document.title
apiUrl	string	后端 API 根地址（必填，用于 http baseURL）
uploadUrl	string	可选；不传时由 apiUrl 自动推导为 apiUrl + 'upload' 或 apiUrl + '/upload'
componentMap	object	动态路由组件映射，见 §7
HomePage	Vue 组件	可选，自定义首页；默认框架内置欢迎页
onReady	function	可选，根实例 created 末尾调用，this 为 Vue 根实例

示例：

import AdminFramework from 'admin-framework'
import componentMap from './router/component-map.js'

const app = AdminFramework.createApp({
  title: '某某管理系统',
  apiUrl: 'https://api.example.com/admin_api/',
  componentMap,
  HomePage: null,
  onReady() {
    console.log('框架与路由就绪', this.$route.path)
  }
})

app.$mount('#app')

---

4. 框架实例（AdminFramework / window.framework）

默认导出为单例。构建后也会挂到 window.framework（浏览器环境）。

4.1 常用属性

属性	说明
version	框架版本号字符串
config	最近一次 createApp 传入的配置
store	Vuex Store 实例（createApp 之后可用）
router	Vue Router 实例
HomePage	当前使用的首页组件引用
http	HTTP 封装实例，同 §5
uiTool	UI 与菜单工具类，同 §6
tools	工具方法集合，同 §6.2
systemApi	src/api/system 聚合导出，同 §8
pages	框架内置页面组件集合（登录、错误页、部分系统页等）
components	布局与子组件导出（Main、TreeGrid 等）
storeModules	默认 user、app 模块描述，扩展 Store 时可参考
createBaseRoutes / setupRouterGuards / registerComponents	高级自定义路由/组件时使用

4.2 addComponentMap(customMap)

在运行时追加组件映射（与 createApp 里的 componentMap 语义相同）。

import Games from './views/ball/games.vue'

AdminFramework.addComponentMap({
  'ball/games': Games,
  'ball/games.vue': Games
})

4.3 initHttp(config, store)

若未走 createApp、自行组装 Store 时，可用此方法初始化 http（一般使用 createApp 即可，内部已调用）。

AdminFramework.initHttp(
  { apiUrl: 'https://api.example.com/admin_api/', timeout: 60000 },
  storeInstance
)

---

5. HTTP 模块

通过 this.$http（组件内）或 AdminFramework.http / window.framework.http 访问。

5.1 初始化

由 createApp({ apiUrl, ... }) 自动完成；请求头会带 admin-token（来自 store.state.user.token）。

5.2 约定

• 成功：后端 JSON 需 code === 0，否则走全局错误提示并 reject。
• 401：清空 token，并跳转登录路由（依赖 window.framework.router）。

5.3 方法说明

方法	说明
init(config, store)	合并 timeout 等，绑定 Store
baseUrl()	当前 apiUrl
ImgSrc(src)	拼接图片完整 URL：baseUrl() + src
getHttpInstance(extra)	返回带拦截器的 axios 实例
get(url, params, config)	GET；params 会序列化，Date 会格式化为字符串
post(url, body, config)	POST JSON
postFormData(url, data)	application/x-www-form-urlencoded
fileExport(url, param, filename, is_down)	下载导出；内部可用 uiTool.downloadFile
formatParamete / formatFormDataParam	参数预处理
showLoad / hideLoad / showError	与全局 loading、Message 联动

示例（在 Vue 组件中）：

export default {
  async mounted() {
    try {
      const res = await this.$http.get('/sys_user/index', { page: 1, pageSize: 20 })
      this.list = res.data
    } catch (e) {
      // 已全局提示
    }
  }
}

隐藏 loading：

await this.$http.get('/xxx', { id: 1 }, { hideLoad: true })

---

6. uiTool 模块

通过 this.$uiTool 或 AdminFramework.uiTool 使用（类静态方法）。

方法	说明
setComponentMap(map)	合并组件映射表
getComponent(path)	按路径取组件，path 可带或不带 .vue
downloadFile(res, fileName)	Blob 下载
setRem()	根据屏宽设置根字体（自适应）
getImgSrc(src)	图片地址（同 http 规则）
getBtn(h, options)	Render 函数里生成操作按钮组
getDropdown(h, items)	下拉更多菜单
delConfirm(callback)	删除确认框
showConfirm({ title, content }, callback)	通用确认框
transformTree(list, cb)	扁平列表转树
subTree / menuToRoute / getRoutes	菜单转路由（框架内部与权限菜单配合）

树表示例：

const tree = this.$uiTool.transformTree(flatListFromApi)

---

6.2 通用工具 tools

通过 this.$tools 使用（具体以源码 src/utils/tools.js 为准）。

常用包括：

• Cookie / Token：getToken、setToken、TOKEN_KEY
• 日期：formatDate(val, fmt)（dayjs）
• 数组：forEach、hasOneOf、getUnion、getIntersection
• 对象：objEqual、removeEmptyObject、isNullorEmpty
• 路由/菜单：getBreadCrumbList、getHomeRoute、getMenuByRouter、filterMenu
• 本地存储：localSave、localRead
• 其它：generateUUID、getUrlParam、downStream、scrollTop 等

示例：

if (this.$tools.getToken()) { /* 已登录 */ }

---

7. 组件映射与动态路由

后端菜单里配置的「组件地址」会对应到字符串路径（如 system/sys_user）。框架通过 componentMap 把路径映射到真实 Vue 组件。

在 createApp 中传入：

import SysUser from './views/system/sys_user.vue'

AdminFramework.createApp({
  apiUrl: '...',
  componentMap: {
    'system/sys_user': SysUser,
    'system/sys_user.vue': SysUser
  }
})

未映射的路径会显示占位提示（控制台 warn），便于排查。

框架内置已注册一批系统页（如 system/sys_menu 等），见 src/views/index.js 中 setupComponentMap；业务模块在 componentMap 中追加即可。

---

8. 系统 API（systemApi）

AdminFramework.systemApi 聚合导出 src/api/system 下各 *Server，例如：

导出名	模块文件	典型用途
userServer	userServer.js	登录、用户 CRUD、权限菜单
menuServer	menuServer.js	菜单管理
roleServer / rolePermissionServer	角色与权限
paramSetupServer	系统参数（如站点标题、Logo）
fileServe	文件上传下载
modelServer / tableServer / formServer 等	低代码/表单相关

调用示例：

const { userServer } = AdminFramework.systemApi

async function login() {
  const res = await userServer.login({ username: 'admin', password: '***' })
  if (res.code === 0) {
    // 写入 token、拉菜单等由登录页与 store 配合完成
  }
}

实际请求仍走全局配置的 http（apiUrl、token 头）。

---

9. Vuex（this.$store）

默认模块：

9.1 user（namespaced: true）

项	说明
state	token、userName、authorityMenus、menuList 等
mutations	setToken、setUserName、setAuthorityMenus、setMenuList
actions	setAuthorityMenus：拉取或传入菜单 JSON，生成动态路由并写入 localStorage

登录后刷新菜单示例：

await this.$store.dispatch('user/setAuthorityMenus', {
  Main: this.$framework.components.Main,
  ParentView: this.$framework.components.ParentView,
  Page404: this.$framework.pages.Page404,
  HomePage: this.$framework.HomePage
})

（具体参数以当前框架版本 user 模块为准。）

9.2 app（namespaced: true）

项	说明
state	sysFormModel（标题、Logo）、面包屑、首页路由
actions	getSysTitle：根据参数与接口更新站点标题与 Logo

await this.$store.dispatch('app/getSysTitle', {
  defaultTitle: this.$config.title,
  defaultLogo: ''
})

---

10. 全局 Vue 原型（组件内）

属性	说明
this.$config	createApp 的 config
this.$http	HTTP 封装
this.$tools	工具集
this.$uiTool	UI 工具类
this.$framework	框架单例（同 AdminFramework）

---

11. 内置页面与组件（pages / components）

• 页面：LoginPage、Page401、Page404、Page500 及多套 system/* 管理页（见 src/views/index.js 导出）。
• 布局：Main、ParentView。
• 通用组件：TreeGrid、Tables、editModal、UploadSingle / UploadMultiple、Editor 等（见 src/components/index.js）。

二次封装时可：

const { TreeGrid, Main } = AdminFramework.components

---

12. 调试

• 浏览器中：window.framework、window.rootVue（根实例，在 createApp 创建后设置）。
• 需要未压缩源码调试时，可在业务工程里直接引用框架 src/index.js（需配置好 alias、loader 与 peer 依赖），或使用浏览器「在源映射中黑盒脚本」等能力。

---

13. Demo 项目

demo/ 为示例：请先在仓库根目录执行 npm run build 生成 dist/admin-framework.js，再在 demo 目录安装依赖并执行 npm run dev。demo/src/main.js 通过相对路径引用上级 dist 中的 UMD 包。

---

以上为框架对外使用方式的说明；内部实现以 src/ 源码为准。若升级版本，请同时核对 peer 依赖与本文档中的 API 是否变更。