diff --git a/demo-project/文档更新说明.md b/demo-project/文档更新说明.md new file mode 100644 index 0000000..ee9fea3 --- /dev/null +++ b/demo-project/文档更新说明.md @@ -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 + + + + +``` + +**传入自定义组件**: +```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 参数说明 +- ✅ 完善了首页组件的使用方式 +- ✅ 提供了最佳实践和迁移指南 + diff --git a/完整使用文档.md b/完整使用文档.md index 1fe4841..0afc386 100644 --- a/完整使用文档.md +++ b/完整使用文档.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 + + + + + + +``` + +**传入自定义组件**: +```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: 需要单独引入样式文件吗?