219 lines
5.2 KiB
Markdown
219 lines
5.2 KiB
Markdown
# Z-Index 层级规范文档
|
||
|
||
## 📋 概述
|
||
|
||
本文档定义了项目中所有 z-index 的使用规范，确保层级关系清晰、一致、可维护。
|
||
|
||
## 🎯 设计原则
|
||
|
||
1. **分层管理**：将 z-index 划分为 5 个主要层级，每层预留充足空间
|
||
2. **语义化命名**：使用有意义的变量名，而非魔法数字
|
||
3. **统一来源**：所有 z-index 值统一定义在 `z-index.css` 中
|
||
4. **易于扩展**：每层之间至少预留 100 的空间，方便插入新层级
|
||
|
||
## 📊 层级划分
|
||
|
||
### 1️⃣ 基础层 (0-99)
|
||
用于页面背景、基础布局等底层元素
|
||
|
||
| 变量名 | 值 | 用途 |
|
||
|--------|-----|------|
|
||
| `--z-background` | 0 | 最底层 - 背景装饰 |
|
||
| `--z-base-content` | 1 | 基础内容层 - 普通文本、图片 |
|
||
| `--z-divider` | 10 | 分割线、边框装饰 |
|
||
|
||
**使用场景：**
|
||
- 页面背景渐变
|
||
- 基础卡片容器
|
||
- 列表项默认状态
|
||
|
||
---
|
||
|
||
### 2️⃣ 组件层 (100-999)
|
||
用于常规 UI 组件，如下拉菜单、悬浮提示等
|
||
|
||
| 变量名 | 值 | 用途 |
|
||
|--------|-----|------|
|
||
| `--z-top-bar` | 100 | TopBar 导航栏 |
|
||
| `--z-sidebar` | 100 | 侧边栏容器 |
|
||
| `--z-dropdown-menu` | 1000 | 下拉菜单（预设操作、世界书选择） |
|
||
| `--z-sort-panel` | 1100 | 排序设置面板 |
|
||
| `--z-tooltip` | 1200 | 悬浮提示 Tooltip |
|
||
| `--z-chat-actions` | 1000 | 聊天消息操作按钮 |
|
||
| `--z-character-preview` | 1000 | 角色卡预览弹窗 |
|
||
|
||
**使用场景：**
|
||
- 点击按钮弹出的下拉菜单
|
||
- 鼠标悬停显示的提示信息
|
||
- 聊天消息的快捷操作按钮
|
||
|
||
---
|
||
|
||
### 3️⃣ 弹窗层 (10000-19999)
|
||
用于模态对话框、编辑面板等需要覆盖整个页面的元素
|
||
|
||
| 变量名 | 值 | 用途 |
|
||
|--------|-------|------|
|
||
| `--z-modal-overlay` | 10000 | 对话框遮罩层背景 |
|
||
| `--z-modal-content` | 10100 | 对话框内容（API配置、预设保存等） |
|
||
| `--z-edit-panel-overlay` | 10200 | 世界书编辑面板遮罩层 |
|
||
| `--z-edit-panel-content` | 10300 | 世界书编辑面板内容 |
|
||
|
||
**使用场景：**
|
||
- API 配置对话框
|
||
- 预设保存/编辑对话框
|
||
- 世界书条目编辑面板
|
||
- 任何需要全屏遮罩的模态窗口
|
||
|
||
**层级关系：**
|
||
```
|
||
编辑面板内容 (10300)
|
||
↓
|
||
编辑面板遮罩 (10200)
|
||
↓
|
||
对话框内容 (10100)
|
||
↓
|
||
对话框遮罩 (10000)
|
||
```
|
||
|
||
---
|
||
|
||
### 4️⃣ 通知层 (20000-29999)
|
||
用于全局通知、Toast 提示等
|
||
|
||
| 变量名 | 值 | 用途 |
|
||
|--------|-------|------|
|
||
| `--z-toast-container` | 20000 | Toast 通知容器 |
|
||
| `--z-toast-item` | 20100 | Toast 通知项 |
|
||
|
||
**使用场景：**
|
||
- 操作成功/失败的提示
|
||
- 系统通知
|
||
- 警告信息
|
||
|
||
---
|
||
|
||
### 5️⃣ 系统层 (30000+)
|
||
用于系统级元素，如加载动画、错误边界等
|
||
|
||
| 变量名 | 值 | 用途 |
|
||
|--------|-------|------|
|
||
| `--z-loading-spinner` | 30000 | 全局加载动画 |
|
||
| `--z-error-boundary` | 30100 | 错误边界覆盖层 |
|
||
|
||
**使用场景：**
|
||
- 页面加载时的旋转动画
|
||
- 错误捕获后的全屏提示
|
||
- 系统级遮罩
|
||
|
||
---
|
||
|
||
## 💡 使用指南
|
||
|
||
### CSS 中使用
|
||
|
||
```css
|
||
/* ✅ 推荐：使用 CSS 变量 */
|
||
.dropdown-menu {
|
||
z-index: var(--z-dropdown-menu);
|
||
}
|
||
|
||
.modal-overlay {
|
||
z-index: var(--z-modal-overlay);
|
||
}
|
||
|
||
.edit-panel {
|
||
z-index: var(--z-edit-panel-content);
|
||
}
|
||
```
|
||
|
||
### TypeScript/JavaScript 中使用
|
||
|
||
```typescript
|
||
// ✅ 推荐：导入常量
|
||
import { Z_INDEX } from '../styles/z-index';
|
||
|
||
const style = {
|
||
zIndex: Z_INDEX.DROPDOWN_MENU,
|
||
};
|
||
```
|
||
|
||
### ❌ 避免的做法
|
||
|
||
```css
|
||
/* ❌ 不要使用魔法数字 */
|
||
.dropdown-menu {
|
||
z-index: 1000; /* 难以理解，不易维护 */
|
||
}
|
||
|
||
/* ❌ 不要使用过大的数值 */
|
||
.modal {
|
||
z-index: 99999; /* 不合理，可能导致层级混乱 */
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 添加新层级
|
||
|
||
如果需要添加新的 z-index 层级，请遵循以下步骤：
|
||
|
||
1. **确定所属层级**：根据元素类型选择合适的层级范围
|
||
2. **选择合适数值**：在该层级范围内选择一个未使用的值（预留 100 间隔）
|
||
3. **更新定义文件**：
|
||
- 在 `z-index.css` 中添加 CSS 变量
|
||
- 在 `z-index.ts` 中添加 TypeScript 常量
|
||
4. **更新文档**：在本文档中添加说明
|
||
|
||
**示例：添加一个新的工具提示层级**
|
||
|
||
```css
|
||
/* z-index.css */
|
||
:root {
|
||
--z-help-tooltip: 1300; /* 在 tooltip (1200) 之上 */
|
||
}
|
||
```
|
||
|
||
```typescript
|
||
// z-index.ts
|
||
export const Z_INDEX = {
|
||
// ...
|
||
HELP_TOOLTIP: 1300,
|
||
} as const;
|
||
```
|
||
|
||
---
|
||
|
||
## 📝 常见问题
|
||
|
||
### Q: 为什么弹窗层从 10000 开始？
|
||
A: 为了与组件层（100-999）保持足够的距离，避免未来在组件层添加更多层级时产生冲突。
|
||
|
||
### Q: 如果两个元素都需要弹窗层怎么办？
|
||
A: 使用不同的子层级，例如：
|
||
- 第一个弹窗：`--z-modal-content` (10100)
|
||
- 第二个弹窗：`--z-modal-content + 10` (10110)
|
||
|
||
### Q: 可以在 inline style 中使用吗？
|
||
A: 可以，但推荐使用 CSS 类。如果必须使用 inline style：
|
||
|
||
```jsx
|
||
<div style={{ zIndex: 'var(--z-dropdown-menu)' }}>
|
||
```
|
||
|
||
---
|
||
|
||
## 📚 相关文件
|
||
|
||
- **CSS 变量定义**：`frontend/src/styles/z-index.css`
|
||
- **TypeScript 常量**：`frontend/src/styles/z-index.ts`
|
||
- **全局样式引入**：`frontend/src/index.css`
|
||
|
||
---
|
||
|
||
## 🔄 更新历史
|
||
|
||
| 日期 | 版本 | 更新内容 |
|
||
|------|------|----------|
|
||
| 2026-05-04 | 1.0 | 初始版本，建立完整的 z-index 层级体系 |
|