zc/admin_core

Fork 0

Files

张成 2e1cd65b07 init

2025-10-08 15:10:33 +08:00

17 KiB

Raw Blame History

Admin Framework 完整使用文档

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

📑 目录

特性
快速开始
完整使用示例
API 文档
系统页面和 API
开发指南
常见问题

✨ 特性

✅ 系统管理页面（sys 开头的所有页面和功能）
✅ 系统 API（system 和 system_high 所有 API）
✅ 全局组件（Tables、Editor、Upload 等）
✅ 布局组件（Main、ParentView）
✅ 登录和错误页面（Login、401、404、500）
✅ 用户登录和权限管理
✅ 动态路由管理
✅ 工具库（HTTP、日期、Token、Cookie 等）
✅ Vuex 状态管理
✅ 路由守卫

🚀 快速开始

一、打包框架

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. 框架已包含的内容

无需从原项目复制：

✅ 已包含：

所有系统页面（system、system_high）
所有系统 API（system、system_high）
所有全局组件（Tables、Editor、Upload 等）
布局组件（Main、ParentView）
登录和错误页面
工具库和 Store 模块

只需准备：

├── config/index.js           # 配置文件（根据你的项目修改）
└── App.vue                   # 应用根组件

2. 创建 main.js（只需 10 行代码！）

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(AdminFramework, {
  config,
  ViewUI,
  VueRouter,
  Vuex,
  createPersistedState
})

// 创建 Vue 实例
window.rootVue = new Vue({
  el: '#app',
  router: AdminFramework.router,  // 使用框架自动创建的 router
  store: AdminFramework.store,    // 使用框架自动创建的 store
  render: h => h(App),
  mounted() {
    AdminFramework.uiTool.setRem()
    this.$store.dispatch('user/setAuthorityMenus', {
      Main: AdminFramework.Main,
      ParentView: AdminFramework.ParentView,
      Page404: AdminFramework.Page404
    })
  }
})

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

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

✅ 注册 ViewUI
✅ 创建 Store（包含用户、应用模块）
✅ 创建 Router（包含所有基础路由和动态路由）
✅ 初始化 HTTP
✅ 设置 API 服务
✅ 注册全局组件
✅ 配置路由守卫

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 from '@/utils/admin-framework.js'

class ProductServer {
  async getList(params) {
    return await http.http.get('/product/list', params)
  }
  
  async save(data) {
    return await http.http.post('/product/save', data)
  }
  
  async delete(id) {
    return await http.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
})

参数说明：

config: 项目配置对象
ViewUI: ViewUI 实例
VueRouter: VueRouter 类
Vuex: Vuex 类
createPersistedState: vuex-persistedstate 插件

initHttp(config, store)

初始化 HTTP 配置

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

setUserServer(userServer)

设置用户服务实例

AdminFramework.setUserServer(userServer)

setParamSetupServer(paramSetupServer)

设置参数设置服务实例

AdminFramework.setParamSetupServer(paramSetupServer)

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

已包含的系统页面

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

system 目录页面

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

system_high 目录页面

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

在路由中使用

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

const routes = [
  {
    path: '/system/user',
    name: 'sys_user',
    component: SysUser
  },
  {
    path: '/system/role',
    name: 'sys_role',
    component: SysRole
  },
  {
    path: '/system_high/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_high 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: 如何扩展 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、组件都已在框架中，无需复制！

📦 完整的项目结构示例

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

📝 版本信息

当前版本: 1.0.0

更新日志:

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

📄 许可证

MIT License

💬 技术支持

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

🎯 快速参考

最小化代码示例（10行）

import Vue from 'vue'
import AdminFramework from './libs/admin-framework.js'
import App from './App.vue'
import config from './config'

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

祝开发愉快！ 🎉

17 KiB Raw Blame History Unescape Escape

Admin Framework 完整使用文档

📑 目录

✨ 特性

🚀 快速开始

一、打包框架

1. 进入框架目录

2. 安装依赖

3. 打包

二、在新项目中使用

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

方式二：作为 npm 包使用

三、最小化使用示例

1. 框架已包含的内容

2. 创建 main.js（只需 10 行代码！）

3. 安装依赖

4. 运行项目

📖 完整使用示例

步骤 1: 准备项目结构

步骤 2: 创建配置文件

步骤 3: 创建 App.vue

步骤 4: 开发业务功能

创建业务页面

创建业务 API

📚 API 文档

框架实例方法

install(Vue, options)

initHttp(config, store)

setUserServer(userServer)

setParamSetupServer(paramSetupServer)

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_high 目录页面

在路由中使用

已包含的系统 API

system API

system_high API

全局组件

🛠️ 开发指南

开发模式

生产构建

目录结构

依赖说明

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

dependencies

❓ 常见问题

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

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

Q3: 如何自定义配置？

Q4: 如何添加业务路由？

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

Q6: 如何扩展 Store 模块？

Q7: 如何使用登录功能？

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

📦 完整的项目结构示例

📝 版本信息

📄 许可证

💬 技术支持

🎯 快速参考

最小化代码示例（10行）

常用API速查

17 KiB

Raw Blame History