1
This commit is contained in:
张成
362
demo-project/文档更新说明.md
Normal file
362
demo-project/文档更新说明.md
Normal file
@@ -0,0 +1,362 @@
|
||||
# 文档更新说明
|
||||
|
||||
## 📝 更新内容
|
||||
|
||||
已更新 `完整使用文档.md`，主要修改如下：
|
||||
|
||||
### 1. 移除已废弃的方法
|
||||
|
||||
**移除的方法**：
|
||||
- ❌ `setUserServer(userServer)` - 已废弃
|
||||
- ❌ `setParamSetupServer(paramSetupServer)` - 已废弃
|
||||
|
||||
**原因**：
|
||||
- 框架已改为直接导入 API 模块
|
||||
- 不再使用依赖注入模式
|
||||
- 简化了代码结构
|
||||
|
||||
### 2. 添加 HomePage 参数说明
|
||||
|
||||
**新增内容**：
|
||||
|
||||
#### install 方法参数
|
||||
|
||||
```javascript
|
||||
Vue.use(AdminFramework, {
|
||||
config: yourConfig,
|
||||
ViewUI: ViewUI,
|
||||
VueRouter: VueRouter,
|
||||
Vuex: Vuex,
|
||||
createPersistedState: createPersistedState,
|
||||
HomePage: HomePage // ✅ 新增：可选的自定义首页组件
|
||||
})
|
||||
```
|
||||
|
||||
**参数说明**：
|
||||
- `HomePage`: 自定义首页组件（可选，不传则使用框架内置组件）
|
||||
|
||||
### 3. 完善 Q11: 主页 HomePage 组件说明
|
||||
|
||||
**新增两种使用方式**：
|
||||
|
||||
#### 方式一：使用框架内置的主页组件（默认）
|
||||
|
||||
```javascript
|
||||
// 不传入 HomePage，框架会使用内置组件
|
||||
Vue.use(AdminFramework, {
|
||||
config,
|
||||
ViewUI,
|
||||
VueRouter,
|
||||
Vuex,
|
||||
createPersistedState
|
||||
})
|
||||
```
|
||||
|
||||
**内置组件特性**：
|
||||
- ✅ 自动从 Vuex Store 获取系统标题
|
||||
- ✅ 优雅的欢迎页面样式
|
||||
- ✅ 无需额外配置
|
||||
|
||||
#### 方式二：传入自定义首页组件（推荐）
|
||||
|
||||
**创建自定义首页**：
|
||||
```vue
|
||||
<!-- 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>
|
||||
```
|
||||
|
||||
**传入自定义组件**：
|
||||
```javascript
|
||||
import HomePage from './views/home/index.vue'
|
||||
|
||||
Vue.use(AdminFramework, {
|
||||
config,
|
||||
ViewUI,
|
||||
VueRouter,
|
||||
Vuex,
|
||||
createPersistedState,
|
||||
HomePage // ✅ 传入自定义首页组件
|
||||
})
|
||||
```
|
||||
|
||||
### 4. 重要说明：首页路由配置
|
||||
|
||||
**关键点**：
|
||||
- ⚠️ **首页路由完全由后端权限菜单返回**
|
||||
- ⚠️ 后端必须返回 `path: '/home'` 的菜单配置
|
||||
- ⚠️ 后端返回的 `component` 字段会映射到实际组件
|
||||
|
||||
**后端菜单配置示例**：
|
||||
```json
|
||||
{
|
||||
"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
|
||||
}
|
||||
```
|
||||
|
||||
**组件映射规则**：
|
||||
```javascript
|
||||
// 后端返回: "component": "home/index"
|
||||
// 实际加载: src/views/home/index.vue
|
||||
|
||||
// 后端返回: "component": "system/user"
|
||||
// 实际加载: src/views/system/user.vue
|
||||
```
|
||||
|
||||
### 5. 降级方案
|
||||
|
||||
如果后端接口失败，框架会使用默认菜单配置（`src/config/menuConfig.js`）：
|
||||
|
||||
```javascript
|
||||
export const defaultMenus = [
|
||||
{
|
||||
id: 1,
|
||||
name: '首页',
|
||||
path: '/home',
|
||||
component: 'home/index',
|
||||
parent_id: 0,
|
||||
type: '页面',
|
||||
is_show_menu: 1,
|
||||
icon: 'md-home',
|
||||
sort: 1
|
||||
},
|
||||
// ... 其他菜单
|
||||
]
|
||||
```
|
||||
|
||||
### 6. 更新快速开始示例
|
||||
|
||||
**新的 main.js 示例**：
|
||||
```javascript
|
||||
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'
|
||||
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 管理系统'
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
## 📊 更新对比
|
||||
|
||||
### 旧版本（已废弃）
|
||||
|
||||
```javascript
|
||||
// ❌ 旧版本：使用依赖注入
|
||||
import { systemApi, systemHighApi } from 'admin-framework'
|
||||
|
||||
AdminFramework.setUserServer(systemApi.userServer)
|
||||
AdminFramework.setParamSetupServer(systemHighApi.paramSetupServer)
|
||||
|
||||
// ❌ 旧版本：首页路由硬编码在框架中
|
||||
// 无法自定义首页组件
|
||||
```
|
||||
|
||||
### 新版本（当前）
|
||||
|
||||
```javascript
|
||||
// ✅ 新版本：直接导入 API
|
||||
import userServer from '../api/system/userServer'
|
||||
import paramSetupServer from '../api/system_high/paramSetupServer'
|
||||
|
||||
// ✅ 新版本：支持自定义首页组件
|
||||
import HomePage from './views/home/index.vue'
|
||||
|
||||
Vue.use(AdminFramework, {
|
||||
config,
|
||||
ViewUI,
|
||||
VueRouter,
|
||||
Vuex,
|
||||
createPersistedState,
|
||||
HomePage // 可选：传入自定义首页组件
|
||||
})
|
||||
```
|
||||
|
||||
## 🎯 最佳实践
|
||||
|
||||
### 推荐做法
|
||||
|
||||
1. **创建自定义首页组件**
|
||||
```bash
|
||||
src/views/home/index.vue
|
||||
```
|
||||
|
||||
2. **在 Vue.use() 时传入 HomePage 参数**
|
||||
```javascript
|
||||
import HomePage from './views/home/index.vue'
|
||||
|
||||
Vue.use(AdminFramework, {
|
||||
config,
|
||||
ViewUI,
|
||||
VueRouter,
|
||||
Vuex,
|
||||
createPersistedState,
|
||||
HomePage // 传入自定义首页组件
|
||||
})
|
||||
```
|
||||
|
||||
3. **确保后端返回首页菜单配置**
|
||||
```json
|
||||
{
|
||||
"id": 1,
|
||||
"name": "首页",
|
||||
"path": "/home",
|
||||
"component": "home/index",
|
||||
"parent_id": 0,
|
||||
"type": "页面",
|
||||
"is_show_menu": 1
|
||||
}
|
||||
```
|
||||
|
||||
4. **在 defaultMenus 中包含首页配置作为降级方案**
|
||||
```javascript
|
||||
// src/config/menuConfig.js
|
||||
export const defaultMenus = [
|
||||
{
|
||||
id: 1,
|
||||
name: '首页',
|
||||
path: '/home',
|
||||
component: 'home/index',
|
||||
// ...
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### 不推荐的做法
|
||||
|
||||
1. ❌ 使用已废弃的 `setUserServer` 和 `setParamSetupServer` 方法
|
||||
2. ❌ 在代码中硬编码首页路由
|
||||
3. ❌ 不提供降级方案（defaultMenus）
|
||||
|
||||
## 📝 迁移指南
|
||||
|
||||
### 从旧版本迁移到新版本
|
||||
|
||||
**步骤 1：移除废弃的方法调用**
|
||||
|
||||
```javascript
|
||||
// ❌ 删除这些代码
|
||||
AdminFramework.setUserServer(systemApi.userServer)
|
||||
AdminFramework.setParamSetupServer(systemHighApi.paramSetupServer)
|
||||
```
|
||||
|
||||
**步骤 2：创建自定义首页组件**
|
||||
|
||||
```bash
|
||||
# 创建首页组件文件
|
||||
mkdir -p src/views/home
|
||||
touch src/views/home/index.vue
|
||||
```
|
||||
|
||||
**步骤 3：更新 main.js**
|
||||
|
||||
```javascript
|
||||
// 添加 HomePage 导入
|
||||
import HomePage from './views/home/index.vue'
|
||||
|
||||
// 在 Vue.use() 时传入
|
||||
Vue.use(AdminFramework, {
|
||||
config,
|
||||
ViewUI,
|
||||
VueRouter,
|
||||
Vuex,
|
||||
createPersistedState,
|
||||
HomePage // 新增
|
||||
})
|
||||
```
|
||||
|
||||
**步骤 4：确保后端返回首页配置**
|
||||
|
||||
检查后端 `authorityMenus` 接口是否返回首页配置。
|
||||
|
||||
**步骤 5：测试**
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
登录后应该能看到自定义的首页。
|
||||
|
||||
## ✅ 验证清单
|
||||
|
||||
- ✅ 移除了 `setUserServer` 和 `setParamSetupServer` 的调用
|
||||
- ✅ 创建了自定义首页组件 `src/views/home/index.vue`
|
||||
- ✅ 在 `Vue.use()` 时传入了 `HomePage` 参数
|
||||
- ✅ 后端返回了首页菜单配置
|
||||
- ✅ `defaultMenus` 中包含了首页配置
|
||||
- ✅ 登录后能正常跳转到首页
|
||||
- ✅ 首页显示正确的内容
|
||||
|
||||
## 📚 相关文档
|
||||
|
||||
- `完整使用文档.md` - 完整的框架使用文档
|
||||
- `demo-project/README.md` - Demo 项目说明
|
||||
- `demo-project/登录跳转首页修复说明.md` - 登录跳转逻辑说明
|
||||
- `demo-project/移除硬编码首页说明.md` - 移除硬编码首页的说明
|
||||
|
||||
---
|
||||
|
||||
**文档已更新完成！** 🎉
|
||||
|
||||
现在文档更准确地反映了框架的当前实现，包括：
|
||||
- ✅ 移除了已废弃的方法
|
||||
- ✅ 添加了 HomePage 参数说明
|
||||
- ✅ 完善了首页组件的使用方式
|
||||
- ✅ 提供了最佳实践和迁移指南
|
||||
|
||||
228
完整使用文档.md
228
完整使用文档.md
@@ -165,6 +165,7 @@ import createPersistedState from 'vuex-persistedstate'
|
||||
import AdminFramework from './libs/admin-framework.js'
|
||||
import App from './App.vue'
|
||||
import config from './config'
|
||||
import HomePage from './views/home/index.vue' // 可选：自定义首页组件
|
||||
|
||||
// 🎉 只需这一行！框架自动完成所有初始化
|
||||
Vue.use(AdminFramework, {
|
||||
@@ -172,7 +173,8 @@ Vue.use(AdminFramework, {
|
||||
ViewUI,
|
||||
VueRouter,
|
||||
Vuex,
|
||||
createPersistedState
|
||||
createPersistedState,
|
||||
HomePage // 可选：传入自定义首页组件（不传则使用框架内置组件）
|
||||
})
|
||||
|
||||
// 创建 Vue 实例
|
||||
@@ -183,11 +185,17 @@ window.rootVue = new Vue({
|
||||
render: h => h(App),
|
||||
mounted() {
|
||||
AdminFramework.uiTool.setRem()
|
||||
this.$store.dispatch('user/setAuthorityMenus', {
|
||||
Main: AdminFramework.Main,
|
||||
ParentView: AdminFramework.ParentView,
|
||||
Page404: AdminFramework.Page404
|
||||
})
|
||||
|
||||
// 只在已登录时获取系统标题
|
||||
const token = this.$store.state.user.token
|
||||
if (token) {
|
||||
this.$store.dispatch('app/getSysTitle', {
|
||||
defaultTitle: 'Demo 管理系统',
|
||||
defaultLogo: ''
|
||||
})
|
||||
} else {
|
||||
document.title = 'Demo 管理系统'
|
||||
}
|
||||
}
|
||||
})
|
||||
|
||||
@@ -202,11 +210,10 @@ window.addEventListener('resize', AdminFramework.uiTool.setRem)
|
||||
- ✅ 注册 Vuex（自动调用 `Vue.use(Vuex)`）
|
||||
- ✅ 创建 Store（包含用户、应用模块）
|
||||
- ✅ 创建 Router（包含所有基础路由和动态路由）
|
||||
- ✅ **提前注册 home 路由**（确保登录后能正常跳转）
|
||||
- ✅ 初始化 HTTP
|
||||
- ✅ 设置 API 服务
|
||||
- ✅ 注册全局组件
|
||||
- ✅ 配置路由守卫
|
||||
- ✅ 支持自定义首页组件（通过 HomePage 参数传入）
|
||||
|
||||
#### 3. 安装依赖
|
||||
|
||||
@@ -354,16 +361,18 @@ Vue.use(AdminFramework, {
|
||||
ViewUI: ViewUI,
|
||||
VueRouter: VueRouter,
|
||||
Vuex: Vuex,
|
||||
createPersistedState: createPersistedState
|
||||
createPersistedState: createPersistedState,
|
||||
HomePage: HomePage // 可选：自定义首页组件
|
||||
})
|
||||
```
|
||||
|
||||
**参数说明：**
|
||||
- `config`: 项目配置对象
|
||||
- `ViewUI`: ViewUI 实例
|
||||
- `VueRouter`: VueRouter 类
|
||||
- `Vuex`: Vuex 类
|
||||
- `createPersistedState`: vuex-persistedstate 插件
|
||||
- `config`: 项目配置对象（必需）
|
||||
- `ViewUI`: ViewUI 实例（必需）
|
||||
- `VueRouter`: VueRouter 类（必需）
|
||||
- `Vuex`: Vuex 类（必需）
|
||||
- `createPersistedState`: vuex-persistedstate 插件（必需）
|
||||
- `HomePage`: 自定义首页组件（可选，不传则使用框架内置组件）
|
||||
|
||||
#### initHttp(config, store)
|
||||
初始化 HTTP 配置
|
||||
@@ -375,20 +384,6 @@ AdminFramework.initHttp({
|
||||
}, store)
|
||||
```
|
||||
|
||||
#### setUserServer(userServer)
|
||||
设置用户服务实例
|
||||
|
||||
```javascript
|
||||
AdminFramework.setUserServer(userServer)
|
||||
```
|
||||
|
||||
#### setParamSetupServer(paramSetupServer)
|
||||
设置参数设置服务实例
|
||||
|
||||
```javascript
|
||||
AdminFramework.setParamSetupServer(paramSetupServer)
|
||||
```
|
||||
|
||||
#### createRouter(Router, components, customRoutes, ViewUI, homeName)
|
||||
创建路由实例
|
||||
|
||||
@@ -955,7 +950,9 @@ export default {
|
||||
|
||||
### Q11: 主页 HomePage 组件说明
|
||||
|
||||
A: **框架已内置主页组件，自动显示系统标题欢迎信息。**
|
||||
A: **框架支持两种方式使用首页组件：使用内置组件或传入自定义组件。**
|
||||
|
||||
#### 方式一：使用框架内置的主页组件（默认）
|
||||
|
||||
**默认主页组件**：
|
||||
```vue
|
||||
@@ -973,27 +970,176 @@ A: **框架已内置主页组件，自动显示系统标题欢迎信息。**
|
||||
**特性**：
|
||||
- ✅ 自动从 Vuex Store 获取系统标题（`app/sysFormModel`）
|
||||
- ✅ 优雅的欢迎页面样式
|
||||
- ✅ home 路由已在创建 Router 时注册，确保登录后能正常跳转
|
||||
- ✅ 无需额外配置
|
||||
|
||||
**如何使用**：
|
||||
框架会自动创建 home 路由并使用内置的 HomePage 组件：
|
||||
**使用方式**：
|
||||
```javascript
|
||||
// 不传入 HomePage，框架会使用内置组件
|
||||
Vue.use(AdminFramework, {
|
||||
config,
|
||||
ViewUI,
|
||||
VueRouter,
|
||||
Vuex,
|
||||
createPersistedState
|
||||
})
|
||||
```
|
||||
|
||||
#### 方式二：传入自定义首页组件（推荐）
|
||||
|
||||
**创建自定义首页组件**：
|
||||
```vue
|
||||
<!-- 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>
|
||||
```
|
||||
|
||||
**传入自定义组件**：
|
||||
```javascript
|
||||
import HomePage from './views/home/index.vue'
|
||||
|
||||
Vue.use(AdminFramework, {
|
||||
config,
|
||||
ViewUI,
|
||||
VueRouter,
|
||||
Vuex,
|
||||
createPersistedState,
|
||||
HomePage // ✅ 传入自定义首页组件
|
||||
})
|
||||
```
|
||||
|
||||
#### 首页路由配置
|
||||
|
||||
**重要说明**：
|
||||
- ⚠️ **首页路由完全由后端权限菜单返回**
|
||||
- ⚠️ 后端必须返回 `path: '/home'` 的菜单配置
|
||||
- ⚠️ 后端返回的 `component` 字段会映射到实际组件
|
||||
|
||||
**后端菜单配置示例**：
|
||||
```json
|
||||
{
|
||||
path: '/home',
|
||||
name: 'home',
|
||||
meta: { title: '首页', notCache: true },
|
||||
component: AdminFramework.HomePage // 框架内置的主页组件
|
||||
"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
|
||||
}
|
||||
```
|
||||
|
||||
**自定义主页**：
|
||||
如果后端返回的权限菜单中包含 home 路由配置，会优先使用权限菜单的配置。
|
||||
|
||||
**直接使用 HomePage 组件**：
|
||||
**组件映射规则**：
|
||||
```javascript
|
||||
// 在其他地方也可以直接引用
|
||||
// 后端返回: "component": "home/index"
|
||||
// 实际加载: src/views/home/index.vue
|
||||
|
||||
// 后端返回: "component": "system/user"
|
||||
// 实际加载: src/views/system/user.vue
|
||||
```
|
||||
|
||||
#### 降级方案
|
||||
|
||||
如果后端接口失败，框架会使用默认菜单配置（`src/config/menuConfig.js`）：
|
||||
```javascript
|
||||
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 组件
|
||||
|
||||
```javascript
|
||||
// 获取框架内置的 HomePage 组件
|
||||
import AdminFramework from './libs/admin-framework.js'
|
||||
const HomePage = AdminFramework.HomePage
|
||||
|
||||
// 在路由中使用
|
||||
const routes = [
|
||||
{
|
||||
path: '/home',
|
||||
name: 'home',
|
||||
component: HomePage
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
#### 最佳实践
|
||||
|
||||
**推荐做法**：
|
||||
1. ✅ 创建自定义首页组件 `src/views/home/index.vue`
|
||||
2. ✅ 在 `Vue.use()` 时传入 `HomePage` 参数
|
||||
3. ✅ 确保后端返回首页菜单配置
|
||||
4. ✅ 在 `defaultMenus` 中包含首页配置作为降级方案
|
||||
|
||||
**完整示例**：
|
||||
```javascript
|
||||
// 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: 需要单独引入样式文件吗？
|
||||
|
||||
Reference in New Issue
Block a user