272 lines
6.5 KiB
Markdown
272 lines
6.5 KiB
Markdown
# Mall Admin 布局系统使用指南
|
||
|
||
## 概述
|
||
|
||
本项目已基于CRMEB Admin的vertical布局设计，创建了一套统一的admin管理后台布局系统。该系统提供：
|
||
|
||
- 🎨 **统一视觉设计** - 参考CRMEB Admin的深色侧边栏风格
|
||
- 📱 **响应式布局** - 支持桌面端和移动端自适应
|
||
- 🔧 **灵活配置** - 支持菜单折叠、主题切换等功能
|
||
- 🧭 **智能导航** - 自动高亮当前页面，支持子菜单展开
|
||
|
||
## 文件结构
|
||
|
||
```
|
||
layouts/
|
||
├── admin/
|
||
│ └── index.uvue # 主布局组件
|
||
|
||
pages/mall/admin/
|
||
├── index.uvue # 首页（已集成布局）
|
||
├── user-management.uvue # 用户管理（已集成布局）
|
||
└── ... # 其他页面
|
||
|
||
pages.json # 页面配置（已更新）
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 1. 在页面中使用AdminLayout
|
||
|
||
```vue
|
||
<template>
|
||
<AdminLayout current-page="your-page-id">
|
||
<!-- 你的页面内容 -->
|
||
<view class="your-page-content">
|
||
<!-- 页面具体内容 -->
|
||
</view>
|
||
</AdminLayout>
|
||
</template>
|
||
|
||
<script setup lang="uts">
|
||
import AdminLayout from '@/layouts/admin/index.uvue'
|
||
|
||
// 你的页面逻辑
|
||
</script>
|
||
```
|
||
|
||
### 2. current-page 参数说明
|
||
|
||
`current-page` 属性用于标识当前页面，对应的菜单项会被高亮显示：
|
||
|
||
| 页面 | current-page 值 | 说明 |
|
||
|------|----------------|------|
|
||
| 首页 | `dashboard` | 主页 |
|
||
| 用户管理 | `user-list` | 用户列表页 |
|
||
| 商品管理 | `product-list` | 商品列表页 |
|
||
| 订单管理 | `order` | 订单管理页 |
|
||
| 商家管理 | `merchant-list` | 商家列表页 |
|
||
| 系统设置 | `system` | 系统设置页 |
|
||
|
||
### 3. 页面配置
|
||
|
||
在 `pages.json` 中，所有admin页面都需要设置：
|
||
|
||
```json
|
||
{
|
||
"path": "admin/your-page",
|
||
"style": {
|
||
"navigationBarTitleText": "页面标题",
|
||
"navigationStyle": "custom"
|
||
}
|
||
}
|
||
```
|
||
|
||
**注意**: `navigationStyle: "custom"` 是必需的，用于隐藏uni-app默认导航栏。
|
||
|
||
## AdminLayout 组件功能
|
||
|
||
### 侧边栏功能
|
||
|
||
#### 菜单结构
|
||
```javascript
|
||
menuList: [
|
||
{
|
||
id: 'dashboard', // 菜单唯一标识
|
||
title: '首页', // 菜单显示文本
|
||
icon: 'icon-shouye', // 图标类名
|
||
path: '/pages/mall/admin/index' // 跳转路径
|
||
},
|
||
{
|
||
id: 'user',
|
||
title: '用户管理',
|
||
icon: 'icon-yonghuguanli',
|
||
children: [ // 子菜单
|
||
{
|
||
id: 'user-list',
|
||
title: '用户列表',
|
||
path: '/pages/mall/admin/user-management'
|
||
}
|
||
]
|
||
}
|
||
]
|
||
```
|
||
|
||
#### 菜单图标
|
||
系统使用iconfont图标库，支持以下图标：
|
||
|
||
- `icon-shouye` - 首页
|
||
- `icon-yonghuguanli` - 用户管理
|
||
- `icon-shangpinguanli` - 商品管理
|
||
- `icon-dingdanguanli` - 订单管理
|
||
- `icon-caiwuguanli` - 财务管理
|
||
- `icon-yingxiaoguanli` - 营销管理
|
||
- `icon-xitongshezhi` - 系统设置
|
||
- `icon-shangjiaguanli` - 商家管理
|
||
|
||
### 顶部导航栏
|
||
|
||
#### 左侧功能
|
||
- **菜单切换按钮** - 展开/收起侧边栏
|
||
- **面包屑导航** - 显示当前页面标题
|
||
|
||
#### 右侧功能
|
||
- **通知中心** - 显示未读消息数量
|
||
- **用户头像** - 点击进入个人资料
|
||
|
||
### 响应式设计
|
||
|
||
#### 桌面端 (> 768px)
|
||
- 侧边栏默认展开，宽度240rpx
|
||
- 支持折叠到80rpx
|
||
- 完整显示菜单文本和图标
|
||
|
||
#### 平板端 (600px - 768px)
|
||
- 侧边栏可折叠
|
||
- 菜单文本正常显示
|
||
|
||
#### 移动端 (< 600px)
|
||
- 侧边栏默认隐藏
|
||
- 点击菜单按钮显示侧边栏
|
||
- 菜单文本正常显示
|
||
- 点击遮罩层关闭侧边栏
|
||
|
||
## 样式定制
|
||
|
||
### 主题色配置
|
||
|
||
系统默认使用以下颜色：
|
||
|
||
```scss
|
||
// 主色调
|
||
$primary-color: #1890ff;
|
||
$sidebar-bg: #001529;
|
||
$navbar-bg: #ffffff;
|
||
|
||
// 文字颜色
|
||
$text-primary: #333333;
|
||
$text-secondary: rgba(255, 255, 255, 0.75);
|
||
$text-muted: rgba(255, 255, 255, 0.65);
|
||
```
|
||
|
||
### 自定义样式
|
||
|
||
如需修改样式，可以在 `layouts/admin/index.uvue` 的 `<style>` 部分进行调整：
|
||
|
||
```scss
|
||
// 修改侧边栏背景色
|
||
.admin-sidebar {
|
||
background-color: #002140; // 更深的蓝色
|
||
}
|
||
|
||
// 修改菜单项激活状态
|
||
.menu-link-active {
|
||
background-color: #0050b3; // 不同的激活色
|
||
}
|
||
```
|
||
|
||
## 数据持久化
|
||
|
||
系统自动保存用户偏好设置到本地存储：
|
||
|
||
- **侧边栏折叠状态** - `admin_sidebar_collapsed`
|
||
- **展开的子菜单** - `admin_open_menus`
|
||
- **用户信息** - 从本地存储读取
|
||
|
||
## 扩展指南
|
||
|
||
### 添加新菜单项
|
||
|
||
1. 在 `menuList` 中添加新菜单配置
|
||
2. 为菜单项分配唯一的 `id`
|
||
3. 设置合适的图标和路径
|
||
4. 如果有子菜单，使用 `children` 数组
|
||
|
||
### 添加新页面
|
||
|
||
1. 创建页面文件 `pages/mall/admin/new-page.uvue`
|
||
2. 使用 `AdminLayout` 包装页面内容
|
||
3. 设置正确的 `current-page` 属性
|
||
4. 在 `pages.json` 中注册页面，设置 `"navigationStyle": "custom"`
|
||
|
||
### 自定义菜单图标
|
||
|
||
1. 在iconfont中添加新图标
|
||
2. 获取图标的class名称（如 `icon-new-feature`）
|
||
3. 在菜单配置中使用该class名
|
||
|
||
## 故障排除
|
||
|
||
### 菜单不显示
|
||
- 检查页面是否正确导入了 `AdminLayout` 组件
|
||
- 确认 `current-page` 属性值与菜单配置中的 `id` 匹配
|
||
|
||
### 样式异常
|
||
- 检查页面是否设置了 `"navigationStyle": "custom"`
|
||
- 确认没有与uni-app默认样式冲突
|
||
|
||
### 移动端适配问题
|
||
- 检查响应式断点是否正确设置
|
||
- 确认遮罩层和侧边栏切换逻辑正常
|
||
|
||
## 迁移现有页面
|
||
|
||
对于已有的admin页面，按以下步骤迁移：
|
||
|
||
1. **导入AdminLayout组件**
|
||
```javascript
|
||
import AdminLayout from '@/layouts/admin/index.uvue'
|
||
```
|
||
|
||
2. **包装页面内容**
|
||
```vue
|
||
<template>
|
||
<AdminLayout current-page="page-id">
|
||
<!-- 原有页面内容 -->
|
||
</AdminLayout>
|
||
</template>
|
||
```
|
||
|
||
3. **更新pages.json配置**
|
||
```json
|
||
{
|
||
"style": {
|
||
"navigationStyle": "custom"
|
||
}
|
||
}
|
||
```
|
||
|
||
4. **移除原有导航栏代码**
|
||
- 删除页面内的自定义导航栏
|
||
- 移除相关的导航栏样式
|
||
|
||
## 最佳实践
|
||
|
||
1. **保持菜单结构清晰** - 使用合理的分组和层级
|
||
2. **图标选择一致** - 使用统一的图标风格
|
||
3. **页面标题准确** - 确保面包屑显示正确的页面标题
|
||
4. **响应式测试** - 在不同设备上测试布局效果
|
||
5. **性能优化** - 避免在菜单中放置大量数据
|
||
|
||
## 更新日志
|
||
|
||
### v1.0.0 (2025-01-23)
|
||
- ✅ 基于CRMEB Admin设计创建统一布局系统
|
||
- ✅ 支持响应式布局和菜单折叠
|
||
- ✅ 集成用户管理和首页
|
||
- ✅ 完成pages.json配置更新
|
||
- ✅ 提供完整的使用文档
|
||
|
||
---
|
||
|
||
如有问题或需要进一步定制，请参考源代码或联系开发团队。 |