496 lines
11 KiB
Markdown
496 lines
11 KiB
Markdown
# 主框架页面设计规范
|
||
|
||
> 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
|