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

• 初始版本，建立基础命名约定体系