zc/admin_core

Fork 0

Files

张成 970edeb759 1

2025-10-28 16:11:23 +08:00

30 KiB

Raw Blame History

Admin Framework 完整使用文档

通用后台管理系统框架 - 包含系统功能、登录、路由管理、布局等核心功能

🎯 Demo 项目

📦 已提供完整的示例项目：demo-project/

一个开箱即用的完整示例，包含：

✅ 框架集成配置
✅ 登录页面
✅ 主页欢迎页
✅ 业务页面示例（产品列表 CRUD）
✅ Webpack 配置
✅ 详细使用说明

快速体验：

cd demo-project
npm install
npm run dev

详细说明：demo-project/README.md

✨ 特性

✅ 极简 API - 只需调用 createApp() 即可完成所有初始化
✅ 模块化设计 - 组件、路由、状态管理等功能按模块组织
✅ 主页组件（欢迎页面，自动显示系统标题）
✅ 系统管理页面（sys 开头的所有页面和功能）
✅ 系统 API（system 和 system 所有 API）
✅ 全局组件（Tables、Editor、Upload、FieldRenderer 等）
✅ 布局组件（Main、ParentView）
✅ 文件下载（支持 CSV 等格式，自动处理换行符）
✅ 登录和错误页面（Login、401、404、500）
✅ 用户登录和权限管理
✅ 动态路由管理
✅ 工具库（HTTP、日期、Token、Cookie 等）
✅ Vuex 状态管理
✅ 路由守卫
✅ 内置样式（base.less、animate.css、ivewExpand.less、iconfont）

🚀 快速开始

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

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

# 1. 进入 demo 项目
cd demo-project

# 2. 安装依赖
npm install

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

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

/login - 登录页面
/home - 主页
/business/product - 业务示例页面

详细说明：查看 demo-project/README.md 和 demo-project/INSTALL.md

🔧 方式二：手动集成到项目

一、打包框架

1. 进入框架目录

cd admin-framework

2. 安装依赖

npm install

3. 打包

npm run build

打包完成后，会在 dist 目录生成 admin-framework.js 文件（约 200-300KB）。

二、在新项目中使用

方式一：直接复制打包文件（推荐）

将 dist/admin-framework.js 复制到新项目的 src/libs/ 目录
在 main.js 中引入：

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

方式二：作为 npm 包使用

在 admin-framework 目录执行：

npm link

npm link admin-framework

在 main.js 中引入：

import AdminFramework from 'admin-framework'

三、最小化使用示例

1. 框架已包含的内容

无需从原项目复制：

✅ 已包含：

主页组件（HomePage - 欢迎页面，显示系统标题）
所有系统页面（system、system）
所有系统 API（system、system）
所有全局组件（Tables、Editor、Upload、FieldRenderer 等）
布局组件（Main、ParentView）
登录和错误页面
工具库和 Store 模块
所有样式文件（base.less、animate.css、ivewExpand.less）
字体图标文件（iconfont）

只需准备：

├── App.vue                   # 应用根组件（可选）

2. 创建 main.js（新版本 - 只需 8 行代码！）

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')

2.1 传统方式（兼容旧版本）

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 实例
window.rootVue = 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)

就这么简单！ 框架会自动：

✅ 注册 ViewUI（自动调用 Vue.use(ViewUI)）
✅ 注册 VueRouter（自动调用 Vue.use(VueRouter)）
✅ 注册 Vuex（自动调用 Vue.use(Vuex)）
✅ 创建 Store（包含用户、应用模块）
✅ 创建 Router（包含所有基础路由和动态路由）
✅ 初始化 HTTP
✅ 注册全局组件
✅ 配置路由守卫
✅ 支持自定义首页组件（通过 HomePage 参数传入）

3. 安装依赖

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

4. 运行项目

npm run dev

📖 完整使用示例

步骤 1: 准备项目结构

your-project/
├── src/
│   ├── config/
│   │   └── index.js
│   ├── libs/
│   │   └── admin-framework.js  ← 框架文件
│   ├── App.vue
│   └── main.js
├── package.json
└── webpack.config.js

步骤 2: 创建配置文件

在 src/config/index.js 中：

module.exports = {
  title: '你的系统名称',
  homeName: '首页',
  apiUrl: 'http://localhost:9090/admin_api/',
  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/'
  }
}

步骤 3: 创建 App.vue

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

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

步骤 4: 开发业务功能

创建业务页面

<!-- src/view/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' }
      ]
    }
  },
  async mounted() {
    await this.loadData()
  },
  methods: {
    async loadData() {
      // 使用框架提供的 http 工具
      const res = await this.$http.get('/product/list', { page: 1 })
      this.list = res.data
    }
  }
}
</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 })
  }
}

export default new ProductServer()

📚 API 文档

框架实例方法

install(Vue, options)

安装 Vue 插件

Vue.use(AdminFramework, {
  config: yourConfig,
  ViewUI: ViewUI,
  VueRouter: VueRouter,
  Vuex: Vuex,
  createPersistedState: createPersistedState,
  HomePage: HomePage  // 可选：自定义首页组件
})

参数说明：

config: 项目配置对象（必需）
ViewUI: ViewUI 实例（必需）
VueRouter: VueRouter 类（必需）
Vuex: Vuex 类（必需）
createPersistedState: vuex-persistedstate 插件（必需）
HomePage: 自定义首页组件（可选，不传则使用框架内置组件）

initHttp(config, store)

初始化 HTTP 配置

AdminFramework.initHttp({
  apiUrl: 'http://localhost:9090/admin_api/',
  timeout: 300000
}, store)

createRouter(Router, components, customRoutes, ViewUI, homeName)

创建路由实例

const router = AdminFramework.createRouter(
  VueRouter,
  { LoginPage, Page401, Page404, Page500 },
  customRoutes,  // 自定义业务路由
  ViewUI,
  'home'
)

createStore(Vuex, customModules, createPersistedState)

创建 Store 实例

const store = AdminFramework.createStore(
  Vuex,
  { business: businessModule },  // 自定义业务模块
  createPersistedState
)

getRoutes(components)

获取动态路由

const mainRoutes = AdminFramework.getRoutes({
  Main,
  ParentView,
  Page404
})

registerComponents(Vue, components)

注册全局组件

AdminFramework.registerComponents(Vue, {
  'my-component': MyComponent
})

工具库

http - HTTP 请求工具

// GET 请求
AdminFramework.http.get('/api/users', { page: 1 })

// POST 请求
AdminFramework.http.post('/api/users', { name: 'test' })

// 文件导出
AdminFramework.http.fileExport('/api/export', { type: 'excel' })

在组件中使用：

export default {
  async mounted() {
    const res = await this.$http.get('/api/users')
  }
}

util - 工具函数

// Token 管理
AdminFramework.util.setToken(token)
AdminFramework.util.getToken()

// 路由工具
AdminFramework.util.getBreadCrumbList(route, homeRoute)
AdminFramework.util.getHomeRoute(routes, 'home')

在组件中使用：

export default {
  methods: {
    getToken() {
      return this.$util.getToken()
    }
  }
}

tools - 功能工具

// 日期格式化
AdminFramework.tools.formatDate(new Date(), 'YYYY-MM-DD HH:mm:ss')

// UUID 生成
AdminFramework.tools.generateUUID()

// Cookie 操作
AdminFramework.tools.setCookie('name', 'value')
AdminFramework.tools.getCookie('name')

在组件中使用：

export default {
  methods: {
    formatDate() {
      return this.$tools.formatDate(new Date(), 'YYYY-MM-DD')
    }
  }
}

uiTool - UI 工具

// 设置响应式字体
AdminFramework.uiTool.setRem()

// 删除确认
AdminFramework.uiTool.delConfirm(() => {
  // 删除逻辑
})

// 树形转换
AdminFramework.uiTool.transformTree(treeData)

在组件中使用：

export default {
  methods: {
    handleDelete() {
      this.$uiTool.delConfirm(() => {
        // 执行删除
      })
    }
  }
}

Store 模块

user 模块

// 登录
this.$store.dispatch('user/handleLogin', {
  userFrom: { username, password },
  Main,
  ParentView,
  Page404
})

// 登出
this.$store.dispatch('user/handleLogOut')

// 设置权限菜单
this.$store.dispatch('user/setAuthorityMenus', {
  Main,
  ParentView,
  Page404
})

// 获取用户信息
this.$store.getters['user/userName']
this.$store.state.user.token

app 模块

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

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

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

🗂️ 系统页面和 API

已包含的系统页面

框架已内置所有系统管理页面，可直接从框架导入使用：

主页

import {
  HomePage         // 主页欢迎页面（显示系统标题）
} from 'admin-framework'

system 目录页面

import {
  SysLog,          // 系统日志管理
  SysParamSetup,   // 参数设置
  SysRole,         // 角色管理
  SysUser          // 用户管理
} from 'admin-framework'

system 目录页面

import {
  SysControl,      // 控制器管理
  SysMenu,         // 菜单管理
  SysTitle         // 系统标题设置
} from 'admin-framework'

在路由中使用

import { HomePage, SysUser, SysRole, SysMenu } from 'admin-framework'

const routes = [
  {
    path: '/home',
    name: 'home',
    component: HomePage  // 框架自动注册，也可手动使用
  },
  {
    path: '/system/user',
    name: 'sys_user',
    component: SysUser
  },
  {
    path: '/system/role',
    name: 'sys_role',
    component: SysRole
  },
  {
    path: '/system/menu',
    name: 'sys_menu',
    component: SysMenu
  }
]

已包含的系统 API

system API

import { systemApi } from 'admin-framework'

// 使用示例
const {
  userServer,
  roleServer,
  sysLogServe,
  fileServe,
  // ... 其他 API
} = systemApi

// 调用 API
const users = await userServer.getList({ page: 1 })
const roles = await roleServer.getList()

system API

import { systemHighApi } from 'admin-framework'

// 使用示例
const {
  menuServer,
  paramSetupServer,
  modelServer,
  // ... 其他 API
} = systemHighApi

// 调用 API
const menus = await menuServer.getTree()
const params = await paramSetupServer.getOne('sys_title')

全局组件

框架已包含所有全局组件，打包后会自动注册：

<template>
  <div>
    <Tables :columns="columns" :data="data" />
    <Editor v-model="content" />
    <UploadSingle v-model="fileUrl" />
    <TreeGrid :data="treeData" />
  </div>
</template>

🛠️ 开发指南

开发模式

npm run dev

生产构建

npm run build

目录结构

admin-framework/
├── src/
│   ├── utils/              # 工具库
│   │   ├── tools.js      # 功能工具
│   │   ├── http.js         # HTTP 工具
│   │   ├── tools.js        # 通用工具
│   │   ├── uiTool.js       # UI 工具
│   │   └── util.js         # 工具函数
│   ├── store/              # Vuex 模块
│   │   ├── user.js         # 用户模块
│   │   ├── app.js          # 应用模块
│   │   └── index.js        # 导出
│   ├── router/             # 路由配置
│   │   └── index.js        # 路由配置
│   └── index.js            # 入口文件
├── dist/                   # 打包输出
│   └── admin-framework.js  # 打包后的文件
├── webpack.config.js       # Webpack 配置
├── package.json            # 依赖配置
└── README.md              # 说明文档

依赖说明

peerDependencies（需要在使用项目中安装）

vue: ^2.6.0
vue-router: ^3.0.0
vuex: ^3.0.0
view-design: ^4.0.0
axios: ^0.21.0

dependencies

dayjs: ^1.10.0
js-cookie: ^2.2.1
vuex-persistedstate: ^4.0.0

❓ 常见问题

Q1: 打包后文件太大怎么办？

A: 框架已经将 Vue、VueRouter、Vuex、ViewUI、Axios 设置为外部依赖，不会打包进去。确保在项目中单独安装这些依赖。

Q2: 如何只使用部分功能？

A: 可以按需导入：

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

Q3: 如何自定义配置？

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

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

Q4: 如何添加业务路由？

A: 在创建路由时传入：

const businessRoutes = [
  {
    path: '/business/product',
    component: () => import('@/view/business/product.vue')
  }
]

const router = AdminFramework.createRouter(
  VueRouter,
  { LoginPage, Page401, Page404, Page500 },
  businessRoutes,  // ← 传入业务路由
  ViewUI
)

Q5: 如何自定义路由守卫？

A: 你可以在创建路由后添加自己的守卫：

const router = AdminFramework.createRouter(...)

router.beforeEach((to, from, next) => {
  // 你的自定义逻辑
  next()
})

Q6: 如何使用文件下载功能？

A: 框架提供了便捷的文件下载方法：

// 在 Vue 组件中使用
export default {
  methods: {
    exportData() {
      // 调用 API 获取数据
      this.$http.fileExport('/api/export', params).then(res => {
        // 下载文件（自动处理换行符）
        this.$uiTool.downloadFile(res, '数据导出.csv')
        this.$Message.success('导出成功！')
      }).catch(error => {
        this.$Message.error('导出失败：' + error.message)
      })
    }
  }
}

特性：

✅ 自动处理 CSV 换行符
✅ 支持多种文件格式
✅ 浏览器兼容性好
✅ 自动清理临时 URL 对象

Q7: 如何扩展 Store 模块？

A: 在创建 Store 时传入自定义模块：

const store = AdminFramework.createStore(Vuex, {
  myModule: {
    namespaced: true,
    state: { ... },
    mutations: { ... },
    actions: { ... }
  }
})

Q7: 如何使用登录功能？

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' })
    }
  }
}

Q8: 需要复制哪些文件到新项目？

A: 框架已包含所有系统功能，只需准备：

config/index.js - 配置文件
App.vue - 应用根组件
main.js - 入口文件

其他所有系统页面、API、组件都已在框架中，无需复制！

Q9: 报错 `must call Vue.use(Vuex) before creating a store instance` 怎么办？

A: 这个问题已在框架 v1.0.0+ 中修复！

如果你使用的是旧版本框架，请重新构建：

cd admin-framework
npm run build

然后将新的 dist/admin-framework.js 复制到项目中替换旧文件。

新版本框架会自动调用 Vue.use(Vuex) 和 Vue.use(VueRouter)，无需手动注册！

Q13: `this.$store.dispatch` 报错怎么办？

A: 常见原因和解决方案：

1. Store 未正确挂载

确保在创建 Vue 实例时使用了框架的 store：

new Vue({
  el: '#app',
  router: AdminFramework.router,
  store: AdminFramework.store,  // ✅ 必须挂载 store
  render: h => h(App)
})

2. 命名空间路径错误

框架的 store 模块都使用了 namespaced: true，必须带上模块名：

// ❌ 错误 - 缺少命名空间
this.$store.dispatch('setAuthorityMenus', data)

// ✅ 正确 - 带上模块名 user/
this.$store.dispatch('user/setAuthorityMenus', data)

// ✅ 正确 - app 模块
this.$store.dispatch('app/getSysTitle', { defaultTitle: '系统' })

3. Store 在 setup/install 时未创建

确保在 Vue.use() 时传入了 Vuex：

// ✅ 正确 - 框架会自动创建 store
Vue.use(AdminFramework, {
  config,
  ViewUI,
  VueRouter,
  Vuex,  // ✅ 必须传入 Vuex
  createPersistedState
})

4. 可用的 Store Actions

user 模块（需要加 user/ 前缀）：

user/setAuthorityMenus - 设置权限菜单
user/handleLogin - 处理登录
user/handleLogOut - 处理登出

app 模块（需要加 app/ 前缀）：

app/getSysTitle - 获取系统标题和 Logo

完整示例：

export default {
  mounted() {
    // 设置权限菜单
    this.$store.dispatch('user/setAuthorityMenus', {
      Main: AdminFramework.Main,
      ParentView: AdminFramework.ParentView,
      Page404: AdminFramework.Page404
    })
    
    // 获取系统标题
    this.$store.dispatch('app/getSysTitle', {
      defaultTitle: '智能代码平台',
      defaultLogo: ''
    })
  },
  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' })
    },
    logout() {
      // 处理登出
      this.$store.dispatch('user/handleLogOut')
    }
  }
}

Q11: 主页 HomePage 组件说明

A: 框架支持两种方式使用首页组件：使用内置组件或传入自定义组件。

方式一：使用框架内置的主页组件（默认）

默认主页组件：

<!-- 已内置在框架中 -->
<template>
  <div class="content-view">
    <h1 class="home-title">
      <span class="hy">欢迎登陆， </span>
      {{ sysFormModel.title }}
    </h1>
  </div>
</template>

特性：

✅ 自动从 Vuex Store 获取系统标题（app/sysFormModel）
✅ 优雅的欢迎页面样式
✅ 无需额外配置

使用方式：

// 不传入 HomePage，框架会使用内置组件
Vue.use(AdminFramework, {
  config,
  ViewUI,
  VueRouter,
  Vuex,
  createPersistedState
})

方式二：传入自定义首页组件（推荐）

创建自定义首页组件：

<!-- src/views/home/index.vue -->
<template>
  <div class="custom-home">
    <h1>欢迎使用 {{ sysFormModel.title }}</h1>
    <p>这是自定义的首页内容</p>
    <!-- 你的自定义内容 -->
  </div>
</template>

<script>
import { mapGetters } from 'vuex'

export default {
  computed: {
    ...mapGetters({
      sysFormModel: 'app/sysFormModel'
    })
  }
}
</script>

<style scoped>
.custom-home {
  padding: 20px;
}
</style>

传入自定义组件：

import HomePage from './views/home/index.vue'

Vue.use(AdminFramework, {
  config,
  ViewUI,
  VueRouter,
  Vuex,
  createPersistedState,
  HomePage  // ✅ 传入自定义首页组件
})

首页路由配置

重要说明：

⚠️ 首页路由完全由后端权限菜单返回
⚠️ 后端必须返回 path: '/home' 的菜单配置
⚠️ 后端返回的 component 字段会映射到实际组件

后端菜单配置示例：

{
  "id": 1,
  "name": "首页",
  "path": "/home",
  "component": "home/index",  // 映射到 src/views/home/index.vue
  "parent_id": 0,
  "type": "页面",
  "is_show_menu": 1,
  "icon": "md-home",
  "sort": 1
}

组件映射规则：

// 后端返回: "component": "home/index"
// 实际加载: src/views/home/index.vue

// 后端返回: "component": "system/user"
// 实际加载: src/views/system/user.vue

降级方案

如果后端接口失败，框架会使用默认菜单配置（src/config/menuConfig.js）：

export const defaultMenus = [
  {
    id: 1,
    name: '首页',
    path: '/home',
    component: 'home/index',
    parent_id: 0,
    type: '页面',
    is_show_menu: 1,
    icon: 'md-home',
    sort: 1
  },
  // ... 其他菜单
]

直接使用 HomePage 组件

// 获取框架内置的 HomePage 组件
import AdminFramework from './libs/admin-framework.js'
const HomePage = AdminFramework.HomePage

// 在路由中使用
const routes = [
  {
    path: '/home',
    name: 'home',
    component: HomePage
  }
]

最佳实践

推荐做法：

✅ 创建自定义首页组件 src/views/home/index.vue
✅ 在 Vue.use() 时传入 HomePage 参数
✅ 确保后端返回首页菜单配置
✅ 在 defaultMenus 中包含首页配置作为降级方案

完整示例：

// main.js
import HomePage from './views/home/index.vue'

Vue.use(AdminFramework, {
  config,
  ViewUI,
  VueRouter,
  Vuex,
  createPersistedState,
  HomePage  // 传入自定义首页组件
})

new Vue({
  el: '#app',
  router: AdminFramework.router,
  store: AdminFramework.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 管理系统'
    }
  }
})

Q12: 需要单独引入样式文件吗？

A: 不需要！框架已内置所有样式。

框架打包时已自动包含以下样式：

✅ base.less - 基础样式
✅ animate.css - 动画样式
✅ ivewExpand.less - ViewUI 扩展样式
✅ iconfont.css - 字体图标样式

无需在项目中：

// ❌ 不需要这些导入
import 'admin-framework/assets/css/base.less'
import 'admin-framework/assets/css/animate.css'

只需引入框架即可：

// ✅ 样式已自动包含
import AdminFramework from './libs/admin-framework.js'
Vue.use(AdminFramework, { ... })

框架使用时样式会自动注入到页面中，无需任何额外配置！

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

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

问题原因：后端权限菜单接口返回的组件路径（如 ball/games.vue）需要映射到实际组件。

解决方案：

方式一：在 Vue.use 时配置（推荐）

// 1. 导入业务组件
import GamesComponent from './views/ball/games.vue'
import PayOrdersComponent from './views/order/pay_orders.vue'

// 2. 配置映射
Vue.use(AdminFramework, {
  config,
  ViewUI,
  VueRouter,
  Vuex,
  createPersistedState,
  // ✅ 配置组件映射
  componentMap: {
    'ball/games': GamesComponent,
    'order/pay_orders': PayOrdersComponent
    // 根据权限菜单接口的 component 字段添加...
  }
})

方式二：使用 addComponentMap 方法

// 先使用框架
Vue.use(AdminFramework, { config, ViewUI, VueRouter, Vuex, createPersistedState })

// 然后添加映射
AdminFramework.addComponentMap({
  'ball/games': GamesComponent,
  'order/pay_orders': PayOrdersComponent
})

框架已自动映射的系统组件

以下组件无需配置，框架已自动映射：

✅ home/index.vue - 主页
✅ system/sys_user.vue - 用户管理
✅ system/sys_role.vue - 角色管理
✅ system/sys_log.vue - 日志管理
✅ system/sys_param_setup.vue - 参数设置
✅ system/sys_menu.vue - 菜单管理
✅ system/sys_control.vue - 控制器管理
✅ system/sys_title.vue - 系统标题设置

配置技巧

路径规则：

后端返回："component": "ball/games.vue"
配置映射：'ball/games': GamesComponent（不需要 .vue 后缀）
框架会自动处理带和不带 .vue 的路径

完整示例：

// 根据你的权限菜单接口，导入所有可能用到的组件
import GamesComponent from './views/ball/games.vue'
import WchUsersComponent from './views/ball/wch_users.vue'
import PayOrdersComponent from './views/order/pay_orders.vue'

Vue.use(AdminFramework, {
  config,
  ViewUI,
  VueRouter,
  Vuex,
  createPersistedState,
  componentMap: {
    'ball/games': GamesComponent,
    'ball/wch_users': WchUsersComponent,
    'order/pay_orders': PayOrdersComponent
  }
})

未映射的组件：会显示友好提示：页面组件未加载: xxx.vue，请在项目中创建此组件或在组件映射表中注册

📦 完整的项目结构示例

your-project/
├── src/
│   ├── api/
│   │   └── business/           # 你的业务 API
│   ├── assets/
│   │   └── images/             # 你的业务图片（框架样式已内置）
│   ├── config/
│   │   └── index.js            # 配置文件
│   ├── libs/
│   │   └── admin-framework.js  # 框架文件（已包含所有样式）
│   ├── view/
│   │   └── business/           # 你的业务页面
│   ├── App.vue
│   └── main.js
├── package.json
└── webpack.config.js

说明：

框架已内置所有系统样式，无需创建 assets/css 目录
只需要准备你自己的业务图片和业务样式（如有需要）

📝 版本信息

当前版本: 1.0.0

更新日志:

v1.0.0 - 初始版本，包含所有核心功能

📄 许可证

MIT License

💬 技术支持

如有问题，请查看本文档或联系开发团队。

🎯 快速参考

最小化代码示例

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'

// 框架会自动调用 Vue.use(ViewUI/VueRouter/Vuex)
Vue.use(AdminFramework, { config, ViewUI, VueRouter, Vuex, createPersistedState })

new Vue({
  el: '#app',
  router: AdminFramework.router,  // 框架自动创建
  store: AdminFramework.store,    // 框架自动创建
  render: h => h(App)
})

常用API速查

// HTTP请求
this.$http.get(url, params)
this.$http.post(url, data)

// Token操作
this.$util.setToken(token)
this.$util.getToken()

// 日期格式化
this.$tools.formatDate(date, 'YYYY-MM-DD')

// 删除确认
this.$uiTool.delConfirm(() => { /* 删除逻辑 */ })

// 登录
this.$store.dispatch('user/handleLogin', { userFrom, Main, ParentView, Page404 })

// 登出
this.$store.dispatch('user/handleLogOut')

祝开发愉快！ 🎉

30 KiB Raw Blame History Unescape Escape

Admin Framework 完整使用文档

🎯 Demo 项目

📑 目录

✨ 特性

🚀 快速开始

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

🔧 方式二：手动集成到项目

一、打包框架

1. 进入框架目录

2. 安装依赖

3. 打包

二、在新项目中使用

方式一：直接复制打包文件（推荐）

方式二：作为 npm 包使用

三、最小化使用示例

1. 框架已包含的内容

2. 创建 main.js（新版本 - 只需 8 行代码！）

2.1 传统方式（兼容旧版本）

3. 安装依赖

4. 运行项目

📖 完整使用示例

步骤 1: 准备项目结构

步骤 2: 创建配置文件

步骤 3: 创建 App.vue

步骤 4: 开发业务功能

创建业务页面

创建业务 API

📚 API 文档

框架实例方法

install(Vue, options)

initHttp(config, store)

createRouter(Router, components, customRoutes, ViewUI, homeName)

createStore(Vuex, customModules, createPersistedState)

getRoutes(components)

registerComponents(Vue, components)

工具库

http - HTTP 请求工具

util - 工具函数

tools - 功能工具

uiTool - UI 工具

Store 模块

user 模块

app 模块

🗂️ 系统页面和 API

已包含的系统页面

主页

system 目录页面

system 目录页面

在路由中使用

已包含的系统 API

system API

system API

全局组件

🛠️ 开发指南

开发模式

生产构建

目录结构

依赖说明

peerDependencies（需要在使用项目中安装）

dependencies

❓ 常见问题

Q1: 打包后文件太大怎么办？

Q2: 如何只使用部分功能？

Q3: 如何自定义配置？

Q4: 如何添加业务路由？

Q5: 如何自定义路由守卫？

Q6: 如何使用文件下载功能？

Q7: 如何扩展 Store 模块？

Q7: 如何使用登录功能？

Q8: 需要复制哪些文件到新项目？

Q9: 报错 must call Vue.use(Vuex) before creating a store instance 怎么办？

Q13: this.$store.dispatch 报错怎么办？

Q11: 主页 HomePage 组件说明

方式一：使用框架内置的主页组件（默认）

方式二：传入自定义首页组件（推荐）

首页路由配置

降级方案

直接使用 HomePage 组件

最佳实践

30 KiB

Raw Blame History

Q9: 报错 `must call Vue.use(Vuex) before creating a store instance` 怎么办？

Q13: `this.$store.dispatch` 报错怎么办？