docs: 更新DockIndicator指示器命名约定文档

- 修正层级结构图,添加完整的外部边缘指示器
- 在层级结构图中标注当前实际类名
- 完善命名体系的一致性
- 版本更新为v1.1
This commit is contained in:
zqm
2025-11-14 10:19:22 +08:00
parent b42e317ddd
commit d2f47559d3

View File

@@ -0,0 +1,136 @@
# DockIndicator 指示器命名约定
## 概述
为了方便团队沟通和代码维护特制定DockIndicator.vue中所有指示器的统一命名约定。
## 命名分类体系
### 1. 外部边缘指示器External Edge Indicators
位于DockLayout边缘的指示器用于检测全局边缘停靠。
| 当前名称 | 建议命名 | 用途说明 |
|---------|---------|----------|
| `indicator-top` | `global-top-indicator` | 全局顶部边缘指示器 |
| `indicator-right` | `global-right-indicator` | 全局右侧边缘指示器 |
| `indicator-bottom` | `global-bottom-indicator` | 全局底部边缘指示器 |
| `indicator-left` | `global-left-indicator` | 全局左侧边缘指示器 |
### 2. 中心区域容器Center Dock Container
包含所有中心区域相关指示器的容器。
| 名称 | 用途说明 |
|------|----------|
| `center-dock-container` | 中心区域容器,包装所有中心指示器 |
### 3. 中心指示区Center Dock Area
位于中心的半透明停靠区域。
| 当前名称 | 建议命名 | 用途说明 |
|---------|---------|----------|
| `indicator-center-area` | `center-dock-zone` | 中心停靠区域(半透明背景) |
### 4. 子区域指示器Sub-Area Indicators
位于中心区域内的四个子区域,用于检测具体停靠区域。
| 当前名称 | 建议命名 | 用途说明 |
|---------|---------|----------|
| `dock-top-area` | `center-top-area` | 中心区域内的上方区域指示器 |
| `dock-right-area` | `center-right-area` | 中心区域内的右侧区域指示器 |
| `dock-bottom-area` | `center-bottom-area` | 中心区域内的下方区域指示器 |
| `dock-left-area` | `center-left-area` | 中心区域内的左侧区域指示器 |
### 5. 边缘方向指示器Edge Direction Indicators
围绕中心区域边缘的四个方向指示器,用于精确停靠定位。
| 当前名称 | 建议命名 | 用途说明 |
|---------|---------|----------|
| `indicator-center-top` | `center-edge-top` | 中心区域上边缘指示器 |
| `indicator-center-right` | `center-edge-right` | 中心区域右边缘指示器 |
| `indicator-center-bottom` | `center-edge-bottom` | 中心区域下边缘指示器 |
| `indicator-center-left` | `center-edge-left` | 中心区域左边缘指示器 |
### 6. 中心指示器Center Indicator
位于中心区域中央的指示器。
| 当前名称 | 建议命名 | 用途说明 |
|---------|---------|----------|
| `indicator-center` | `center-main-indicator` | 中心主指示器 |
## 层级结构图
```
DockIndicator
├── 外部边缘指示器
│ ├── global-top-indicator (indicator-top)
│ ├── global-right-indicator (indicator-right)
│ ├── global-bottom-indicator (indicator-bottom)
│ └── global-left-indicator (indicator-left)
└── 中心区域容器 (center-dock-container)
├── 中心指示区 (center-dock-zone)
│ └── indicator-center-area
├── 子区域指示器
│ ├── center-top-area (dock-top-area)
│ ├── center-right-area (dock-right-area)
│ ├── center-bottom-area (dock-bottom-area)
│ └── center-left-area (dock-left-area)
├── 边缘方向指示器
│ ├── center-edge-top (indicator-center-top)
│ ├── center-edge-right (indicator-center-right)
│ ├── center-edge-bottom (indicator-center-bottom)
│ └── center-edge-left (indicator-center-left)
└── 中心指示器
└── center-main-indicator (indicator-center)
```
## 命名原则
1. **统一前缀规范**
- `global-`:全局/外部指示器
- `center-`:中心区域相关指示器
- `edge`:边缘方向指示器
- `area`:区域/区域指示器
2. **方向描述一致**
- `top`:顶部/上方
- `right`:右侧/右方
- `bottom`:底部/下方
- `left`:左侧/左方
- `main`:主要的/中心的
3. **功能清晰表达**
- `indicator`:指示器
- `zone`:区域/停靠区
- `container`:容器
## 使用建议
1. **代码中引用**:统一使用新命名进行类名和变量命名
2. **沟通时使用**:团队沟通时使用标准化的中文描述
3. **文档更新**:及时更新相关文档和注释
4. **渐进式重构**:建议在下次重构时统一更新类名
## 中文沟通用词建议
- **全局顶部指示器**:指代全局顶部边缘指示器
- **中心区域**指代center-dock-container
- **中心停靠区**指代center-dock-zone
- **中心各子区域**:分别称为"上方区域"、"右侧区域"、"下方区域"、"左侧区域"
- **中心边缘指示器**:分别称为"上边缘指示器"、"右边缘指示器"、"下边缘指示器"、"左边缘指示器"
- **中心主指示器**:指代中心的中央指示器
---
**文档版本**v1.1
**创建日期**2024年
**最后更新**2024年
**适用范围**DockIndicator.vue 组件
## 更新日志
### v1.1 (当前版本)
- 修正层级结构图,添加完整的外部边缘指示器(右、下、左)
- 在层级结构图中标注当前实际使用的类名
- 完善命名体系的一致性
### v1.0
- 初始版本,建立基础命名约定体系