363 lines
7.6 KiB
Markdown
363 lines
7.6 KiB
Markdown
# 文档更新说明
|
||
|
||
## 📝 更新内容
|
||
|
||
已更新 `完整使用文档.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 参数说明
|
||
- ✅ 完善了首页组件的使用方式
|
||
- ✅ 提供了最佳实践和迁移指南
|
||
|