606 lines
12 KiB
Markdown
606 lines
12 KiB
Markdown
# 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
|