mini-programs/docs/z-index-guide.md

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 - 距离/排序筛选下拉菜单展开状态

动态逻辑：

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，解决层级冲突问题