# 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/game_pages/list/index.tsx`（主逻辑）
- `src/components/DistanceQuickFilter/index.tsx`（筛选菜单回调）
- `src/components/PublishMenu/PublishMenu.tsx`（发布菜单回调）
- `src/components/GuideBar/index.tsx`（接收回调）

**监听的状态**：
1. **`isPublishMenuVisible`** - 发布菜单展开状态
2. **`isShowFilterPopup`** - 综合筛选弹窗展开状态
3. **`isDistanceFilterVisible`** - 距离/排序筛选下拉菜单展开状态

**动态逻辑**：
```tsx
if (isPublishMenuVisible) {
  // 发布菜单展开 → z-index: 900 (high)
  setGuideBarZIndex('high');
} else if (isShowFilterPopup || isDistanceFilterVisible) {
  // 任何筛选组件展开 → 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，解决层级冲突问题