feat: upgrade iflow-engine-base to v1.0.5, add pause/resume rendering API
- Update iflow-engine-base from 1.0.1 to 1.0.5 - Change default engine version from v1 to v2 - Add pauseRendering() and resumeRendering() methods - Add switch model feature in demos - Update model URLs in demos - Add new documentation files
This commit is contained in:
yuding
605
docs/MODULES/components.md
Normal file
605
docs/MODULES/components.md
Normal file
@@ -0,0 +1,605 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user