785 lines
16 KiB
Markdown
785 lines
16 KiB
Markdown
# Components 模块文档
|
||
|
||
## 模块概述
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| **模块名** | components |
|
||
| **职责** | 提供 BIM SDK 的所有引擎组件（3D / 2D / 720）和 UI 组件 |
|
||
| **公开 API** | 3 个引擎组件 + 20+ UI 组件 |
|
||
| **状态** | ✅ 稳定 |
|
||
|
||
## 代码地图
|
||
|
||
```
|
||
src/components/
|
||
├── engine/ # 3D 引擎组件 (包装 iflow-engine-base)
|
||
├── engine-2d/ # 2D 图纸引擎组件 (包装 createEngine2d)
|
||
├── engine-720/ # 720° 全景引擎组件 (包装 createEngine720)
|
||
├── dialog/ # 通用弹窗组件
|
||
├── tree/ # 树形控件组件
|
||
├── menu/ # 菜单组件
|
||
├── button-group/ # 按钮组件
|
||
├── radial-toolbar/ # 径向工具栏组件
|
||
├── 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，提供模型加载、视角控制、测量功能。仅由 `BimEngine` 通过 `EngineManager` 使用。
|
||
|
||
### 配置
|
||
|
||
```typescript
|
||
interface EngineOptions {
|
||
container: HTMLElement;
|
||
backgroundColor?: number | string;
|
||
version?: 'v1' | 'v2';
|
||
showStats?: boolean;
|
||
showViewCube?: boolean;
|
||
}
|
||
```
|
||
|
||
### API
|
||
|
||
```typescript
|
||
class Engine implements IBimComponent {
|
||
init(): void;
|
||
loadModel(url: string, options?: ModelLoadOptions): void;
|
||
CameraGoHome(): void;
|
||
activateMeasure(mode: MeasureMode): void;
|
||
deactivateMeasure(): void;
|
||
onRawEvent(event: string, handler: Function): void;
|
||
offRawEvent(event: string, handler: Function): void;
|
||
setTheme(theme: ThemeConfig): void;
|
||
destroy(): void;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Engine2d（2D 图纸引擎组件）
|
||
|
||
### 概述
|
||
|
||
包装 `createEngine2d()`，提供 2D CAD/DWG 图纸加载与查看。由 `BimEngine2d` 直接使用，跳过 Manager 层。
|
||
|
||
### 配置
|
||
|
||
```typescript
|
||
interface Engine2dOptions {
|
||
container: HTMLElement;
|
||
backgroundColor?: number;
|
||
gridEnabled?: boolean;
|
||
axesEnabled?: boolean;
|
||
selectionColor?: number;
|
||
highlightColor?: number;
|
||
enablePerformanceMonitoring?: boolean;
|
||
}
|
||
```
|
||
|
||
### API
|
||
|
||
```typescript
|
||
class Engine2d implements IBimComponent {
|
||
init(): void;
|
||
loadDrawing(url: string, options?: DrawingLoadOptions): Promise<void>;
|
||
getLayers(): Drawing2dLayer[];
|
||
setLayerVisible(name: string, visible: boolean): void;
|
||
resetView(): void;
|
||
fitToView(): void;
|
||
setZoom(zoom: number): void;
|
||
getZoom(): number;
|
||
onRawEvent(event: string, handler: Function): void;
|
||
offRawEvent(event: string, handler: Function): void;
|
||
setTheme(theme: ThemeConfig): void;
|
||
destroy(): void;
|
||
}
|
||
```
|
||
|
||
### 相关类型
|
||
|
||
```typescript
|
||
interface DrawingLoadOptions {
|
||
chunkSize?: number;
|
||
enableChunkedLoading?: boolean;
|
||
enableValidation?: boolean;
|
||
}
|
||
|
||
interface Drawing2dLayer {
|
||
name: string;
|
||
visible: boolean;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Engine720（720° 全景引擎组件）
|
||
|
||
### 概述
|
||
|
||
包装 `createEngine720()`，提供 720° 全景图加载与查看。由 `BimEngine720` 直接使用，跳过 Manager 层。
|
||
|
||
### 配置
|
||
|
||
```typescript
|
||
interface Engine720Options {
|
||
container: HTMLElement;
|
||
fov?: number; // 默认 75
|
||
enableZoom?: boolean; // 默认 true
|
||
enableRotate?: boolean; // 默认 true
|
||
sphereRadius?: number; // 默认 500
|
||
rotateSpeed?: number;
|
||
zoomSpeed?: number;
|
||
enableDamping?: boolean;
|
||
dampingFactor?: number;
|
||
minFov?: number;
|
||
maxFov?: number;
|
||
}
|
||
```
|
||
|
||
### API
|
||
|
||
```typescript
|
||
class Engine720 implements IBimComponent {
|
||
init(): void;
|
||
loadPanorama(url: string, options?: PanoramaLoadOptions): Promise<void>;
|
||
preloadPanoramas(urls: string[]): Promise<void>;
|
||
setFov(fov: number): void;
|
||
getFov(): number;
|
||
lookAt(phi: number, theta: number, animated?: boolean): void;
|
||
resetView(): void;
|
||
onRawEvent(event: string, handler: Function): void;
|
||
offRawEvent(event: string, handler: Function): void;
|
||
setTheme(theme: ThemeConfig): void;
|
||
destroy(): void;
|
||
}
|
||
```
|
||
|
||
### 相关类型
|
||
|
||
```typescript
|
||
interface PanoramaLoadOptions {
|
||
timeout?: number;
|
||
}
|
||
|
||
interface PanoramaAnnotation {
|
||
id: string;
|
||
phi?: number;
|
||
theta?: number;
|
||
text?: string;
|
||
data?: any;
|
||
}
|
||
```
|
||
|
||
## 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;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## RadialToolbar（径向工具栏组件）
|
||
|
||
### 概述
|
||
|
||
圆形径向菜单组件，用于替代传统线性工具栏。支持多环布局、扇形展开、hover 触发和 toggle 状态。
|
||
|
||
### 配置
|
||
|
||
```typescript
|
||
interface RadialToolbarOptions {
|
||
container: HTMLElement;
|
||
items?: RadialMenuItem[];
|
||
mainButtonIcon?: string;
|
||
mainButtonLabel?: string;
|
||
onMainButtonClick?: () => void;
|
||
itemsPerRing?: number;
|
||
closeDelay?: number;
|
||
}
|
||
|
||
interface RadialMenuItem {
|
||
id: string;
|
||
label: string;
|
||
/** 直接显示的文本（优先级高于 label 的国际化翻译） */
|
||
title?: string;
|
||
icon?: string;
|
||
onClick?: (item: RadialMenuItem) => void;
|
||
isToggle?: boolean;
|
||
isActive?: boolean;
|
||
onToggle?: (nextActive: boolean, item: RadialMenuItem) => void;
|
||
}
|
||
```
|
||
|
||
### API
|
||
|
||
```typescript
|
||
class RadialToolbar {
|
||
init(): void;
|
||
addItem(item: RadialMenuItem): void;
|
||
setItemActive(id: string, active: boolean): void;
|
||
setTheme(theme: ThemeConfig): void;
|
||
setLocales(): void;
|
||
destroy(): void;
|
||
}
|
||
```
|
||
|
||
### 使用说明
|
||
|
||
- `label`：国际化键名（如 `'toolbar.home'`），SDK 内置按钮使用
|
||
- `title`：直接显示文本，优先级高于 `label`，适合外部动态添加按钮
|
||
- `itemsPerRing`：每环最多显示的按钮数，超出自动进入下一环
|
||
- `isToggle`：是否为切换按钮，配合 `onToggle` 和 `setItemActive` 使用
|
||
|
||
### 布局说明
|
||
|
||
**角度计算**：按钮中心均匀分布在扇形范围内（默认 180°~270°），通过 `(index + 0.5) / count` 计算位置，确保完整填满扇形而不贴边。
|
||
|
||
**环容量**：每环按钮数量写死在 `src/components/radial-toolbar/index.ts` 中（当前为 `[4, 6, 8]`），如需调整直接修改源码。
|
||
|
||
### 与 BottomDock 联动
|
||
|
||
`RadialToolbarManager` 会自动监听 `BottomDock` 状态变化，同步按钮激活状态：
|
||
|
||
```typescript
|
||
// 点击径向工具栏按钮展开/收起 Dock
|
||
onToggle: (active) => {
|
||
if (active) {
|
||
bimEngine.bottomDock?.open('measure');
|
||
} else {
|
||
bimEngine.bottomDock?.close('measure');
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 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-03-10
|