初步构建起页面布局

ADMIN_LAYOUT_GUIDE.md

@@ -0,0 +1,272 @@
+# 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配置更新
+- ✅ 提供完整的使用文档
+
+---
+
+如有问题或需要进一步定制，请参考源代码或联系开发团队。