unis_sip/oms_web/docs/pages/main-layout.md

# 主框架页面设计规范

> Nex Design 主框架布局设计文档

## 概述

主框架页面是应用的基础布局结构，包含侧边菜单栏、顶部导航栏和内容区域。本文档详细说明了主框架的设计规范、交互逻辑和实现要点。

---

## 页面结构

```
┌─────────────────────────────────────────────────────┐
│                    顶部导航栏 (64px)                   │
├──────────┬──────────────────────────────────────────┤
│          │                                          │
│  侧边栏   │          内容区域                         │
│ (200px)  │      (可向下滚动)                         │
│          │                                          │
│          │                                          │
└──────────┴──────────────────────────────────────────┘
```

---

## 1. 侧边栏 (Sider)

### 1.1 基础规范

| 属性 | 展开状态 | 收起状态 |
|------|---------|---------|
| 宽度 | 200px | 64px |
| 背景色 | #001529 (深色) | #001529 |
| 位置 | 固定左侧 | 固定左侧 |
| 层级 | z-index: 10 | z-index: 10 |

### 1.2 Logo 区域

**设计规范**：
- 高度：64px
- 背景：rgba(255, 255, 255, 0.05)
- 底部边框：1px solid rgba(255, 255, 255, 0.05)
- 内边距：12px 16px
- 对齐：居中

**展开状态**：
- 显示完整 Logo（logo-full.png）
- Logo 高度：40px，宽度自适应

**收起状态**：
- 显示方形 Logo（logo-small.png）
- Logo 尺寸：40px × 40px
- 圆角：8px

### 1.3 菜单系统

#### 菜单层级

支持**两级菜单**结构：
- **一级菜单**：带图标，可展开/收起
- **二级菜单**：文字列表，可带徽章标识

#### 菜单数据格式

```json
[
  {
    "key": "overview",
    "label": "概览",
    "icon": "DashboardOutlined",
    "path": "/overview"
  },
  {
    "key": "certificate",
    "label": "证书管理",
    "icon": "SafetyCertificateOutlined",
    "children": [
      {
        "key": "ssl-cert",
        "label": "SSL证书管理",
        "path": "/certificate/ssl"
      }
    ]
  }
]
```

#### 菜单状态

**正常状态**：
- 背景色：透明
- 文字颜色：rgba(255, 255, 255, 0.65)

**悬停状态**：
- 背景色：rgba(184, 23, 141, 0.2)
- 文字颜色：#fff

**选中状态**：
- 背景色：#b8178d (品牌主色)
- 文字颜色：#fff
- 左侧边框：3px solid #b8178d

**展开状态**：
- 二级菜单背景：rgba(0, 0, 0, 0.15)
- 二级菜单内边距：左侧 48px

#### 徽章系统

支持在菜单项上显示徽章标识：

- **HOT 徽章**：
  - 背景色：#ff4d4f (红色)
  - 文字：白色
  - 尺寸：18px 高度，圆角 9px

- **NEW 徽章**：
  - 背景色：#52c41a (绿色)
  - 文字：白色
  - 尺寸：18px 高度，圆角 9px

**注意**：收起状态下徽章自动隐藏。

#### 收起状态行为

- 仅显示一级菜单图标
- 鼠标悬停时不展开子菜单
- 点击跳转到该分类的默认页面

### 1.4 滚动条样式

```css
宽度：6px
轨道：透明
滑块：rgba(255, 255, 255, 0.2)
滑块悬停：rgba(255, 255, 255, 0.3)
圆角：3px
```

---

## 2. 顶部导航栏 (Header)

### 2.1 基础规范

| 属性 | 值 |
|------|---|
| 高度 | 64px |
| 背景色 | #ffffff |
| 阴影 | 0 1px 4px rgba(0, 21, 41, 0.08) |
| 位置 | sticky，top: 0 |
| 层级 | z-index: 9 |
| 内边距 | 0 24px |

### 2.2 左侧区域

**折叠按钮**：
- 图标尺寸：18px
- 颜色：rgba(0, 0, 0, 0.65)
- 悬停色：#b8178d (品牌主色)
- 悬停背景：rgba(0, 0, 0, 0.03)
- 内边距：8px
- 圆角：4px
- 功能：切换侧边栏展开/收起状态

**工作台标识**：
- 字号：14px
- 字重：500 (Medium)
- 颜色：rgba(0, 0, 0, 0.88)
- 左侧间距：16px

### 2.3 右侧区域

从左到右依次包含：

1. **搜索框**
   - 宽度：200px
   - 高度：32px
   - 圆角：16px (胶囊形)
   - 占位文字："搜索..."
   - 前缀图标：SearchOutlined

2. **帮助图标**
   - 图标：QuestionCircleOutlined
   - 尺寸：16px
   - 颜色：rgba(0, 0, 0, 0.65)
   - 悬停色：#b8178d

3. **功能链接**（ICP 备案、企业、支持）
   - 字号：14px
   - 颜色：rgba(0, 0, 0, 0.65)
   - 悬停色：#b8178d
   - 悬停背景：rgba(0, 0, 0, 0.03)
   - 内边距：4px 8px
   - 圆角：4px

4. **工单图标**
   - 图标：SettingOutlined
   - 样式同帮助图标

5. **消息中心**
   - 图标：BellOutlined
   - 带徽章：Badge count={5}
   - 徽章位置：右上角，offset: [-3, 3]
   - 徽章尺寸：small

6. **用户信息**
   - 头像：32px × 32px 圆形
   - 用户名：14px，Medium 字重
   - 颜色：rgba(0, 0, 0, 0.88)
   - 整体内边距：4px 8px
   - 悬停背景：rgba(0, 0, 0, 0.03)
   - 点击显示下拉菜单

**间距**：各元素之间间距 16-20px

---

## 3. 内容区域 (Content)

### 3.1 基础规范

| 属性 | 值 |
|------|---|
| 背景色 | #f5f5f5 |
| 内边距 | 24px |
| 高度 | calc(100vh - 64px) |
| 滚动 | overflow-y: auto |

### 3.2 内容容器

- 最大宽度：根据业务需求，建议 1200-1600px
- 内边距：24px
- 背景色：根据内容类型，卡片为 #fff

### 3.3 滚动行为

- 仅内容区域可滚动
- 顶部导航栏和侧边栏保持固定
- 滚动条样式与全局一致

---

## 4. 响应式适配

### 4.1 断点规则

| 断点 | 行为 |
|------|------|
| < 768px | 侧边栏默认收起，通过遮罩层展开 |
| ≥ 768px | 侧边栏可正常展开/收起 |
| ≥ 1200px | 建议默认展开侧边栏 |

### 4.2 移动端优化

- 侧边栏改为抽屉模式 (Drawer)
- 顶部搜索框宽度减小或移至下拉菜单
- 功能链接收起至"更多"菜单
- 用户信息简化显示

---

## 5. 主题配色

### 5.1 品牌主色

基于 NEX Logo 的紫红色：

```css
--primary-color: #b8178d;
--primary-hover: #9c1477;
--primary-active: #801161;
```

### 5.2 辅助色

- **蓝色**（信息色）：#1677ff
- **绿色**（成功）：#52c41a
- **红色**（错误/警告）：#ff4d4f
- **橙色**（警告）：#faad14

### 5.3 中性色

```css
--text-primary: rgba(0, 0, 0, 0.88);
--text-secondary: rgba(0, 0, 0, 0.65);
--text-tertiary: rgba(0, 0, 0, 0.45);
--bg-primary: #ffffff;
--bg-secondary: #fafafa;
--bg-tertiary: #f5f5f5;
--border-color: #d9d9d9;
```

---

## 6. 交互规范

### 6.1 侧边栏折叠

**触发方式**：
- 点击顶部折叠按钮
- 可选：在设置中保存用户偏好

**动画**：
- 过渡时间：200ms
- 缓动函数：ease-in-out
- 影响元素：侧边栏宽度、Logo、菜单文字

**状态保持**：
- 使用 localStorage 保存用户折叠状态
- 页面刷新后保持用户选择

### 6.2 菜单导航

**展开逻辑**：
- 点击一级菜单展开/收起二级菜单
- 默认展开当前路由所在的菜单组
- 支持手风琴模式（可选）

**高亮逻辑**：
- 根据当前路由自动高亮对应菜单项
- 二级菜单选中时，一级菜单也显示激活状态

**跳转方式**：
- 使用 React Router 进行路由跳转
- 支持浏览器前进/后退

### 6.3 用户下拉菜单

**菜单项**：
- 个人中心
- 账户设置
- 分割线
- 退出登录

**交互**：
- 点击用户信息区域展开
- 点击菜单项执行对应操作
- 点击外部区域关闭

---

## 7. 代码实现

### 7.1 组件结构

```
MainLayout/
├── MainLayout.jsx      # 主布局组件
├── MainLayout.css      # 布局样式
├── AppSider.jsx        # 侧边栏组件
├── AppSider.css        # 侧边栏样式
├── AppHeader.jsx       # 顶部栏组件
├── AppHeader.css       # 顶部栏样式
└── index.js           # 导出文件
```

### 7.2 菜单数据配置

菜单数据独立维护在 `src/constants/menuData.json`，便于更新和管理。

### 7.3 关键技术点

1. **状态管理**：
   - collapsed 状态通过 props 传递
   - 菜单展开状态 (openKeys) 在 AppSider 内部管理

2. **路由集成**：
   - 使用 useNavigate 进行路由跳转
   - 使用 useLocation 获取当前路由

3. **图标映射**：
   - 通过 iconMap 对象将字符串转换为图标组件

4. **主题定制**：
   - 在 src/main.jsx 中配置 Ant Design 主题
   - 使用 ConfigProvider 包裹应用

---

## 8. 示例页面

### 8.1 概览页 (Overview)

作为主框架的示例页面，展示了：
- 统计卡片布局
- 图表展示
- 数据可视化
- 响应式栅格系统

详细设计见：[概览页设计文档](./overview.md)

---

## 9. 可访问性

### 9.1 键盘导航

- 支持 Tab 键在可交互元素间切换
- 支持 Enter 键激活菜单项
- 支持方向键在菜单间导航

### 9.2 语义化标签

- 使用 nav 标签包裹导航菜单
- 使用 header 标签包裹顶部栏
- 使用 main 标签包裹主内容区

### 9.3 对比度

- 所有文本与背景对比度 ≥ 4.5:1
- 图标与背景对比度 ≥ 3:1

---

## 10. 性能优化

### 10.1 懒加载

- 页面组件使用 React.lazy 懒加载
- 减少首屏加载时间

### 10.2 防抖优化

- 搜索框输入使用防抖处理
- 窗口大小变化使用节流处理

### 10.3 虚拟滚动

- 菜单项较多时考虑虚拟滚动
- 长列表使用虚拟化技术

---

## 11. 开发指南

### 11.1 添加新菜单

1. 编辑 `src/constants/menuData.json`
2. 添加菜单项配置
3. 如需新图标，在 `AppSider.jsx` 的 iconMap 中添加映射
4. 创建对应的页面组件
5. 在 `App.jsx` 中添加路由

### 11.2 自定义主题

1. 编辑 `src/main.jsx` 中的 theme 配置
2. 修改 `tailwind.config.js` 中的颜色系统
3. 更新 `src/styles/globals.css` 中的 CSS 变量

### 11.3 扩展功能

- 添加面包屑导航
- 添加页签 (Tabs) 功能
- 添加全局设置抽屉
- 添加主题切换（亮色/暗色）

---

## 12. 常见问题

### Q1: 如何修改侧边栏默认展开状态？

在 `MainLayout.jsx` 中修改 `collapsed` 的初始值：

```jsx
const [collapsed, setCollapsed] = useState(false) // false 为展开
```

### Q2: 如何添加三级菜单？

当前设计仅支持两级菜单。如需三级菜单，需要：
1. 修改 menuData.json 数据结构
2. 修改 AppSider.jsx 中的 getMenuItems 函数
3. 考虑 UI 空间和用户体验

### Q3: 如何实现菜单权限控制？

建议：
1. 在菜单数据中添加 `roles` 或 `permissions` 字段
2. 在渲染菜单前根据用户权限过滤
3. 在路由层面也要做权限校验

---

## 版本记录

| 版本 | 日期 | 说明 |
|------|------|------|
| 1.0.0 | 2024-11-04 | 初始版本，完成主框架设计 |

---

**维护者**: Nex Design Team
**最后更新**: 2024-11-04