bim_engine/docs/MODULES/components.md

# Components 模块文档

## 模块概述

| 项目 | 内容 |
|------|------|
| **模块名** | components |
| **职责** | 提供 BIM 3D 引擎 SDK 的所有 UI 组件 |
| **公开 API** | 20+ 个组件类 |
| **状态** | ✅ 稳定 |

## 代码地图

```
src/components/
├── engine/                      # 3D 引擎组件
├── dialog/                      # 通用弹窗组件
├── tree/                        # 树形控件组件
├── menu/                        # 菜单组件
├── button-group/                # 按钮组件
├── collapse/                    # 折叠面板组件
├── tab/                         # 标签页组件
├── description/                 # 描述列表组件
├── measure-panel/               # 测量面板组件
├── section-plane-panel/         # 平面剖切面板
├── section-axis-panel/          # 轴向剖切面板
├── section-box-panel/           # 剖切盒面板
├── walk-control-panel/          # 漫游控制面板
├── walk-path-panel/             # 漫游路径面板
├── walk-plan-view-panel/        # 漫游平面图面板
├── right-key/                   # 右键菜单组件
└── map-panel/                   # 地图面板组件
```

## 组件接口

所有组件实现统一接口：

```typescript
interface IBimComponent {
  element: HTMLElement;
  init(): void;
  setTheme(theme: ThemeConfig): void;
  setLocales?(): void;
  destroy(): void;
}
```

---

## Engine（3D 引擎组件）

### 概述

包装第三方 3D 引擎 SDK，提供模型加载、视角控制、测量功能。

### 配置

```typescript
interface EngineOptions {
  container: HTMLElement;
  backgroundColor?: number | string;
  version?: 'v1' | 'v2';
  showStats?: boolean;
  showViewCube?: boolean;
}
```

### API

```typescript
class Engine {
  init(): void;
  loadModel(url: string, options?: ModelLoadOptions): void;
  CameraGoHome(): void;
  getEngine(): any;
  activateMeasure(mode: MeasureMode): void;
  deactivateMeasure(): void;
  setTheme(theme: ThemeConfig): void;
  destroy(): void;
}
```

### 测量模式

| 模式 | 说明 |
|------|------|
| `distance` | 距离测量 |
| `minDistance` | 最小距离 |
| `angle` | 角度测量 |
| `elevation` | 标高测量 |
| `volume` | 体积测量 |
| `laserDistance` | 激光测距 |
| `slope` | 坡度测量 |
| `spaceVolume` | 空间体积 |

---

## BimDialog（通用弹窗组件）

### 概述

通用弹窗容器，支持拖拽、缩放、自定义内容。

### 配置

```typescript
interface DialogOptions {
  container: HTMLElement;
  title?: string;
  content?: HTMLElement | string;
  width?: number | string;
  height?: number | string;
  position?: DialogPosition;
  draggable?: boolean;
  resizable?: boolean;
  minWidth?: number;
  minHeight?: number;
  onOpen?: () => void;
  onClose?: () => void;
  backgroundColor?: string;
  headerBackgroundColor?: string;
  titleColor?: string;
  textColor?: string;
  borderColor?: string;
}

type DialogPosition =
  | 'center'
  | 'top-left' | 'top-center' | 'top-right'
  | 'left-center' | 'right-center'
  | 'bottom-left' | 'bottom-center' | 'bottom-right'
  | { x: number; y: number };
```

### API

```typescript
class BimDialog {
  init(): void;
  setContent(content: HTMLElement | string): void;
  fitWidth(recenter?: boolean): void;
  fitHeight(recenter?: boolean): void;
  close(): void;
  setTheme(theme: ThemeConfig): void;
  destroy(): void;
}
```

---

## BimTree（树形控件组件）

### 概述

递归树形结构展示，支持复选框、搜索、展开折叠。

### 配置

```typescript
interface TreeOptions {
  data: TreeNodeConfig[];
  checkable?: boolean;
  checkStrictly?: boolean;
  indent?: number;
  defaultExpandAll?: boolean;
  enableSearch?: boolean;
  searchPlaceholder?: string;
  onNodeCheck?: (node: BimTreeNode) => void;
  onNodeSelect?: (node: BimTreeNode) => void;
  onNodeExpand?: (node: BimTreeNode) => void;
}

interface TreeNodeConfig {
  id: string;
  label: string;
  icon?: string;
  children?: TreeNodeConfig[];
  expanded?: boolean;
  checked?: boolean;
  disabled?: boolean;
  data?: any;
}
```

### API

```typescript
class BimTree {
  init(): void;
  getNode(id: string): BimTreeNode | undefined;
  checkNode(id: string, checked: boolean): void;
  expandAll(expanded: boolean): void;
  getCheckedNodes(includeHalf?: boolean): TreeNodeConfig[];
  revealNode(node: BimTreeNode): void;
  setTheme(theme: ThemeConfig): void;
  destroy(): void;
}
```

---

## BimMenu（菜单组件）

### 概述

菜单列表渲染，支持分组、排序、递归子菜单。

### 配置

```typescript
interface MenuOptions {
  items: MenuItemConfig[];
  groupOrder?: string[];
}

interface MenuItemConfig {
  id: string;
  label: string;
  icon?: string;
  group?: string;
  order?: number;
  visible?: boolean;
  disabled?: boolean;
  children?: MenuItemConfig[];
  onClick?: () => void;
}
```

### API

```typescript
class BimMenu {
  init(): void;
  getElement(): HTMLElement;
  setTheme(theme: ThemeConfig): void;
  destroy(): void;
}
```

---

## BimButtonGroup（按钮组件）

### 概述

分组按钮布局，支持下拉菜单、互斥激活。

### 配置

```typescript
interface ButtonGroupOptions {
  container: HTMLElement | string;
  position?: GroupPosition;
  direction?: 'row' | 'column';
  align?: 'vertical' | 'horizontal';
  expand?: 'up' | 'down' | 'left' | 'right';
  type?: 'default' | 'glass-pill';
  showLabel?: boolean;
  visibility?: Record<string, boolean>;
  backgroundColor?: string;
  btnBackgroundColor?: string;
  btnHoverColor?: string;
  btnActiveColor?: string;
  iconColor?: string;
  iconActiveColor?: string;
  textColor?: string;
  textActiveColor?: string;
}

interface ButtonConfig {
  id: string;
  type: 'button' | 'menu';
  label: string;
  icon?: string;
  keepActive?: boolean;
  exclusive?: boolean;
  isActive?: boolean;
  disabled?: boolean;
  onClick?: (button: any) => void;
  children?: ButtonConfig[];
  groupId?: string;
  parentId?: string;
  align?: 'vertical' | 'horizontal';
  iconSize?: number;
  minWidth?: number;
}
```

### API

```typescript
class BimButtonGroup {
  init(): Promise<void>;
  addGroup(groupId: string, beforeGroupId?: string): void;
  addButton(config: ButtonConfig): void;
  setBtnActive(id: string, active?: boolean): void;
  setShowLabel(show: boolean): void;
  updateButtonVisibility(id: string, visible: boolean): void;
  setColors(colors: ButtonGroupColors): void;
  setTheme(theme: ThemeConfig): void;
  destroy(): void;
}
```

---

## BimCollapse（折叠面板组件）

### 概述

可折叠/展开的面板组件，支持手风琴模式。

### 配置

```typescript
interface CollapseOptions {
  container: HTMLElement | string;
  items: CollapseItemConfig[];
  activeIds?: string[];
  accordion?: boolean;
  bordered?: boolean;
  ghost?: boolean;
  className?: string;
  onChange?: (activeIds: string[]) => void;
}

interface CollapseItemConfig {
  id: string;
  title: string;
  content: HTMLElement | string;
  icon?: string;
  extra?: HTMLElement | string;
  disabled?: boolean;
  className?: string;
}
```

### API

```typescript
class BimCollapse {
  init(): void;
  toggleItem(id: string): void;
  setTheme(theme: ThemeConfig): void;
  destroy(): void;
}
```

---

## BimTab（标签页组件）

### 概述

标签页容器，支持图标、禁用态。

### 配置

```typescript
interface TabOptions {
  container: HTMLElement;
  tabs: TabItem[];
  activeId?: string;
  onChange?: (tabId: string, tab: TabItem) => void;
}

interface TabItem {
  id: string;
  title: string;
  icon?: string;
  content: HTMLElement | string;
  disabled?: boolean;
}
```

### API

```typescript
class BimTab {
  init(): void;
  activateTab(tabId: string): void;
  setTheme(theme: ThemeConfig): void;
  setLocales(): void;
  destroy(): void;
}
```

---

## BimDescription（描述列表组件）

### 概述

Key-Value 数据展示组件。

### 配置

```typescript
interface DescriptionOptions {
  container: HTMLElement | string;
  items: DescriptionItem[];
  bordered?: boolean;
  className?: string;
  fontSize?: string;
  labelColor?: string;
  valueColor?: string;
  labelWidth?: string;
  labelPadding?: string;
  valuePadding?: string;
}

interface DescriptionItem {
  label: string;
  value: HTMLElement | string;
  labelColor?: string;
  valueColor?: string;
  className?: string;
}
```

### API

```typescript
class BimDescription {
  init(): void;
  setItems(items: DescriptionItem[]): void;
  setTheme(theme: ThemeConfig): void;
  destroy(): void;
}
```

---

## MeasurePanel（测量面板组件）

### 概述

测量面板 UI，支持 8 种测量类型。

### 配置

```typescript
interface MeasurePanelOptions {
  defaultMode?: MeasureMode;
  defaultExpanded?: boolean;
  onModeChange?: (mode: MeasureMode) => void;
  onExpandedChange?: (expanded: boolean) => void;
  onClearAll?: () => void;
  onSettings?: () => void;
}
```

### API

```typescript
class MeasurePanel {
  init(): void;
  getActiveMode(): MeasureMode;
  switchMode(mode: MeasureMode): void;
  setResult(result: MeasureResult | null): void;
  clearAll(): void;
  getConfig(): MeasureConfig;
  setConfig(partial: Partial<MeasureConfig>, persist?: boolean): void;
  setExpanded(expanded: boolean): void;
  getExpanded(): boolean;
  setTheme(theme: ThemeConfig): void;
  destroy(): void;
}
```

---

## SectionPlanePanel（平面剖切面板）

### 概述

平面剖切控制面板。

### 配置

```typescript
interface SectionPlanePanelOptions {
  onHide?: () => void;
  onReverse?: () => void;
  onReset?: () => void;
}
```

### API

```typescript
class SectionPlanePanel {
  init(): void;
  setTheme(theme: ThemeConfig): void;
  setLocales(): void;
  destroy(): void;
}
```

---

## SectionAxisPanel（轴向剖切面板）

### 概述

X/Y/Z 轴向剖切控制面板。

### 配置

```typescript
interface SectionAxisPanelOptions {
  defaultAxis?: 'x' | 'y' | 'z';
  onHideToggle?: (isHidden: boolean) => void;
  onReverse?: () => void;
  onAxisChange?: (axis: 'x' | 'y' | 'z') => void;
}
```

---

## SectionBoxPanel（剖切盒面板）

### 概述

六面体剖切盒控制面板。

### 配置

```typescript
interface SectionBoxPanelOptions {
  onHideToggle?: (isHidden: boolean) => void;
  onReverseToggle?: (isReversed: boolean) => void;
  onFitToModel?: () => void;
  onReset?: () => void;
  onRangeChange?: (axis: string, value: number) => void;
}
```

---

## WalkControlPanel（漫游控制面板）

### 概述

漫游模式控制面板。

### 配置

```typescript
interface WalkControlPanelOptions {
  defaultSpeed?: number;
  defaultGravity?: boolean;
  defaultCollision?: boolean;
  defaultCharacterModel?: 'construction-worker' | 'office-male';
  defaultWalkMode?: 'walk' | 'run';
  onPlanViewToggle?: (active: boolean) => void;
  onPathModeToggle?: (active: boolean) => void;
  onWalkModeToggle?: (active: boolean) => void;
  onSpeedChange?: (speed: number) => void;
  onGravityToggle?: (enabled: boolean) => void;
  onCollisionToggle?: (enabled: boolean) => void;
  onCharacterModelChange?: (model: string) => void;
  onWalkModeChange?: (mode: string) => void;
  onExit?: () => void;
}
```

### API

```typescript
class WalkControlPanel {
  init(): void;
  getState(): WalkControlState;
  setPlanViewActive(active: boolean): void;
  setPathModeActive(active: boolean): void;
  setTheme(theme: ThemeConfig): void;
  setLocales(): void;
  destroy(): void;
}

interface WalkControlState {
  mode: 'none' | 'path' | 'walk';
  isPlanViewActive: boolean;
  speed: number;
  gravity: boolean;
  collision: boolean;
  characterModel: string;
  walkMode: string;
}
```

---

## 依赖关系

所有组件依赖:
- `ThemeManager` (主题)
- `LocaleManager` (国际化，部分组件)

组件不直接依赖 Manager，由 Manager 创建和管理组件实例。

---

**文档生成时间**: 2026-01-23