107 lines
3.7 KiB
Markdown
107 lines
3.7 KiB
Markdown
# Z-Index 层级管理规范
|
||
|
||
## 层级划分
|
||
|
||
为了避免 z-index 冲突，项目采用以下层级划分：
|
||
|
||
```
|
||
0-99: 页面内容层（普通元素、卡片、列表项等）
|
||
100-899: 固定定位元素（顶部导航栏、sticky 元素等）
|
||
900-999: 底部导航栏和菜单
|
||
1000-1999: 下拉菜单、筛选面板
|
||
2000-8999: 模态框、弹窗
|
||
9000+: 全局提示、Toast、确认框
|
||
```
|
||
|
||
## 具体层级分配
|
||
|
||
### 页面内容层 (0-99)
|
||
- **0-9**: 背景层
|
||
- **10-99**: 普通内容元素
|
||
|
||
### 固定定位层 (100-899)
|
||
- **100**: 页面头部固定区域（.fixedHeader）
|
||
- **100-199**: 顶部导航栏、搜索栏
|
||
- **200-899**: 其他 sticky 元素
|
||
|
||
### 底部导航和菜单层 (900-999)
|
||
- **80**: 底部导航栏降低层级（GuideBar - 筛选弹窗显示时）
|
||
- **900**: 底部导航栏正常层级（GuideBar - 默认状态）
|
||
- **940**: 发布菜单遮罩层（PublishMenu overlay）
|
||
- **950**: 发布菜单容器（PublishMenu container）
|
||
- **960**: 发布菜单卡片（PublishMenu card）
|
||
|
||
### 下拉菜单层 (1000-1999)
|
||
- **1100**: 距离筛选下拉菜单（DistanceQuickFilter）
|
||
- **1200**: 综合筛选弹窗（FilterPopup）
|
||
|
||
### 模态框层 (2000-8999)
|
||
- **2000-5000**: 普通弹窗
|
||
- **9999**: CommonPopup（全局通用弹窗）
|
||
|
||
## 动态 Z-Index 控制
|
||
|
||
某些组件需要根据交互状态动态调整 z-index：
|
||
|
||
### GuideBar（底部导航栏）动态控制
|
||
|
||
|
||
- `src/components/DistanceQuickFilter/index.tsx`（筛选菜单回调）
|
||
- `src/components/PublishMenu/PublishMenu.tsx`（发布菜单回调）
|
||
- `src/container/listCustomNavbar/index.tsx`（城市选择器回调）
|
||
- `src/components/GuideBar/index.tsx`（接收回调）
|
||
|
||
**监听的状态**：
|
||
1. **`isPublishMenuVisible`** - 发布菜单展开状态
|
||
2. **`isShowFilterPopup`** - 综合筛选弹窗展开状态
|
||
3. **`isDistanceFilterVisible`** - 距离/排序筛选下拉菜单展开状态
|
||
4. **`isCityPickerVisible`** - 城市选择器展开状态
|
||
|
||
**动态逻辑**：
|
||
```tsx
|
||
if (isPublishMenuVisible) {
|
||
// 发布菜单展开 → z-index: 900 (high)
|
||
setGuideBarZIndex('high');
|
||
} else if (isShowFilterPopup || isDistanceFilterVisible || isCityPickerVisible) {
|
||
// 任何筛选组件或选择器展开 → z-index: 80 (low)
|
||
setGuideBarZIndex('low');
|
||
} else {
|
||
// 都关闭 → z-index: 900 (high)
|
||
setGuideBarZIndex('high');
|
||
}
|
||
```
|
||
|
||
**优势**：
|
||
- 自动响应所有相关组件的状态变化
|
||
- 优先级清晰：发布菜单 > 筛选组件 > 默认状态
|
||
- 避免底部导航栏遮挡筛选内容
|
||
|
||
## 使用原则
|
||
|
||
1. **同类组件使用相近的 z-index**：便于管理和维护
|
||
2. **预留足够的间隔**：为未来新增组件预留空间
|
||
3. **避免使用过大的值**：除非是全局级别的组件（如 Toast）
|
||
4. **使用 !important 需谨慎**：只在覆盖第三方组件样式时使用
|
||
5. **优先考虑动态控制**：对于有交互冲突的组件，使用动态 z-index 而不是固定值
|
||
|
||
## 常见问题
|
||
|
||
### Q: 筛选下拉菜单被底部导航栏遮挡？
|
||
A: 确保下拉菜单 z-index (1100) 大于底部导航栏 (900)
|
||
|
||
### Q: 发布菜单弹出时被筛选菜单遮挡？
|
||
A: 发布菜单 (950-960) 低于筛选菜单 (1100-1200)，这是正常的层级关系
|
||
|
||
### Q: 如何添加新的浮层组件？
|
||
A: 根据组件类型，在对应层级范围内选择合适的值，并更新此文档
|
||
|
||
## 修改记录
|
||
|
||
- 2024-xx-xx: 完善 GuideBar 动态 z-index 控制，监听所有筛选组件和发布菜单状态
|
||
- 新增 DistanceQuickFilter 菜单展开/收起回调
|
||
- 新增 PublishMenu 展开/收起回调
|
||
- 使用 useEffect 统一管理 z-index 逻辑
|
||
- 2024-xx-xx: 实现 GuideBar 动态 z-index 控制，根据筛选弹窗状态自动调整层级
|
||
- 2024-xx-xx: 统一调整底部导航栏和筛选菜单的 z-index，解决层级冲突问题
|
||
|