bim_engine/docs/components/button-group.md

# ButtonGroup 组件详细文档

> 本文档详细描述 ButtonGroup 组件的实现细节，包括 API、UI 结构、逻辑流程等，供 AI 根据文档重现组件。

---

## 1. 组件概述

### 1.1 基本信息
- **组件名称**: `BimButtonGroup`
- **文件路径**: `src/components/button-group/index.ts`
- **类型定义**: `src/components/button-group/index.type.ts`
- **样式文件**: `src/components/button-group/index.css`
- **实现接口**: `IBimComponent`
- **用途**: 提供通用的按钮组组件，支持按钮、菜单、分组、嵌套菜单等功能

### 1.2 在 SDK 中的位置
- ButtonGroup 组件是独立的 UI 组件
- 必须通过 `ButtonGroupManager` 或 `ToolbarManager` 使用，不允许直接使用
- `ButtonGroupManager` 位于 `src/managers/button-group-manager.ts`
- `ToolbarManager` 位于 `src/managers/toolbar-manager.ts`

---

## 2. 组件类 API 文档

### 2.1 构造函数

```typescript
constructor(options: ButtonGroupOptions)
```

**参数**:
- `options`: `ButtonGroupOptions` - 按钮组配置选项（详见类型定义）

**默认配置**:
```typescript
{
    showLabel: true,
    visibility: {},
    direction: 'row',      // 默认横向排列
    position: 'static',    // 默认静态定位
    align: 'vertical',     // 默认图标在上
    expand: 'down'         // 默认向下展开
}
```

**行为**:
- 解析容器元素（支持字符串 ID 或 HTMLElement）
- 合并用户配置和默认配置
- 记录用户自定义的颜色属性
- 初始化容器
- 应用样式

### 2.2 公共方法

#### `setEngine(engine: BimEngine): void`
设置引擎实例

**参数**:
- `engine`: `BimEngine` - 引擎实例

**功能**:
- 保存引擎引用，用于发送事件

#### `init(): Promise<void>`
初始化组件功能（实现 `IBimComponent` 接口）

**功能**:
- 调用 `render()` 渲染按钮组
- 订阅语言变更：`localeManager.subscribe()`
- 订阅主题变更：`themeManager.subscribe()`

**返回**: Promise（异步方法，但当前实现是同步的）

#### `setTheme(theme: ThemeConfig): void`
设置主题（实现 `IBimComponent` 接口）

**参数**:
- `theme`: `ThemeConfig` - 全局主题配置

**功能**:
- 将主题颜色映射到按钮组颜色
- **只应用没有被用户自定义的颜色属性**
- 如果用户已自定义颜色，保持用户自定义

**主题颜色映射**:
- `theme.panelBackground` → `backgroundColor`
- `theme.componentBackground` → `btnBackgroundColor`
- `theme.componentHover` → `btnHoverColor`
- `theme.componentActive` → `btnActiveColor`
- `theme.icon` → `iconColor`
- `theme.iconActive` → `iconActiveColor`
- `theme.textSecondary` → `textColor`
- `theme.textPrimary` → `textActiveColor`

#### `setLocales(): void`
设置语言（实现 `IBimComponent` 接口）

**功能**:
- 调用 `render()` 重新渲染，更新所有按钮的标签文本

#### `setColors(colors: ButtonGroupColors): void`
直接设置颜色（强制覆盖）

**参数**:
- `colors`: `ButtonGroupColors` - 颜色配置对象

**功能**:
- 更新配置选项
- **标记这些颜色为自定义**，后续的 `setTheme()` 不会覆盖它们
- 应用样式

#### `setBackgroundColor(color: string): void`
设置背景颜色

**参数**:
- `color`: `string` - 背景颜色值

**功能**:
- 调用 `setColors({ backgroundColor: color })`

#### `addGroup(groupId: string, beforeGroupId?: string): void`
添加按钮组

**参数**:
- `groupId`: `string` - 组 ID（必须唯一）
- `beforeGroupId`: `string` (可选) - 在此组之前插入

**功能**:
- 创建新的按钮组
- 如果组已存在，忽略
- 如果指定了 `beforeGroupId`，在该组之前插入；否则追加到末尾

#### `addButton(config: ButtonConfig): void`
添加按钮

**参数**:
- `config`: `ButtonConfig` - 按钮配置

**功能**:
- 将按钮添加到指定组
- 如果指定了 `parentId`，将按钮添加为父按钮的子项（嵌套菜单）
- 如果未指定 `parentId`，将按钮添加到组的根级别

**按钮类型**:
- `type: 'button'` - 普通按钮
- `type: 'menu'` - 菜单按钮（有子项）

#### `render(): void`
渲染按钮组

**功能**:
- 清空容器
- 清空按钮引用映射
- 遍历所有组，渲染每个组
- 每个组渲染为一个 `.bim-btn-group-section` 元素

#### `updateButtonVisibility(id: string, visible: boolean): void`
更新按钮可见性

**参数**:
- `id`: `string` - 按钮 ID
- `visible`: `boolean` - 是否可见

**功能**:
- 更新 `options.visibility` 对象
- 调用 `render()` 重新渲染

#### `setShowLabel(show: boolean): void`
设置是否显示标签

**参数**:
- `show`: `boolean` - 是否显示标签

**功能**:
- 更新 `options.showLabel`
- 调用 `updateLabelsVisibility()` 更新所有按钮的标签显示状态

#### `destroy(): void`
销毁组件（实现 `IBimComponent` 接口）

**功能**:
- 取消语言和主题订阅
- 关闭下拉菜单（如果打开）
- 清空容器
- 清空按钮引用映射

### 2.3 受保护方法

#### `emit<K extends keyof EngineEvents>(event: K, payload: EngineEvents[K]): void`
发送事件

**功能**:
- 如果引擎已设置，通过引擎发送事件
- 如果引擎未设置，输出警告

### 2.4 私有方法（供理解实现细节）

#### `initContainer(): void`
初始化容器

**功能**:
- 清空容器内容
- 添加 `bim-btn-group-root` 类
- 根据 `direction` 添加 `dir-row` 或 `dir-column` 类
- 如果提供了 `className`，添加自定义类
- 调用 `updatePosition()` 更新位置

#### `updatePosition(): void`
更新容器位置

**功能**:
- 根据 `position` 选项设置容器位置
- 支持预设位置（如 'center', 'top-left' 等）或坐标对象 `{ x, y }`
- 如果 `position` 是 'static'，使用相对定位

**位置计算逻辑**:
- `static`: 使用相对定位，不设置绝对定位属性
- `{ x, y }`: 直接使用坐标值
- 预设位置: 使用 `margin: 20px` 和 `transform` 实现定位

#### `applyStyles(): void`
应用样式到容器

**功能**:
- 将配置的颜色值设置到 CSS 变量
- CSS 变量映射：
  - `backgroundColor` → `--bim-btn-group-section-bg`
  - `btnBackgroundColor` → `--bim-btn-bg`
  - `btnHoverColor` → `--bim-btn-hover-bg`
  - `btnActiveColor` → `--bim-btn-active-bg`
  - `iconColor` → `--bim-icon-color`
  - `iconActiveColor` → `--bim-icon-active-color`
  - `textColor` → `--bim-btn-text-color`
  - `textActiveColor` → `--bim-btn-text-active-color`

#### `renderGroup(group: ButtonGroup, index: number, total: number): HTMLElement`
渲染按钮组

**参数**:
- `group`: `ButtonGroup` - 按钮组对象
- `index`: `number` - 组索引
- `total`: `number` - 总组数

**返回**: 组元素

**功能**:
- 创建 `.bim-btn-group-section` 元素
- 如果不是最后一组，添加 `has-divider` 类（用于显示分隔线）
- 遍历组内的按钮，渲染每个可见的按钮

#### `renderButton(button: OptButton): HTMLElement`
渲染单个按钮

**参数**:
- `button`: `OptButton` - 按钮配置

**返回**: 按钮包装元素

**功能**:
- 创建 `.opt-btn-wrapper` 和 `.opt-btn` 元素
- 根据按钮的 `align` 或全局 `align` 设置布局方向
- 如果按钮是激活状态，添加 `active` 类
- 如果按钮是禁用状态，添加 `disabled` 类
- 如果按钮没有标签，添加 `no-label` 类
- 创建图标元素（`.opt-btn-icon`）
- 创建文字包装器（`.opt-btn-text-wrapper`），包含标签和箭头（如果有子项）
- 绑定点击、鼠标进入、鼠标离开事件
- 保存按钮引用到 `btnRefs` Map

#### `renderDropdownItem(button: OptButton): HTMLElement`
渲染下拉菜单项

**参数**:
- `button`: `OptButton` - 按钮配置

**返回**: 菜单项元素

**功能**:
- 创建 `.opt-btn-dropdown-item` 元素
- 根据按钮的 `align` 设置布局方向（默认 'horizontal'）
- 创建图标和标签
- 绑定点击事件

#### `handleClick(button: OptButton): void`
处理按钮点击

**功能**:
- 如果按钮是禁用状态，忽略
- 如果按钮没有子项：
  - 如果 `keepActive` 为 true，切换激活状态
  - 关闭下拉菜单
  - 调用 `onClick` 回调（如果存在）
- 如果按钮有子项，不处理（由鼠标悬停处理）

#### `handleMouseEnter(button: OptButton, btnEl: HTMLElement): void`
处理鼠标进入

**功能**:
- 清除悬停超时
- 如果按钮有子项，显示下拉菜单
- 如果按钮没有子项，关闭下拉菜单

#### `handleMouseLeave(): void`
处理鼠标离开

**功能**:
- 设置 200ms 延迟后关闭下拉菜单（防止鼠标移动到菜单时关闭）

#### `showDropdown(button: OptButton, btnEl: HTMLElement): void`
显示下拉菜单

**功能**:
- 关闭当前打开的下拉菜单
- 创建 `.opt-btn-dropdown` 元素
- 根据主按钮组的方向设置菜单的布局方向：
  - 如果主组是横向（`direction: 'row'`），菜单纵向排列
  - 如果主组是纵向（`direction: 'column'`），菜单横向排列
- 渲染所有可见的子按钮
- 计算菜单位置（根据 `expand` 选项）：
  - `up`: 向上展开，与按钮水平居中对齐
  - `down`: 向下展开，与按钮水平居中对齐
  - `right`: 向右展开，与按钮垂直居中对齐
  - `left`: 向左展开，与按钮垂直居中对齐
- 将菜单添加到 `document.body`（绝对定位）
- 绑定鼠标进入和离开事件（保持菜单打开）

#### `closeDropdown(): void`
关闭下拉菜单

**功能**:
- 移除下拉菜单元素
- 移除所有按钮箭头元素的 `rotated` 类

#### `updateButtonState(buttonId: string): void`
更新按钮状态

**功能**:
- 根据 `activeBtnIds` Set 更新按钮的 `active` 类

#### `findButton(buttons: OptButton[], id: string): OptButton | undefined`
查找按钮（递归）

**功能**:
- 在按钮数组中查找指定 ID 的按钮
- 递归查找子按钮

#### `findButtonById(id: string): OptButton | undefined`
根据 ID 查找按钮

**功能**:
- 在所有组中查找指定 ID 的按钮

#### `isVisible(id: string): boolean`
检查按钮是否可见

**功能**:
- 检查 `options.visibility` 对象
- 如果未设置或为 true，返回 true
- 如果设置为 false，返回 false

#### `getIcon(icon?: string): string`
获取图标 HTML

**功能**:
- 如果提供了图标，返回图标 HTML
- 否则返回默认图标

#### `updateLabelsVisibility(): void`
更新标签可见性

**功能**:
- 遍历所有按钮引用
- 根据 `showLabel` 选项和按钮是否有标签，更新 `no-label` 类

---

## 3. 分化组件说明

### 3.1 Toolbar

**文件路径**: `src/components/button-group/toolbar/index.ts`

**继承关系**: `Toolbar extends BimButtonGroup`

**特殊功能**:
- 预定义了底部工具栏的配置
- 自动加载默认按钮（首页、漫游、定位、设置、信息等）
- 使用固定的配置（底部居中、横向排列、图标在上、向上展开）

**实现方式**:
- 重写 `init()` 方法
- 先调用 `super.init()`
- 动态导入所有默认按钮配置
- 创建两个组（'group-1' 和 'group-2'）
- 添加所有默认按钮
- 调用 `render()` 渲染

**默认按钮列表**:
- `group-1`:
  - `home` - 首页按钮（通过工厂函数创建，注入 engine）
  - `walk-menu` - 漫游菜单
  - `walk-person` - 人视
  - `walk-bird` - 鸟瞰
  - `location` - 定位
- `group-2`:
  - `setting` - 设置
  - `info` - 信息

**与父类的差异**:
- 固定了配置选项（`position: 'bottom-center'`, `direction: 'row'`, `align: 'vertical'`, `expand: 'up'`）
- 自动加载默认按钮
- 其他功能完全继承自 `BimButtonGroup`

---

## 4. Manager API 文档

### 4.1 ButtonGroupManager 类

**文件路径**: `src/managers/button-group-manager.ts`

**继承关系**: `ButtonGroupManager extends BimComponent`

#### 构造函数

```typescript
constructor(engine: BimEngine, container: HTMLElement)
```

**参数**:
- `engine`: `BimEngine` - 引擎实例
- `container`: `HTMLElement` - 按钮组挂载的目标容器

#### 公共方法

##### `create(id: string, options: Omit<ButtonGroupOptions, 'container'>): BimButtonGroup`
创建按钮组

**参数**:
- `id`: `string` - 按钮组唯一标识
- `options`: `Omit<ButtonGroupOptions, 'container'>` - 配置选项（不需要传 container）

**返回**: `BimButtonGroup` 实例

**功能**:
- 自动使用 Manager 绑定的容器
- 创建 `BimButtonGroup` 实例
- 注入引擎实例
- 调用 `init()` 初始化
- 将按钮组保存到 Map 中

##### `get(id: string): BimButtonGroup | undefined`
获取按钮组

**参数**:
- `id`: `string` - 按钮组 ID

**返回**: `BimButtonGroup` 实例或 undefined

##### `updateTheme(theme: ThemeConfig): void`
更新所有按钮组的主题

**参数**:
- `theme`: `ThemeConfig` - 主题配置

##### `destroy(): void`
销毁管理器

**功能**:
- 销毁所有按钮组
- 清空 Map

### 4.2 ToolbarManager 类

**文件路径**: `src/managers/toolbar-manager.ts`

**继承关系**: `ToolbarManager extends BimComponent`

#### 构造函数

```typescript
constructor(engine: BimEngine, container: HTMLElement)
```

**参数**:
- `engine`: `BimEngine` - 引擎实例
- `container`: `HTMLElement` - 工具栏挂载的目标容器

**行为**:
- 自动调用 `init()` 创建工具栏

#### 公共方法

##### `updateTheme(theme: ThemeConfig): void`
更新工具栏主题

##### `refresh(): void`
刷新工具栏

**功能**:
- 调用工具栏的 `render()` 方法重新渲染

##### `addGroup(groupId: string, beforeGroupId?: string): void`
添加按钮组

**功能**:
- 转发到工具栏的 `addGroup()` 方法
- 自动调用 `render()` 重新渲染

##### `addButton(config: ButtonConfig): void`
添加按钮

**功能**:
- 转发到工具栏的 `addButton()` 方法
- 自动调用 `render()` 重新渲染

##### `setButtonVisibility(id: string, v: boolean): void`
设置按钮可见性

**功能**:
- 转发到工具栏的 `updateButtonVisibility()` 方法

##### `setShowLabel(show: boolean): void`
设置是否显示标签

**功能**:
- 转发到工具栏的 `setShowLabel()` 方法

##### `setVisible(visible: boolean): void`
设置工具栏可见性

**功能**:
- 通过设置容器的 `visibility` CSS 属性控制显示/隐藏

##### `setBackgroundColor(color: string): void`
设置背景颜色

**功能**:
- 转发到工具栏的 `setBackgroundColor()` 方法

##### `setColors(colors: ButtonGroupColors): void`
设置颜色

**功能**:
- 转发到工具栏的 `setColors()` 方法

##### `destroy(): void`
销毁管理器

**功能**:
- 销毁工具栏实例

---

## 5. UI 详细描述

### 5.1 DOM 结构

**完整 HTML 结构**:
```html
<div class="bim-btn-group-root [dir-row|dir-column] [static] [className]">
    <!-- 按钮组 1 -->
    <div class="bim-btn-group-section [has-divider]">
        <!-- 按钮包装器 -->
        <div class="opt-btn-wrapper">
            <div class="opt-btn [align-vertical|align-horizontal] [active] [disabled] [no-label]">
                <div class="opt-btn-icon">[图标 SVG]</div>
                <div class="opt-btn-text-wrapper">
                    <span class="opt-btn-label">标签文本</span>
                    [<span class="opt-btn-arrow [rotated]">▼</span>] <!-- 如果有子项 -->
                </div>
            </div>
        </div>
        <!-- 更多按钮... -->
    </div>
    
    <!-- 按钮组 2 -->
    <div class="bim-btn-group-section">
        <!-- 更多按钮... -->
    </div>
</div>

<!-- 下拉菜单（动态创建，添加到 document.body） -->
<div class="opt-btn-dropdown" style="[位置样式]">
    <div class="opt-btn-dropdown-item [align-horizontal|align-vertical]">
        <div class="opt-btn-icon">[图标 SVG]</div>
        <span class="opt-btn-dropdown-label">标签文本</span>
    </div>
    <!-- 更多菜单项... -->
</div>
```

### 5.2 CSS 类名和样式

#### `.bim-btn-group-root` (根容器)
- `display: flex` - Flex 布局
- `gap: 8px` - 组之间的间距
- `z-index: 1000` - 层级
- `position: absolute` - 绝对定位（除非是 static）
- `pointer-events: auto` - 确保可接收事件

#### `.bim-btn-group-root.static` (静态定位)
- `position: relative` - 相对定位
- 清除所有绝对定位属性

#### `.bim-btn-group-root.dir-row` (横向排列)
- `flex-direction: row` - 横向排列
- `align-items: center` - 垂直居中

#### `.bim-btn-group-root.dir-column` (纵向排列)
- `flex-direction: column` - 纵向排列
- `align-items: stretch` - 拉伸对齐

#### `.bim-btn-group-section` (按钮组)
- `display: flex` - Flex 布局
- `gap: 4px` - 按钮之间的间距
- `background-color: var(--bim-btn-group-section-bg)` - 背景色
- `border-radius: 6px` - 圆角
- `padding: 4px` - 内边距
- `box-shadow` - 阴影效果

#### `.opt-btn-wrapper` (按钮包装器)
- `position: relative` - 相对定位（为下拉菜单提供定位参考）

#### `.opt-btn` (按钮本体)
- `display: flex` - Flex 布局
- `cursor: pointer` - 指针光标
- `border-radius: 4px` - 圆角
- `transition: background-color 0.2s, color 0.2s` - 过渡动画
- `padding: 6px` - 内边距
- `align-items: center` - 垂直居中
- `justify-content: center` - 水平居中

#### `.opt-btn:hover` (按钮悬停)
- `background-color: var(--bim-btn-hover-bg)` - 悬停背景色

#### `.opt-btn.active` (按钮激活)
- `background-color: var(--bim-btn-active-bg)` - 激活背景色
- `color: var(--bim-btn-text-active-color)` - 激活文字颜色

#### `.opt-btn.disabled` (按钮禁用)
- `opacity: 0.5` - 半透明
- `cursor: not-allowed` - 禁止光标

#### `.opt-btn-icon` (图标)
- `width/height: var(--bim-icon-size)` - 图标尺寸
- `display: flex` - Flex 布局
- `align-items: center` - 垂直居中
- `justify-content: center` - 水平居中
- `color: var(--bim-icon-color)` - 图标颜色
- `flex-shrink: 0` - 不收缩

#### `.opt-btn-text-wrapper` (文字包装器)
- `display: flex` - Flex 布局
- `align-items: center` - 垂直居中
- `justify-content: center` - 水平居中
- `pointer-events: none` - 不接收鼠标事件

#### `.opt-btn-label` (标签)
- `display: inline` - 内联显示

#### `.opt-btn.no-label .opt-btn-label` (无标签时隐藏)
- `display: none` - 隐藏

#### `.opt-btn.align-vertical` (垂直布局 - 图标在上)
- `flex-direction: column` - 纵向排列
- `text-align: center` - 文字居中

#### `.opt-btn.align-horizontal` (水平布局 - 图标在左)
- `flex-direction: row` - 横向排列

#### `.opt-btn-arrow` (箭头)
- `font-size: 10px` - 字体大小
- `opacity: 0.6` - 半透明
- `transition: transform 0.2s` - 旋转过渡
- `margin-left: 4px` - 左边距

#### `.opt-btn-arrow.rotated` (箭头旋转)
- `transform: rotate(180deg)` - 旋转 180 度

#### `.opt-btn-dropdown` (下拉菜单)
- `position: absolute` - 绝对定位
- `background-color: var(--bim-toolbar-bg)` - 背景色
- `border-radius: 4px` - 圆角
- `padding: 4px` - 内边距
- `box-shadow` - 阴影效果
- `z-index: 1001` - 层级
- `display: flex` - Flex 布局
- `flex-direction: column` - 纵向排列（默认）
- `border: 1px solid rgba(255, 255, 255, 0.1)` - 边框
- `animation: dropdown-fade-in 0.2s` - 淡入动画

#### `.opt-btn-dropdown-item` (菜单项)
- `display: flex` - Flex 布局
- `align-items: center` - 垂直居中
- `padding: 8px 12px` - 内边距
- `cursor: pointer` - 指针光标
- `border-radius: 4px` - 圆角
- `color: var(--bim-btn-text-color)` - 文字颜色
- `transition: background 0.2s` - 背景过渡

#### `.opt-btn-dropdown-item:hover` (菜单项悬停)
- `background-color: var(--bim-btn-hover-bg)` - 悬停背景色
- `color: #fff` - 白色文字

### 5.3 CSS 变量

**定义位置**: 容器元素的内联样式

**变量列表**:
- `--bim-btn-group-section-bg`: 按钮组背景颜色
- `--bim-btn-bg`: 按钮背景颜色
- `--bim-btn-hover-bg`: 按钮悬停背景颜色
- `--bim-btn-active-bg`: 按钮激活背景颜色
- `--bim-icon-color`: 图标颜色
- `--bim-icon-active-color`: 图标激活颜色
- `--bim-btn-text-color`: 文字颜色
- `--bim-btn-text-active-color`: 文字激活颜色
- `--bim-toolbar-bg`: 工具栏背景颜色（用于下拉菜单）

### 5.4 交互行为

#### 按钮点击
- **触发条件**: 点击按钮元素
- **行为**:
  - 如果按钮是禁用状态，忽略
  - 如果按钮没有子项：
    - 如果 `keepActive` 为 true，切换激活状态
    - 关闭下拉菜单
    - 调用 `onClick` 回调
  - 如果按钮有子项，不处理（由鼠标悬停处理）

#### 鼠标悬停
- **触发条件**: 鼠标进入按钮
- **行为**:
  - 如果按钮有子项，显示下拉菜单
  - 如果按钮没有子项，关闭下拉菜单

#### 鼠标离开
- **触发条件**: 鼠标离开按钮或下拉菜单
- **行为**:
  - 延迟 200ms 后关闭下拉菜单（防止鼠标移动到菜单时关闭）

#### 下拉菜单显示
- **触发条件**: 鼠标悬停在有子项的按钮上
- **行为**:
  - 创建下拉菜单元素
  - 计算位置（根据 `expand` 选项）
  - 添加到 `document.body`
  - 显示淡入动画

#### 下拉菜单关闭
- **触发条件**: 
  - 鼠标离开按钮和菜单区域
  - 点击按钮（非菜单按钮）
- **行为**:
  - 移除下拉菜单元素
  - 移除箭头旋转状态

### 5.5 响应式行为

- 按钮组位置会根据容器尺寸自动调整（如果使用绝对定位）
- 下拉菜单位置会根据按钮位置和窗口尺寸自动计算
- 标签文本支持多语言切换
- 按钮可见性可以动态控制

---

## 6. 逻辑流程详细描述

### 6.1 初始化流程

1. **构造函数调用**:
   - 解析容器元素
   - 合并配置选项
   - 记录用户自定义的颜色属性
   - 调用 `initContainer()` 初始化容器
   - 调用 `applyStyles()` 应用样式

2. **init() 方法执行**:
   - 调用 `render()` 渲染按钮组
   - 订阅语言变更：`localeManager.subscribe()`
   - 订阅主题变更：`themeManager.subscribe()`

### 6.2 渲染流程

1. **render() 方法**:
   - 清空容器
   - 清空按钮引用映射
   - 遍历所有组，调用 `renderGroup()` 渲染每个组

2. **renderGroup() 方法**:
   - 创建组元素
   - 如果不是最后一组，添加分隔线类
   - 遍历组内按钮，调用 `renderButton()` 渲染每个可见按钮

3. **renderButton() 方法**:
   - 创建按钮包装器和按钮元素
   - 设置布局方向（根据按钮或全局配置）
   - 设置激活/禁用状态
   - 创建图标元素
   - 创建文字包装器（包含标签和箭头）
   - 绑定事件监听器
   - 保存按钮引用

### 6.3 事件处理流程

#### 按钮点击流程
1. 用户点击按钮 → `click` 事件
2. `handleClick()` 被调用
3. 检查按钮是否禁用
4. 如果按钮没有子项：
   - 如果 `keepActive` 为 true，切换激活状态
   - 更新按钮的 `active` 类
   - 关闭下拉菜单
   - 调用 `onClick` 回调

#### 下拉菜单显示流程
1. 鼠标进入按钮 → `mouseenter` 事件
2. `handleMouseEnter()` 被调用
3. 清除悬停超时
4. 如果按钮有子项，调用 `showDropdown()`
5. `showDropdown()` 执行：
   - 关闭当前打开的下拉菜单
   - 创建下拉菜单元素
   - 设置菜单布局方向（根据主组方向）
   - 渲染所有可见的子按钮
   - 计算菜单位置（根据 `expand` 选项）
   - 添加到 `document.body`
   - 绑定鼠标事件（保持菜单打开）

#### 下拉菜单关闭流程
1. 鼠标离开按钮或菜单 → `mouseleave` 事件
2. `handleMouseLeave()` 被调用
3. 设置 200ms 延迟
4. 延迟后调用 `closeDropdown()`
5. `closeDropdown()` 执行：
   - 移除下拉菜单元素
   - 移除箭头旋转状态

### 6.4 状态管理

#### 内部状态
- `groups`: 按钮组数组
- `activeBtnIds`: 激活按钮 ID 的 Set
- `btnRefs`: 按钮元素引用的 Map
- `dropdownElement`: 当前打开的下拉菜单元素
- `hoverTimeout`: 悬停超时的 ID
- `customColors`: 用户自定义颜色属性的 Set

#### 订阅管理
- `unsubscribeLocale`: 语言订阅取消函数
- `unsubscribeTheme`: 主题订阅取消函数

### 6.5 与其他组件的交互

- **与 ButtonGroupManager/ToolbarManager**: 通过 Manager 创建和管理
- **与 ThemeManager**: 订阅主题变更
- **与 LocaleManager**: 订阅语言变更
- **与 BimEngine**: 通过引擎发送事件（如果设置了引擎）

---

## 7. 国际化支持

### 7.1 使用的翻译键

- `button.label`: 按钮标签（每个按钮的 `label` 属性）

### 7.2 语言变更处理

- 组件订阅 `localeManager.subscribe()`
- 语言变更时，`setLocales()` 方法被调用
- 调用 `render()` 重新渲染，更新所有按钮的标签文本

### 7.3 实现细节

```typescript
public setLocales(): void {
    this.render(); // 重新渲染，标签会通过 t() 函数获取最新翻译
}

// 在 renderButton() 中
label.textContent = t(button.label);
```

---

## 8. 主题支持

### 8.1 使用的主题变量

- `theme.panelBackground` → `backgroundColor`
- `theme.componentBackground` → `btnBackgroundColor`
- `theme.componentHover` → `btnHoverColor`
- `theme.componentActive` → `btnActiveColor`
- `theme.icon` → `iconColor`
- `theme.iconActive` → `iconActiveColor`
- `theme.textSecondary` → `textColor`
- `theme.textPrimary` → `textActiveColor`

### 8.2 主题变更处理

- 组件订阅 `themeManager.subscribe()`
- 主题变更时，`setTheme()` 方法被调用
- **只应用没有被用户自定义的颜色属性**
- 如果用户已自定义颜色，保持用户自定义

### 8.3 自定义颜色保护机制

- 构造函数中记录用户自定义的颜色属性
- `setTheme()` 时只更新未自定义的颜色
- `setColors()` 时标记颜色为自定义

---

## 9. 使用示例

### 9.1 基本使用（通过 ButtonGroupManager）

```typescript
import { BimEngine } from 'bim-engine-sdk';

const engine = new BimEngine('container');

// 创建按钮组
const buttonGroup = engine.buttonGroup.create('my-group', {
    position: 'top-right',
    direction: 'row',
    showLabel: true
});

// 添加组
buttonGroup.addGroup('group-1');

// 添加按钮
buttonGroup.addButton({
    id: 'btn-1',
    groupId: 'group-1',
    type: 'button',
    label: 'toolbar.home',
    icon: '<svg>...</svg>',
    onClick: (button) => {
        console.log('按钮被点击:', button.id);
    }
});
```

### 9.2 使用工具栏（通过 ToolbarManager）

```typescript
// 工具栏已自动创建，直接使用
engine.toolbar.addButton({
    id: 'custom-btn',
    groupId: 'group-1',
    type: 'button',
    label: 'toolbar.custom',
    icon: '<svg>...</svg>',
    onClick: (button) => {
        console.log('自定义按钮被点击');
    }
});

// 控制按钮可见性
engine.toolbar.setButtonVisibility('location', false);

// 控制标签显示
engine.toolbar.setShowLabel(false);
```

### 9.3 使用嵌套菜单

```typescript
// 添加菜单按钮
buttonGroup.addButton({
    id: 'menu-btn',
    groupId: 'group-1',
    type: 'menu',
    label: 'toolbar.menu',
    icon: '<svg>...</svg>',
    children: [
        {
            id: 'sub-1',
            type: 'button',
            label: 'toolbar.sub1',
            onClick: () => console.log('子项 1')
        },
        {
            id: 'sub-2',
            type: 'button',
            label: 'toolbar.sub2',
            onClick: () => console.log('子项 2')
        }
    ]
});
```

---

## 10. 实现细节（供 AI 重现）

### 10.1 关键算法

#### 位置计算算法
```typescript
function calculatePosition(position, containerWidth, containerHeight) {
    const margin = 20;
    switch (position) {
        case 'top-left': return { top: margin, left: margin };
        case 'top-center': return { top: margin, left: '50%', transform: 'translateX(-50%)' };
        case 'top-right': return { top: margin, right: margin };
        // ... 其他位置
    }
}
```

#### 下拉菜单位置计算算法
```typescript
function calculateDropdownPosition(expand, buttonRect, dropdownRect) {
    switch (expand) {
        case 'up':
            return {
                bottom: window.innerHeight - buttonRect.top + 8,
                left: buttonRect.left + (buttonRect.width - dropdownRect.width) / 2
            };
        case 'down':
            return {
                top: buttonRect.bottom + 8,
                left: buttonRect.left + (buttonRect.width - dropdownRect.width) / 2
            };
        // ... 其他方向
    }
}
```

#### 激活状态切换算法
```typescript
function toggleActiveState(buttonId, activeBtnIds) {
    if (activeBtnIds.has(buttonId)) {
        activeBtnIds.delete(buttonId);
    } else {
        activeBtnIds.add(buttonId);
    }
}
```

### 10.2 性能优化点

1. **按钮引用缓存**:
   - 使用 `btnRefs` Map 缓存按钮元素引用
   - 避免重复查询 DOM

2. **延迟关闭下拉菜单**:
   - 使用 200ms 延迟，防止鼠标移动到菜单时关闭
   - 使用 `setTimeout` 和 `clearTimeout` 管理

3. **条件渲染**:
   - 只渲染可见的按钮（根据 `visibility` 选项）
   - 减少 DOM 操作

4. **CSS 变量**:
   - 使用 CSS 变量应用主题和颜色
   - 主题变更时无需重新渲染 DOM

### 10.3 注意事项和边界情况

1. **按钮 ID 唯一性**:
   - 按钮 ID 必须唯一
   - 如果重复，可能导致状态管理错误

2. **组 ID 唯一性**:
   - 组 ID 必须唯一
   - `addGroup()` 会检查重复

3. **嵌套菜单深度**:
   - 当前实现只支持一级嵌套（按钮 → 子项）
   - 不支持多级嵌套

4. **下拉菜单定位**:
   - 下拉菜单添加到 `document.body`，使用绝对定位
   - 需要根据按钮位置和窗口尺寸计算位置
   - 可能需要处理边界情况（菜单超出窗口）

5. **事件清理**:
   - 组件销毁时必须清理所有事件监听
   - 必须取消主题和语言订阅
   - 必须关闭下拉菜单

6. **翻译键处理**:
   - 标签可能是翻译键或普通文本
   - 只有翻译键才需要通过 `t()` 函数处理

7. **自定义颜色保护**:
   - 用户自定义的颜色不会被主题覆盖
   - 需要正确记录和管理自定义颜色

---

## 11. 类型定义

### 11.1 ButtonGroupOptions

```typescript
interface ButtonGroupOptions extends ButtonGroupColors {
    container: HTMLElement | string;    // 容器（必需）
    position?: GroupPosition;            // 位置（可选）
    direction?: GroupDirection;          // 排列方向（可选，默认 'row'）
    align?: ButtonAlign;                 // 按钮内部布局（可选，默认 'vertical'）
    expand?: ExpandDirection;            // 菜单展开方向（可选，默认 'down'）
    showLabel?: boolean;                 // 是否显示标签（可选，默认 true）
    visibility?: Record<string, boolean>; // 按钮可见性（可选）
    className?: string;                  // 自定义类名（可选）
}
```

### 11.2 ButtonConfig

```typescript
interface ButtonConfig {
    id: string;                          // 按钮 ID（必需，必须唯一）
    type: ButtonType;                    // 按钮类型（必需，'button' | 'menu'）
    label: string;                       // 标签（必需，支持翻译键）
    icon?: string;                       // 图标 SVG（可选）
    keepActive?: boolean;                // 是否保持激活状态（可选）
    disabled?: boolean;                  // 是否禁用（可选）
    onClick?: (button: OptButton) => void; // 点击回调（可选）
    children?: ButtonConfig[];           // 子项（可选，用于菜单）
    groupId?: string;                    // 所属组 ID（可选）
    parentId?: string;                   // 父按钮 ID（可选，用于嵌套）
    align?: ButtonAlign;                 // 按钮内部布局（可选）
    iconSize?: number;                   // 图标大小（可选，默认 32）
    minWidth?: number;                   // 最小宽度（可选，默认 50）
}
```

### 11.3 其他类型

```typescript
type ButtonType = 'button' | 'menu';
type GroupPosition = 'center' | 'top-left' | 'top-center' | 'top-right' 
    | 'left-center' | 'right-center' 
    | 'bottom-left' | 'bottom-center' | 'bottom-right'
    | { x: number; y: number } | 'static';
type GroupDirection = 'row' | 'column';
type ButtonAlign = 'vertical' | 'horizontal';
type ExpandDirection = 'up' | 'down' | 'left' | 'right';
```

---

## 12. 文件清单

### 12.1 相关文件

- `src/components/button-group/index.ts` - 主组件类
- `src/components/button-group/index.type.ts` - 类型定义
- `src/components/button-group/index.css` - 样式文件
- `src/components/button-group/toolbar/index.ts` - 工具栏（分化组件）
- `src/managers/button-group-manager.ts` - 通用按钮组管理器
- `src/managers/toolbar-manager.ts` - 工具栏管理器

### 12.2 依赖文件

- `src/types/component.ts` - IBimComponent 接口
- `src/themes/types.ts` - ThemeConfig 类型
- `src/services/theme.ts` - ThemeManager
- `src/services/locale.ts` - LocaleManager
- `src/types/events.ts` - EngineEvents 类型

---

## 13. 更新记录

| 日期 | 修改内容 | 修改人 |
|------|---------|--------|
| 2024-XX-XX | 初始创建 | AI Assistant |

---

**重要提醒**: 本文档必须与组件代码保持同步。任何组件修改都必须更新本文档！