JoyD/AutoRobot/Windows/Robot/Web/src/DockLayout/DockIndicator指示器命名约定.md

# 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）
位于中心区域内的四个半透明子区域，鼠标悬停后显示半透明的依靠区，以鼠标位置所在的Area.vue内容区作为基准进行停靠检测。

| 当前名称 | 建议命名 | 用途说明 |
|---------|---------|----------|
| `dock-top-area` | `center-top-area` | 中心区域内上方半透明区域，鼠标悬停显示停靠依靠区 |
| `dock-right-area` | `center-right-area` | 中心区域内右侧半透明区域，鼠标悬停显示停靠依靠区 |
| `dock-bottom-area` | `center-bottom-area` | 中心区域内下方半透明区域，鼠标悬停显示停靠依靠区 |
| `dock-left-area` | `center-left-area` | 中心区域内左侧半透明区域，鼠标悬停显示停靠依靠区 |

**✅ 已完成功能实现（v1.2）**：
- 子区域鼠标事件处理（hover效果）
- 鼠标位置检测功能（detectMouseArea方法）
- 半透明依靠区动态显示（computeRelianceAreaStyle方法）
- Area组件标识支持（data-area-id属性）
- 基于鼠标位置的动态样式计算（enhancedPreviewAreaStyle）

### 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. 独立中心指示器（Independent Center Indicator）
位于与中心区域容器同级的独立中心指示器，具有更高层级（z-index:10000）。

| 当前名称 | 建议命名 | 用途说明 |
|---------|---------|----------|
| `center-main-indicator` | - | 独立中心指示器，与中心区域容器同级但位于容器上层（z-index:10000），位于容器正中央，提供主要的中心区域交互入口 |

## 层级结构图

```
DockIndicator
├── 外部边缘指示器
│   ├── indicator-top (global-top-indicator)
│   ├── indicator-right (global-right-indicator)  
│   ├── indicator-bottom (global-bottom-indicator)
│   └── indicator-left (global-left-indicator)
├── 中心区域容器 (center-dock-container)
│   ├── 中心指示区 (indicator-center-area)
│   ├── 边缘方向指示器
│   │   ├── 中心指示区上方指示器 (indicator-center-top)
│   │   ├── 中心指示区右侧指示器 (indicator-center-right)
│   │   ├── 中心指示区下方指示器 (indicator-center-bottom)
│   │   └── 中心指示区左侧指示器 (indicator-center-left)
│   └── 子区域指示器
│       ├── 上区指示 (dock-top-area)
│       ├── 右区指示 (dock-right-area)
│       ├── 下区指示 (dock-bottom-area)
│       └── 左区指示 (dock-left-area)
└── 独立中心指示器 (center-main-indicator) [位于中心区域容器上层，z-index:10000]
```

## 命名原则

1. **统一前缀规范**：
   - `global-`：全局/外部指示器
   - `center-`：中心区域相关指示器
   - `edge`：边缘方向指示器
   - `area`：区域/区域指示器

2. **方向描述一致**：
   - `top`：顶部/上方
   - `right`：右侧/右方
   - `bottom`：底部/下方
   - `left`：左侧/左方
   - `main`：主要的/中心的

3. **功能清晰表达**：
   - `indicator`：指示器
   - `zone`：区域/停靠区
   - `container`：容器

## 使用建议

1. **代码中引用**：统一使用新命名进行类名和变量命名
2. **沟通时使用**：团队沟通时使用标准化的中文描述
3. **文档更新**：及时更新相关文档和注释
4. **渐进式重构**：建议在下次重构时统一更新类名

## 中文沟通用词建议

- **全局顶部指示器**：指代全局顶部边缘指示器
- **全局右侧指示器**：指代全局右侧边缘指示器  
- **全局底部指示器**：指代全局底部边缘指示器
- **全局左侧指示器**：指代全局左侧边缘指示器
- **独立中心指示器**：指代center-main-indicator，与中心区域容器同级但位于容器上层的独立中心指示器（z-index:10）
- **中心区域**：指代center-dock-container
- **中心停靠区**：指代center-dock-zone
- **中心上方区域**：指代center-top-area，鼠标悬停显示停靠依靠区
- **中心右侧区域**：指代center-right-area，鼠标悬停显示停靠依靠区
- **中心下方区域**：指代center-bottom-area，鼠标悬停显示停靠依靠区
- **中心左侧区域**：指代center-left-area，鼠标悬停显示停靠依靠区
- **中心上边缘指示器**：指代center-edge-top，用于精确停靠定位
- **中心右边缘指示器**：指代center-edge-right，用于精确停靠定位
- **中心下边缘指示器**：指代center-edge-bottom，用于精确停靠定位
- **中心左边缘指示器**：指代center-edge-left，用于精确停靠定位

---

**文档版本**：v1.8  
**创建日期**：2024年  
**最后更新**：2024年  
**适用范围**：DockIndicator.vue 组件

## 更新日志

### v1.8 (当前版本)
- **重要修正**：移除文档中不准确的`indicator-center`描述，反映真实代码状态
- 删除"中心指示器"章节，该组件已从模板中移除
- 修正层级结构图，移除不存在的`indicator-center`节点
- 增强中文沟通用词建议，提供更详细的指示器说明
- **层级修正**：将独立中心指示器z-index从10更新为10000，确保其位于中心区域容器之上
- **代码清理**：删除DockIndicator.vue中残留的无用indicator-center样式定义

### v1.7 (前一版本)
- 修改DockIndicator.vue代码，实现将中心指示器移到与中心区域容器同级
- 保持中心指示器位置相对于中心区域容器正中央
- 更新层级结构图，增加独立中心指示器层级
- 新增独立中心指示器分类说明
- 更新层级结构图格式和内容

### v1.6 (前一版本)
- 根据实际代码情况更新文档结构
- 移除独立中心指示器相关内容，确认真实实现为单一的center-dock-container内部指示器
- 更新层级结构图，反映实际的DOM层级结构
- 统一文档内容与代码实现的一致性

### v1.3
- 添加独立中心指示器相关命名约定
- 更新层级结构图，增加独立中心指示器层级
- 更新中文沟通用词建议，增加独立中心指示器相关词汇
- 调整中心指示器分类，区分容器内外两种类型

### v1.2
- 添加子区域指示器功能实现记录
- 更新文档以反映半透明依靠区功能的完成状态

### v1.1
- 修正层级结构图，添加完整的外部边缘指示器（右、下、左）
- 在层级结构图中标注当前实际使用的类名
- 完善命名体系的一致性

### v1.0
- 初始版本，建立基础命名约定体系