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
122
docs/MODULES/_INDEX.md
Normal file
122
docs/MODULES/_INDEX.md
Normal file
@@ -0,0 +1,122 @@
|
||||
# 模块文档索引
|
||||
|
||||
## 模块列表
|
||||
|
||||
| 模块 | 路径 | 职责 | 文档 |
|
||||
|------|------|------|------|
|
||||
| **core** | `src/core/` | 核心基础设施：事件系统、管理器基类、注册表 | [core.md](core.md) |
|
||||
| **managers** | `src/managers/` | 15 个管理器，处理业务逻辑和组件协调 | [managers.md](managers.md) |
|
||||
| **components** | `src/components/` | 20+ 个 UI 组件 | [components.md](components.md) |
|
||||
| **services** | `src/services/` | 全局服务：国际化、主题管理 | [services.md](services.md) |
|
||||
|
||||
## Core 模块
|
||||
|
||||
提供 SDK 的核心基础设施。
|
||||
|
||||
| 类 | 文件 | 职责 |
|
||||
|-----|------|------|
|
||||
| EventEmitter | `event-emitter.ts` | 事件发布/订阅系统 |
|
||||
| ManagerRegistry | `manager-registry.ts` | 全局单例注册表 |
|
||||
| BaseManager | `base-manager.ts` | Manager 抽象基类 |
|
||||
| BaseDialogManager | `base-dialog-manager.ts` | 对话框 Manager 基类 |
|
||||
|
||||
[查看详情 →](core.md)
|
||||
|
||||
## Managers 模块
|
||||
|
||||
处理业务逻辑，协调组件交互。
|
||||
|
||||
### 核心管理器
|
||||
|
||||
| 管理器 | 职责 |
|
||||
|--------|------|
|
||||
| EngineManager | 3D 引擎管理 |
|
||||
| ToolbarManager | 工具栏管理 |
|
||||
| DialogManager | 对话框管理 |
|
||||
| ButtonGroupManager | 按钮组管理 |
|
||||
| RightKeyManager | 右键菜单管理 |
|
||||
|
||||
### 功能管理器
|
||||
|
||||
| 管理器 | 职责 |
|
||||
|--------|------|
|
||||
| PropertyPanelManager | 属性面板管理 |
|
||||
| ConstructTreeManagerBtn | 构件树管理 |
|
||||
| MeasureDialogManager | 测量对话框管理 |
|
||||
| SectionPlaneDialogManager | 平面剖切管理 |
|
||||
| SectionAxisDialogManager | 轴向剖切管理 |
|
||||
| SectionBoxDialogManager | 剖切盒管理 |
|
||||
| WalkControlManager | 漫游控制管理 |
|
||||
| WalkPathDialogManager | 漫游路径管理 |
|
||||
| WalkPlanViewDialogManager | 漫游平面图管理 |
|
||||
| MapDialogManager | 地图管理 |
|
||||
|
||||
[查看详情 →](managers.md)
|
||||
|
||||
## Components 模块
|
||||
|
||||
纯 UI 组件，不包含业务逻辑。
|
||||
|
||||
### 核心组件
|
||||
|
||||
| 组件 | 职责 |
|
||||
|------|------|
|
||||
| Engine | 3D 视口容器 |
|
||||
| BimDialog | 通用对话框 |
|
||||
| BimTree | 树形控件 |
|
||||
| BimMenu | 菜单组件 |
|
||||
| BimButtonGroup | 按钮组 |
|
||||
|
||||
### 面板组件
|
||||
|
||||
| 组件 | 职责 |
|
||||
|------|------|
|
||||
| MeasurePanel | 测量面板 |
|
||||
| SectionPlanePanel | 平面剖切面板 |
|
||||
| SectionAxisPanel | 轴向剖切面板 |
|
||||
| SectionBoxPanel | 剖切盒面板 |
|
||||
| WalkControlPanel | 漫游控制面板 |
|
||||
| WalkPathPanel | 漫游路径面板 |
|
||||
| WalkPlanViewPanel | 漫游平面图面板 |
|
||||
| MapPanel | 地图面板 |
|
||||
|
||||
### 展示组件
|
||||
|
||||
| 组件 | 职责 |
|
||||
|------|------|
|
||||
| BimCollapse | 折叠面板 |
|
||||
| BimTab | 标签页 |
|
||||
| BimDescription | 描述列表 |
|
||||
|
||||
[查看详情 →](components.md)
|
||||
|
||||
## Services 模块
|
||||
|
||||
提供全局服务。
|
||||
|
||||
| 服务 | 职责 |
|
||||
|------|------|
|
||||
| LocaleManager | 国际化服务，多语言支持 |
|
||||
| ThemeManager | 主题管理服务，明暗切换 |
|
||||
|
||||
[查看详情 →](services.md)
|
||||
|
||||
## 类型定义
|
||||
|
||||
| 文件 | 内容 |
|
||||
|------|------|
|
||||
| `types/component.ts` | 组件接口 IBimComponent |
|
||||
| `types/events.ts` | 事件类型 EngineEvents |
|
||||
| `types/measure.ts` | 测量类型定义 |
|
||||
| `locales/types.ts` | 国际化类型 |
|
||||
| `themes/types.ts` | 主题配置类型 |
|
||||
|
||||
## 工具函数
|
||||
|
||||
| 文件 | 内容 |
|
||||
|------|------|
|
||||
| `utils/icon-manager.ts` | 图标管理器，提供 40+ SVG 图标 |
|
||||
|
||||
---
|
||||
|
||||
**文档生成时间**: 2026-01-23
|
||||
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
|
||||
386
docs/MODULES/core.md
Normal file
386
docs/MODULES/core.md
Normal file
@@ -0,0 +1,386 @@
|
||||
# Core 模块文档
|
||||
|
||||
## 模块概述
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **模块名** | core |
|
||||
| **职责** | 提供 SDK 的核心基础设施：事件发射、Manager 注册表、Manager 生命周期管理 |
|
||||
| **公开 API** | 4 个类 |
|
||||
| **状态** | ✅ 稳定 |
|
||||
|
||||
## 代码地图
|
||||
|
||||
```
|
||||
src/core/
|
||||
├── event-emitter.ts # 事件发射器
|
||||
├── manager-registry.ts # Manager 注册表（单例）
|
||||
├── base-manager.ts # Manager 抽象基类
|
||||
└── base-dialog-manager.ts # 对话框 Manager 基类
|
||||
```
|
||||
|
||||
| 文件 | 行数 | 职责 | 导出 |
|
||||
|------|------|------|------|
|
||||
| `event-emitter.ts` | 70 | 发布/订阅事件系统 | `EventEmitter` |
|
||||
| `manager-registry.ts` | 127 | 全局单例注册表 | `ManagerRegistry` |
|
||||
| `base-manager.ts` | 57 | Manager 基类 | `BaseManager` |
|
||||
| `base-dialog-manager.ts` | 145 | 对话框 Manager 基类 | `BaseDialogManager` |
|
||||
|
||||
## 架构设计
|
||||
|
||||
### 类关系图
|
||||
|
||||
```
|
||||
EventEmitter
|
||||
↑ (组合)
|
||||
ManagerRegistry (单例)
|
||||
↑ (访问)
|
||||
BaseManager (抽象类)
|
||||
↑ (继承)
|
||||
BaseDialogManager (抽象类)
|
||||
↑ (继承)
|
||||
具体 Manager 类
|
||||
```
|
||||
|
||||
### 设计模式
|
||||
|
||||
| 模式 | 应用 | 说明 |
|
||||
|------|------|------|
|
||||
| 单例模式 | ManagerRegistry | 全局唯一实例 |
|
||||
| 发布/订阅 | EventEmitter | 解耦事件通信 |
|
||||
| 模板方法 | BaseDialogManager | 定义对话框生命周期 |
|
||||
|
||||
---
|
||||
|
||||
## EventEmitter
|
||||
|
||||
### 概述
|
||||
|
||||
轻量级事件发射器，提供发布/订阅功能。
|
||||
|
||||
### API
|
||||
|
||||
```typescript
|
||||
class EventEmitter {
|
||||
// 订阅事件，返回取消订阅函数
|
||||
on(event: string, listener: (payload: any) => void): () => void;
|
||||
|
||||
// 取消订阅
|
||||
off(event: string, listener: (payload: any) => void): void;
|
||||
|
||||
// 发送事件
|
||||
emit(event: string, payload?: any): void;
|
||||
|
||||
// 清除所有监听器
|
||||
clear(): void;
|
||||
}
|
||||
```
|
||||
|
||||
### 使用示例
|
||||
|
||||
```typescript
|
||||
const emitter = new EventEmitter();
|
||||
|
||||
// 订阅
|
||||
const unsubscribe = emitter.on('user:login', (data) => {
|
||||
console.log('User logged in:', data);
|
||||
});
|
||||
|
||||
// 发送
|
||||
emitter.emit('user:login', { userId: 123 });
|
||||
|
||||
// 取消订阅
|
||||
unsubscribe();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ManagerRegistry
|
||||
|
||||
### 概述
|
||||
|
||||
全局单例注册表，集中管理所有 Manager 实例，提供跨 Manager 通信。
|
||||
|
||||
### API
|
||||
|
||||
```typescript
|
||||
class ManagerRegistry {
|
||||
// 获取单例
|
||||
static getInstance(): ManagerRegistry;
|
||||
|
||||
// 重置单例（用于测试）
|
||||
static reset(): void;
|
||||
|
||||
// 容器元素
|
||||
container: HTMLElement | null;
|
||||
wrapper: HTMLElement | null;
|
||||
|
||||
// Manager 实例
|
||||
toolbar: ToolbarManager | null;
|
||||
dialog: DialogManager | null;
|
||||
engine3d: EngineManager | null;
|
||||
buttonGroup: ButtonGroupManager | null;
|
||||
rightKey: RightKeyManager | null;
|
||||
constructTree: ConstructTreeManagerBtn | null;
|
||||
propertyPanel: PropertyPanelManager | null;
|
||||
measure: MeasureDialogManager | null;
|
||||
walkControl: WalkControlManager | null;
|
||||
map: MapDialogManager | null;
|
||||
sectionPlane: SectionPlaneDialogManager | null;
|
||||
sectionAxis: SectionAxisDialogManager | null;
|
||||
sectionBox: SectionBoxDialogManager | null;
|
||||
|
||||
// 事件方法
|
||||
emit<K extends keyof EngineEvents>(event: K, payload: EngineEvents[K]): void;
|
||||
on<K extends keyof EngineEvents>(event: K, listener: (payload: EngineEvents[K]) => void): () => void;
|
||||
off<K extends keyof EngineEvents>(event: K, listener: (payload: EngineEvents[K]) => void): void;
|
||||
clearEvents(): void;
|
||||
}
|
||||
```
|
||||
|
||||
### 使用示例
|
||||
|
||||
```typescript
|
||||
const registry = ManagerRegistry.getInstance();
|
||||
|
||||
// 访问 Manager
|
||||
registry.toolbar?.show();
|
||||
registry.measure?.switchMode('distance');
|
||||
|
||||
// 发送事件
|
||||
registry.emit('engine:model-loaded', { url: 'model.gltf' });
|
||||
|
||||
// 订阅事件
|
||||
const unsubscribe = registry.on('engine:object-clicked', (payload) => {
|
||||
console.log('Object clicked:', payload.objectId);
|
||||
});
|
||||
```
|
||||
|
||||
### 支持的事件
|
||||
|
||||
| 事件 | 数据类型 | 说明 |
|
||||
|------|---------|------|
|
||||
| `ui:open-dialog` | `{ id: string; data?: any }` | 打开对话框 |
|
||||
| `ui:close-dialog` | `{ id: string }` | 关闭对话框 |
|
||||
| `engine:model-loaded` | `{ url: string }` | 模型加载完成 |
|
||||
| `engine:object-clicked` | `{ objectId: string; position: Point3D }` | 点击对象 |
|
||||
| `ui:tree-node-check` | `{ id: string; checked: boolean; node: any }` | 树节点勾选 |
|
||||
| `ui:tree-node-select` | `{ id: string; selected: boolean; node: any }` | 树节点选择 |
|
||||
| `sys:theme-changed` | `{ theme: string }` | 主题变更 |
|
||||
| `sys:locale-changed` | `{ locale: string }` | 语言变更 |
|
||||
| `walk:speed-change` | `{ speed: number }` | 漫游速度变更 |
|
||||
| `walk:path-mode-toggle` | `{ isActive: boolean }` | 路径模式切换 |
|
||||
| `map:opened` | `{}` | 地图打开 |
|
||||
| `map:closed` | `{}` | 地图关闭 |
|
||||
|
||||
---
|
||||
|
||||
## BaseManager
|
||||
|
||||
### 概述
|
||||
|
||||
所有 Manager 的抽象基类，提供注册表访问和事件订阅管理。
|
||||
|
||||
### API
|
||||
|
||||
```typescript
|
||||
abstract class BaseManager {
|
||||
// 受保护属性
|
||||
protected registry: ManagerRegistry;
|
||||
|
||||
// 受保护方法
|
||||
protected subscribe<K extends keyof EngineEvents>(
|
||||
event: K,
|
||||
handler: (payload: EngineEvents[K]) => void
|
||||
): void;
|
||||
|
||||
protected emit<K extends keyof EngineEvents>(
|
||||
event: K,
|
||||
payload: EngineEvents[K]
|
||||
): void;
|
||||
|
||||
// 公开方法
|
||||
destroy(): void;
|
||||
}
|
||||
```
|
||||
|
||||
### 使用示例
|
||||
|
||||
```typescript
|
||||
export class CustomManager extends BaseManager {
|
||||
constructor() {
|
||||
super();
|
||||
}
|
||||
|
||||
public initialize(): void {
|
||||
// 订阅事件（自动管理生命周期）
|
||||
this.subscribe('engine:model-loaded', (payload) => {
|
||||
console.log('Model loaded:', payload.url);
|
||||
});
|
||||
}
|
||||
|
||||
public doSomething(): void {
|
||||
// 发送事件
|
||||
this.emit('custom:action', { data: 'value' });
|
||||
|
||||
// 访问其他 Manager
|
||||
this.registry.toolbar?.show();
|
||||
}
|
||||
|
||||
public destroy(): void {
|
||||
// 自动清理所有订阅
|
||||
super.destroy();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 特性
|
||||
|
||||
- **自动资源清理**: `destroy()` 时自动取消所有订阅
|
||||
- **类型安全**: 使用 TypeScript 泛型确保事件类型
|
||||
- **注册表访问**: 可通过 `this.registry` 访问所有 Manager
|
||||
|
||||
---
|
||||
|
||||
## BaseDialogManager
|
||||
|
||||
### 概述
|
||||
|
||||
对话框 Manager 的抽象基类，封装对话框的完整生命周期。
|
||||
|
||||
### API
|
||||
|
||||
```typescript
|
||||
abstract class BaseDialogManager extends BaseManager {
|
||||
// 抽象属性（子类必须实现）
|
||||
protected abstract get dialogId(): string;
|
||||
protected abstract get dialogTitle(): string;
|
||||
|
||||
// 抽象方法（子类必须实现）
|
||||
protected abstract createContent(): HTMLElement;
|
||||
|
||||
// 可选属性（子类可重写）
|
||||
protected get dialogWidth(): number; // 默认: 300
|
||||
protected get dialogHeight(): number | 'auto'; // 默认: 'auto'
|
||||
protected get dialogOptions(): DialogManagerOptions;
|
||||
|
||||
// 钩子方法（子类可重写）
|
||||
protected onDialogCreated(): void;
|
||||
protected onDialogClose(): void;
|
||||
protected onBeforeDestroy(): void;
|
||||
protected getDialogPosition(): { x: number; y: number };
|
||||
|
||||
// 公开方法
|
||||
show(): void;
|
||||
hide(): void;
|
||||
toggle(): void;
|
||||
isOpen(): boolean;
|
||||
destroy(): void;
|
||||
}
|
||||
|
||||
interface DialogManagerOptions {
|
||||
draggable?: boolean; // 默认 true
|
||||
resizable?: boolean; // 默认 false
|
||||
}
|
||||
```
|
||||
|
||||
### 使用示例
|
||||
|
||||
```typescript
|
||||
export class MeasureDialogManager extends BaseDialogManager {
|
||||
private panel: MeasurePanel | null = null;
|
||||
|
||||
protected get dialogId(): string {
|
||||
return 'measure-dialog';
|
||||
}
|
||||
|
||||
protected get dialogTitle(): string {
|
||||
return 'measure.dialogTitle'; // i18n key
|
||||
}
|
||||
|
||||
protected get dialogWidth(): number {
|
||||
return 250;
|
||||
}
|
||||
|
||||
protected createContent(): HTMLElement {
|
||||
this.panel = new MeasurePanel({
|
||||
onModeChange: (mode) => {
|
||||
this.registry.engine3d?.activateMeasure(mode);
|
||||
}
|
||||
});
|
||||
this.panel.init();
|
||||
|
||||
const wrapper = document.createElement('div');
|
||||
wrapper.appendChild(this.panel.element);
|
||||
return wrapper;
|
||||
}
|
||||
|
||||
protected onDialogCreated(): void {
|
||||
this.dialog?.fitHeight(false);
|
||||
}
|
||||
|
||||
protected onDialogClose(): void {
|
||||
this.registry.toolbar?.setBtnActive('measure', false);
|
||||
}
|
||||
|
||||
protected onBeforeDestroy(): void {
|
||||
this.panel?.destroy();
|
||||
this.panel = null;
|
||||
}
|
||||
|
||||
// 业务方法
|
||||
public switchMode(mode: string): void {
|
||||
this.panel?.switchMode(mode);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 生命周期
|
||||
|
||||
```
|
||||
show()
|
||||
↓
|
||||
销毁旧对话框
|
||||
↓
|
||||
createContent() ← 子类实现
|
||||
↓
|
||||
创建 BimDialog
|
||||
↓
|
||||
onDialogCreated() ← 钩子
|
||||
↓
|
||||
显示中...
|
||||
↓
|
||||
hide() / 关闭按钮
|
||||
↓
|
||||
onDialogClose() ← 钩子
|
||||
↓
|
||||
onBeforeDestroy() ← 钩子
|
||||
↓
|
||||
销毁对话框
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 依赖关系
|
||||
|
||||
```
|
||||
BaseDialogManager
|
||||
↓ 继承
|
||||
BaseManager
|
||||
↓ 依赖
|
||||
ManagerRegistry
|
||||
↓ 组合
|
||||
EventEmitter
|
||||
```
|
||||
|
||||
### 被依赖情况
|
||||
|
||||
| 模块 | 依赖方式 |
|
||||
|------|---------|
|
||||
| managers/* | 继承 BaseManager 或 BaseDialogManager |
|
||||
| components/* | 间接依赖（通过 Manager） |
|
||||
| BimEngine | 使用 ManagerRegistry |
|
||||
|
||||
---
|
||||
|
||||
**文档生成时间**: 2026-01-23
|
||||
489
docs/MODULES/managers.md
Normal file
489
docs/MODULES/managers.md
Normal file
@@ -0,0 +1,489 @@
|
||||
# Managers 模块文档
|
||||
|
||||
## 模块概述
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **模块名** | managers |
|
||||
| **职责** | 处理业务逻辑，协调组件交互，管理组件生命周期 |
|
||||
| **公开 API** | 15 个 Manager 类 |
|
||||
| **状态** | ✅ 稳定 |
|
||||
|
||||
## 代码地图
|
||||
|
||||
```
|
||||
src/managers/
|
||||
├── engine-manager.ts # 3D 引擎管理器
|
||||
├── toolbar-manager.ts # 工具栏管理器
|
||||
├── dialog-manager.ts # 对话框管理器
|
||||
├── button-group-manager.ts # 按钮组管理器
|
||||
├── right-key-manager.ts # 右键菜单管理器
|
||||
├── property-panel-manager.ts # 属性面板管理器
|
||||
├── construct-tree-manager-btn.ts # 构件树管理器
|
||||
├── walk-control-manager.ts # 漫游控制管理器
|
||||
├── measure-dialog-manager.ts # 测量对话框管理器
|
||||
├── section-plane-dialog-manager.ts # 平面剖切对话框管理器
|
||||
├── section-box-dialog-manager.ts # 剖切盒对话框管理器
|
||||
├── section-axis-dialog-manager.ts # 轴向剖切对话框管理器
|
||||
├── map-dialog-manager.ts # 地图对话框管理器
|
||||
├── walk-path-dialog-manager.ts # 漫游路径对话框管理器
|
||||
└── walk-plan-view-dialog-manager.ts # 漫游平面图对话框管理器
|
||||
```
|
||||
|
||||
## 管理器分类
|
||||
|
||||
### 按继承关系
|
||||
|
||||
```
|
||||
BaseManager
|
||||
├── EngineManager
|
||||
├── ToolbarManager
|
||||
├── DialogManager
|
||||
├── ButtonGroupManager
|
||||
├── RightKeyManager
|
||||
├── PropertyPanelManager
|
||||
├── ConstructTreeManagerBtn
|
||||
└── WalkControlManager
|
||||
|
||||
BaseDialogManager (继承自 BaseManager)
|
||||
├── MeasureDialogManager
|
||||
├── SectionPlaneDialogManager
|
||||
├── SectionAxisDialogManager
|
||||
├── SectionBoxDialogManager
|
||||
├── MapDialogManager
|
||||
├── WalkPathDialogManager
|
||||
└── WalkPlanViewDialogManager
|
||||
```
|
||||
|
||||
### 按功能分类
|
||||
|
||||
| 类别 | 管理器 | 职责 |
|
||||
|------|--------|------|
|
||||
| **核心** | EngineManager | 3D 引擎管理 |
|
||||
| **UI 容器** | ToolbarManager, DialogManager, ButtonGroupManager | 容器组件管理 |
|
||||
| **交互** | RightKeyManager, PropertyPanelManager, ConstructTreeManagerBtn | 用户交互 |
|
||||
| **3D 工具** | MeasureDialogManager, SectionPlaneDialogManager, SectionAxisDialogManager, SectionBoxDialogManager | 3D 操作工具 |
|
||||
| **漫游** | WalkControlManager, WalkPathDialogManager, WalkPlanViewDialogManager, MapDialogManager | 漫游功能 |
|
||||
|
||||
---
|
||||
|
||||
## EngineManager
|
||||
|
||||
### 概述
|
||||
|
||||
管理 3D 引擎的初始化、模型加载和测量功能。
|
||||
|
||||
### API
|
||||
|
||||
```typescript
|
||||
class EngineManager extends BaseManager {
|
||||
initialize(options?: EngineOptions): void;
|
||||
isInitialized(): boolean;
|
||||
loadModel(url: string, options?: ModelLoadOptions): void;
|
||||
getEngine(): any;
|
||||
CameraGoHome(): void;
|
||||
activateMeasure(mode: MeasureMode): void;
|
||||
deactivateMeasure(): void;
|
||||
getCurrentMeasureType(): MeasureMode | null;
|
||||
destroy(): void;
|
||||
}
|
||||
```
|
||||
|
||||
### 使用示例
|
||||
|
||||
```typescript
|
||||
const engine = new EngineManager(container);
|
||||
engine.initialize();
|
||||
engine.loadModel('model.gltf', { autoFit: true });
|
||||
engine.activateMeasure('distance');
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ToolbarManager
|
||||
|
||||
### 概述
|
||||
|
||||
管理底部工具栏的按钮配置、显示控制、主题管理。
|
||||
|
||||
### API
|
||||
|
||||
```typescript
|
||||
class ToolbarManager extends BaseManager {
|
||||
addGroup(groupId: string, beforeGroupId?: string): void;
|
||||
addButton(config: ButtonConfig): void;
|
||||
setBtnActive(id: string, active?: boolean): void;
|
||||
setButtonVisibility(id: string, visible: boolean): void;
|
||||
setShowLabel(show: boolean): void;
|
||||
updateTheme(theme: ThemeConfig): void;
|
||||
setBackgroundColor(color: string): void;
|
||||
setColors(colors: ButtonGroupColors): void;
|
||||
show(): void;
|
||||
hide(): void;
|
||||
setVisible(visible: boolean): void;
|
||||
refresh(): void;
|
||||
destroy(): void;
|
||||
}
|
||||
```
|
||||
|
||||
### 使用示例
|
||||
|
||||
```typescript
|
||||
const toolbar = new ToolbarManager(container);
|
||||
|
||||
toolbar.addGroup('custom-group');
|
||||
toolbar.addButton({
|
||||
id: 'custom-btn',
|
||||
groupId: 'custom-group',
|
||||
type: 'button',
|
||||
label: 'Custom',
|
||||
icon: '<svg>...</svg>',
|
||||
onClick: () => console.log('Clicked')
|
||||
});
|
||||
|
||||
toolbar.setBtnActive('custom-btn', true);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## DialogManager
|
||||
|
||||
### 概述
|
||||
|
||||
创建和管理通用对话框实例。
|
||||
|
||||
### API
|
||||
|
||||
```typescript
|
||||
class DialogManager extends BaseManager {
|
||||
create(options: DialogOptions): BimDialog;
|
||||
showInfoDialog(): void;
|
||||
updateTheme(theme: ThemeConfig): void;
|
||||
destroy(): void;
|
||||
}
|
||||
```
|
||||
|
||||
### 使用示例
|
||||
|
||||
```typescript
|
||||
const dialogManager = new DialogManager(container);
|
||||
|
||||
const dialog = dialogManager.create({
|
||||
title: 'My Dialog',
|
||||
content: element,
|
||||
width: 400,
|
||||
onClose: () => console.log('Closed')
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## MeasureDialogManager
|
||||
|
||||
### 概述
|
||||
|
||||
管理测量工具的对话框和测量面板。
|
||||
|
||||
### API
|
||||
|
||||
```typescript
|
||||
class MeasureDialogManager extends BaseDialogManager {
|
||||
getActiveMode(): MeasureMode;
|
||||
switchMode(mode: MeasureMode): void;
|
||||
setMeasureResult(result: MeasureResult | null): void;
|
||||
getConfig(): MeasureConfig;
|
||||
setConfig(partial: Partial<MeasureConfig>, persist?: boolean): void;
|
||||
clearAll(): void;
|
||||
openSettings(): void;
|
||||
show(): void;
|
||||
hide(): void;
|
||||
toggle(): void;
|
||||
}
|
||||
```
|
||||
|
||||
### 测量模式
|
||||
|
||||
| 模式 | 说明 |
|
||||
|------|------|
|
||||
| `distance` | 距离测量 |
|
||||
| `minDistance` | 最小距离 |
|
||||
| `angle` | 角度测量 |
|
||||
| `elevation` | 标高测量 |
|
||||
| `volume` | 体积测量 |
|
||||
| `laserDistance` | 激光测距 |
|
||||
| `slope` | 坡度测量 |
|
||||
| `spaceVolume` | 空间体积 |
|
||||
|
||||
### 使用示例
|
||||
|
||||
```typescript
|
||||
const measure = new MeasureDialogManager();
|
||||
measure.show();
|
||||
measure.switchMode('distance');
|
||||
|
||||
const config = measure.getConfig();
|
||||
measure.setConfig({ unit: 'cm', precision: 1 });
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## SectionPlaneDialogManager
|
||||
|
||||
### 概述
|
||||
|
||||
管理平面剖切工具对话框。
|
||||
|
||||
### API
|
||||
|
||||
```typescript
|
||||
class SectionPlaneDialogManager extends BaseDialogManager {
|
||||
show(): void;
|
||||
hide(): void;
|
||||
toggle(): void;
|
||||
isOpen(): boolean;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## SectionAxisDialogManager
|
||||
|
||||
### 概述
|
||||
|
||||
管理轴向剖切工具对话框。
|
||||
|
||||
### API
|
||||
|
||||
```typescript
|
||||
class SectionAxisDialogManager extends BaseDialogManager {
|
||||
getHiddenState(): boolean;
|
||||
setHiddenState(isHidden: boolean): void;
|
||||
getActiveAxis(): 'x' | 'y' | 'z';
|
||||
setActiveAxis(axis: 'x' | 'y' | 'z'): void;
|
||||
show(): void;
|
||||
hide(): void;
|
||||
toggle(): void;
|
||||
}
|
||||
```
|
||||
|
||||
### 使用示例
|
||||
|
||||
```typescript
|
||||
const sectionAxis = new SectionAxisDialogManager();
|
||||
sectionAxis.show();
|
||||
sectionAxis.setActiveAxis('y');
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## SectionBoxDialogManager
|
||||
|
||||
### 概述
|
||||
|
||||
管理剖切盒工具对话框。
|
||||
|
||||
### API
|
||||
|
||||
```typescript
|
||||
class SectionBoxDialogManager extends BaseDialogManager {
|
||||
getHiddenState(): boolean;
|
||||
setHiddenState(isHidden: boolean): void;
|
||||
getReversedState(): boolean;
|
||||
setReversedState(isReversed: boolean): void;
|
||||
getRange(): SectionBoxRange;
|
||||
setRange(range: Partial<SectionBoxRange>): void;
|
||||
show(): void;
|
||||
hide(): void;
|
||||
toggle(): void;
|
||||
}
|
||||
|
||||
interface SectionBoxRange {
|
||||
minX: number;
|
||||
maxX: number;
|
||||
minY: number;
|
||||
maxY: number;
|
||||
minZ: number;
|
||||
maxZ: number;
|
||||
}
|
||||
```
|
||||
|
||||
### 使用示例
|
||||
|
||||
```typescript
|
||||
const sectionBox = new SectionBoxDialogManager();
|
||||
sectionBox.show();
|
||||
|
||||
const range = sectionBox.getRange();
|
||||
sectionBox.setRange({ minX: 0, maxX: 100 });
|
||||
sectionBox.setReversedState(true);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## WalkControlManager
|
||||
|
||||
### 概述
|
||||
|
||||
管理漫游控制面板和相关交互。
|
||||
|
||||
### API
|
||||
|
||||
```typescript
|
||||
class WalkControlManager extends BaseManager {
|
||||
init(): void;
|
||||
show(): void;
|
||||
hide(): void;
|
||||
destroy(): void;
|
||||
}
|
||||
```
|
||||
|
||||
### 事件
|
||||
|
||||
| 事件 | 说明 |
|
||||
|------|------|
|
||||
| `walk:plan-view-toggle` | 平面图切换 |
|
||||
| `walk:path-mode-toggle` | 路径模式切换 |
|
||||
| `walk:walk-mode-toggle` | 漫游模式切换 |
|
||||
| `walk:speed-change` | 速度变化 |
|
||||
| `walk:gravity-toggle` | 重力开关 |
|
||||
| `walk:collision-toggle` | 碰撞开关 |
|
||||
|
||||
---
|
||||
|
||||
## PropertyPanelManager
|
||||
|
||||
### 概述
|
||||
|
||||
管理构件属性面板的显示。
|
||||
|
||||
### API
|
||||
|
||||
```typescript
|
||||
class PropertyPanelManager extends BaseManager {
|
||||
init(): void;
|
||||
show(): void;
|
||||
hide(): void;
|
||||
isOpen(): boolean;
|
||||
destroy(): void;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ConstructTreeManagerBtn
|
||||
|
||||
### 概述
|
||||
|
||||
管理构件树按钮和对话框。
|
||||
|
||||
### API
|
||||
|
||||
```typescript
|
||||
class ConstructTreeManagerBtn extends BaseManager {
|
||||
openConstructTreeDialog(): void;
|
||||
addGroup(groupId: string, beforeGroupId?: string): void;
|
||||
addButton(config: ButtonConfig): void;
|
||||
setButtonVisibility(id: string, visible: boolean): void;
|
||||
setShowLabel(show: boolean): void;
|
||||
setVisible(visible: boolean): void;
|
||||
setBackgroundColor(color: string): void;
|
||||
setColors(colors: ButtonGroupColors): void;
|
||||
refresh(): void;
|
||||
destroy(): void;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## RightKeyManager
|
||||
|
||||
### 概述
|
||||
|
||||
管理右键上下文菜单。
|
||||
|
||||
### API
|
||||
|
||||
```typescript
|
||||
class RightKeyManager extends BaseManager {
|
||||
registerHandler(handler: ContextMenuHandler): void;
|
||||
showMenu(x: number, y: number, items: MenuItemConfig[], groupOrder?: string[]): void;
|
||||
hide(): void;
|
||||
destroy(): void;
|
||||
}
|
||||
|
||||
type ContextMenuHandler = (e: MouseEvent) => MenuItemConfig[];
|
||||
```
|
||||
|
||||
### 使用示例
|
||||
|
||||
```typescript
|
||||
const rightKey = new RightKeyManager(container);
|
||||
|
||||
rightKey.registerHandler((e) => [
|
||||
{ id: 'view', label: 'View', onClick: () => {} },
|
||||
{ id: 'delete', label: 'Delete', onClick: () => {} }
|
||||
]);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ButtonGroupManager
|
||||
|
||||
### 概述
|
||||
|
||||
创建和管理多个按钮组实例。
|
||||
|
||||
### API
|
||||
|
||||
```typescript
|
||||
class ButtonGroupManager extends BaseManager {
|
||||
create(id: string, options: ButtonGroupOptions): BimButtonGroup;
|
||||
get(id: string): BimButtonGroup | undefined;
|
||||
updateTheme(theme: ThemeConfig): void;
|
||||
destroy(): void;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 交互流程
|
||||
|
||||
### 工具栏按钮触发测量
|
||||
|
||||
```
|
||||
ToolbarManager (按钮点击)
|
||||
↓
|
||||
MeasureDialogManager.show()
|
||||
↓
|
||||
onModeChange 事件
|
||||
↓
|
||||
EngineManager.activateMeasure(mode)
|
||||
↓
|
||||
3D 引擎进入测量模式
|
||||
```
|
||||
|
||||
### 漫游模式激活
|
||||
|
||||
```
|
||||
ToolbarManager (walk 按钮)
|
||||
↓
|
||||
WalkControlManager.show()
|
||||
↓
|
||||
隐藏底部工具栏
|
||||
↓
|
||||
显示漫游控制面板
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 依赖关系
|
||||
|
||||
所有 Manager 都依赖:
|
||||
- `BaseManager` 或 `BaseDialogManager`
|
||||
- `ManagerRegistry`
|
||||
|
||||
各 Manager 之间通过事件系统通信，避免直接依赖。
|
||||
|
||||
---
|
||||
|
||||
**文档生成时间**: 2026-01-23
|
||||
402
docs/MODULES/services.md
Normal file
402
docs/MODULES/services.md
Normal file
@@ -0,0 +1,402 @@
|
||||
# Services 模块文档
|
||||
|
||||
## 模块概述
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **模块名** | services |
|
||||
| **职责** | 提供全局状态管理服务：国际化和主题系统 |
|
||||
| **公开 API** | 2 个管理器类 + 辅助函数 |
|
||||
| **状态** | ✅ 稳定 |
|
||||
|
||||
## 代码地图
|
||||
|
||||
```
|
||||
src/
|
||||
├── services/
|
||||
│ ├── locale.ts # 国际化服务
|
||||
│ └── theme.ts # 主题服务
|
||||
├── locales/
|
||||
│ ├── types.ts # 翻译类型定义
|
||||
│ ├── zh-CN.ts # 中文翻译
|
||||
│ └── en-US.ts # 英文翻译
|
||||
└── themes/
|
||||
├── types.ts # 主题类型定义
|
||||
└── presets.ts # 内置主题预设
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## LocaleManager（国际化服务）
|
||||
|
||||
### 概述
|
||||
|
||||
管理应用语言、翻译文本，支持实时订阅。
|
||||
|
||||
### API
|
||||
|
||||
```typescript
|
||||
class LocaleManager {
|
||||
getLocale(): LocaleType;
|
||||
setLocale(locale: LocaleType): void;
|
||||
t(key: string): string;
|
||||
subscribe(listener: (locale: LocaleType) => void): () => void;
|
||||
}
|
||||
|
||||
type LocaleType = 'zh-CN' | 'en-US';
|
||||
|
||||
// 单例导出
|
||||
export const localeManager: LocaleManager;
|
||||
|
||||
// 便捷函数
|
||||
export function t(key: string): string;
|
||||
```
|
||||
|
||||
### 使用示例
|
||||
|
||||
```typescript
|
||||
import { localeManager, t } from 'iflow-engine';
|
||||
|
||||
// 获取当前语言
|
||||
const locale = localeManager.getLocale(); // 'zh-CN'
|
||||
|
||||
// 切换语言
|
||||
localeManager.setLocale('en-US');
|
||||
|
||||
// 翻译
|
||||
console.log(t('toolbar.home')); // 'Home'
|
||||
console.log(t('measure.modes.distance')); // 'Distance'
|
||||
|
||||
// 订阅语言变更
|
||||
const unsubscribe = localeManager.subscribe((locale) => {
|
||||
console.log('Language changed:', locale);
|
||||
});
|
||||
```
|
||||
|
||||
### 翻译键结构
|
||||
|
||||
| 域 | 说明 | 示例 |
|
||||
|---|------|------|
|
||||
| `common` | 通用文本 | `common.title` |
|
||||
| `toolbar` | 工具栏按钮 | `toolbar.home`, `toolbar.measure` |
|
||||
| `dialog` | 对话框 | `dialog.testTitle` |
|
||||
| `menu` | 菜单项 | `menu.info` |
|
||||
| `tree` | 树形控件 | `tree.searchPlaceholder` |
|
||||
| `measure` | 测量工具 | `measure.modes.distance`, `measure.units.m` |
|
||||
| `sectionPlane` | 平面剖切 | `sectionPlane.dialogTitle` |
|
||||
| `sectionAxis` | 轴向剖切 | `sectionAxis.dialogTitle` |
|
||||
| `sectionBox` | 剖切盒 | `sectionBox.dialogTitle` |
|
||||
| `walkControl` | 漫游控制 | `walkControl.speed` |
|
||||
| `map` | 地图 | `map.dialogTitle` |
|
||||
|
||||
### 扩展新语言
|
||||
|
||||
1. 创建翻译文件 `src/locales/ja-JP.ts`
|
||||
2. 更新类型 `src/locales/types.ts`
|
||||
3. 注册到 LocaleManager
|
||||
|
||||
```typescript
|
||||
// src/locales/ja-JP.ts
|
||||
export const jaJP: TranslationDictionary = {
|
||||
common: { title: 'BimEngine' },
|
||||
toolbar: { home: 'ホーム', measure: '測定' },
|
||||
// ...
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ThemeManager（主题服务）
|
||||
|
||||
### 概述
|
||||
|
||||
管理应用主题、颜色方案，支持实时订阅。
|
||||
|
||||
### API
|
||||
|
||||
```typescript
|
||||
class ThemeManager {
|
||||
getTheme(): ThemeConfig;
|
||||
setTheme(themeName: 'dark' | 'light'): void;
|
||||
setCustomTheme(theme: ThemeConfig): void;
|
||||
subscribe(listener: (theme: ThemeConfig) => void): () => void;
|
||||
}
|
||||
|
||||
// 单例导出
|
||||
export const themeManager: ThemeManager;
|
||||
```
|
||||
|
||||
### 使用示例
|
||||
|
||||
```typescript
|
||||
import { themeManager } from 'iflow-engine';
|
||||
|
||||
// 获取当前主题
|
||||
const theme = themeManager.getTheme();
|
||||
console.log(theme.primary); // '#2563eb'
|
||||
|
||||
// 切换预设主题
|
||||
themeManager.setTheme('dark');
|
||||
|
||||
// 自定义主题
|
||||
themeManager.setCustomTheme({
|
||||
name: 'custom',
|
||||
primary: '#ff6b6b',
|
||||
// ...
|
||||
});
|
||||
|
||||
// 订阅主题变更
|
||||
const unsubscribe = themeManager.subscribe((theme) => {
|
||||
console.log('Theme changed:', theme.name);
|
||||
});
|
||||
```
|
||||
|
||||
### 预设主题
|
||||
|
||||
#### 亮色主题 (`lightTheme`)
|
||||
|
||||
| 属性 | 值 | 说明 |
|
||||
|------|-----|------|
|
||||
| `primary` | `#2563eb` | 主色 |
|
||||
| `bgBase` | `#f8fafc` | 页面背景 |
|
||||
| `bgElevated` | `#ffffff` | 卡片背景 |
|
||||
| `textPrimary` | `#0f172a` | 主文本 |
|
||||
| `textSecondary` | `#475569` | 次要文本 |
|
||||
|
||||
#### 暗色主题 (`darkTheme`)
|
||||
|
||||
| 属性 | 值 | 说明 |
|
||||
|------|-----|------|
|
||||
| `primary` | `#3b82f6` | 主色 |
|
||||
| `bgBase` | `#152232` | 页面背景 |
|
||||
| `bgElevated` | `#1f2d3e` | 卡片背景 |
|
||||
| `textPrimary` | `#ffffff` | 主文本 |
|
||||
| `textSecondary` | `#94a3b8` | 次要文本 |
|
||||
|
||||
### ThemeConfig 结构
|
||||
|
||||
```typescript
|
||||
interface ThemeConfig {
|
||||
name: string;
|
||||
|
||||
// 品牌色
|
||||
primary: string;
|
||||
primaryHover: string;
|
||||
primaryActive: string;
|
||||
primarySubtle: string;
|
||||
|
||||
// 状态色
|
||||
success: string;
|
||||
warning: string;
|
||||
danger: string;
|
||||
info: string;
|
||||
|
||||
// 背景色
|
||||
bgBase: string;
|
||||
bgElevated: string;
|
||||
bgOverlay: string;
|
||||
bgInset: string;
|
||||
bgGlass: string;
|
||||
bgGlassBlur: string;
|
||||
|
||||
// 文字色
|
||||
textPrimary: string;
|
||||
textSecondary: string;
|
||||
textTertiary: string;
|
||||
textDisabled: string;
|
||||
textInverse: string;
|
||||
textLink: string;
|
||||
|
||||
// 图标色
|
||||
iconDefault: string;
|
||||
iconHover: string;
|
||||
iconActive: string;
|
||||
iconDisabled: string;
|
||||
|
||||
// 边框色
|
||||
borderDefault: string;
|
||||
borderSubtle: string;
|
||||
borderStrong: string;
|
||||
divider: string;
|
||||
|
||||
// 组件状态
|
||||
componentBg: string;
|
||||
componentBgHover: string;
|
||||
componentBgActive: string;
|
||||
componentBgSelected: string;
|
||||
|
||||
// 焦点
|
||||
focusRing: string;
|
||||
selectionBg: string;
|
||||
|
||||
// 阴影
|
||||
shadowSm: string;
|
||||
shadowMd: string;
|
||||
shadowLg: string;
|
||||
shadowGlow: string;
|
||||
|
||||
// 浮动层
|
||||
floatingBg: string;
|
||||
floatingBorder: string;
|
||||
floatingBtnBg: string;
|
||||
floatingBtnBgHover: string;
|
||||
floatingIconColor: string;
|
||||
|
||||
// 面板
|
||||
panelBg: string;
|
||||
panelBorder: string;
|
||||
panelHeaderBg: string;
|
||||
panelRadius: string;
|
||||
|
||||
// 选项卡
|
||||
tabBg: string;
|
||||
tabItemBg: string;
|
||||
tabItemBgActive: string;
|
||||
tabItemTextActive: string;
|
||||
|
||||
// 组件覆盖（可选）
|
||||
overrides?: {
|
||||
dialog?: { headerBg?: string };
|
||||
toolbar?: { bg?: string; buttonBg?: string };
|
||||
input?: { bg?: string; placeholder?: string };
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### 创建自定义主题
|
||||
|
||||
```typescript
|
||||
import { createThemeFromPartial, lightTheme } from 'iflow-engine';
|
||||
|
||||
// 基于预设创建（推荐）
|
||||
const customTheme = createThemeFromPartial(lightTheme, {
|
||||
name: 'coral',
|
||||
primary: '#ff6b6b',
|
||||
primaryHover: '#ff5252',
|
||||
primaryActive: '#ff4757',
|
||||
});
|
||||
|
||||
themeManager.setCustomTheme(customTheme);
|
||||
```
|
||||
|
||||
### CSS 变量映射
|
||||
|
||||
主题颜色自动映射到 CSS 变量：
|
||||
|
||||
```css
|
||||
.my-component {
|
||||
background-color: var(--bim-bg-elevated);
|
||||
color: var(--bim-text-primary);
|
||||
border: 1px solid var(--bim-border-default);
|
||||
}
|
||||
|
||||
.my-button {
|
||||
background-color: var(--bim-primary);
|
||||
color: var(--bim-text-inverse);
|
||||
}
|
||||
|
||||
.my-button:hover {
|
||||
background-color: var(--bim-primary-hover);
|
||||
}
|
||||
```
|
||||
|
||||
常用 CSS 变量：
|
||||
|
||||
| 变量 | 说明 |
|
||||
|------|------|
|
||||
| `--bim-primary` | 主色 |
|
||||
| `--bim-bg-base` | 页面背景 |
|
||||
| `--bim-bg-elevated` | 卡片背景 |
|
||||
| `--bim-text-primary` | 主文本 |
|
||||
| `--bim-border-default` | 边框 |
|
||||
| `--bim-shadow-sm` | 小阴影 |
|
||||
|
||||
---
|
||||
|
||||
## React 集成
|
||||
|
||||
```typescript
|
||||
import { useEffect, useState } from 'react';
|
||||
import { localeManager, themeManager } from 'iflow-engine';
|
||||
|
||||
// 语言 Hook
|
||||
export function useLocale() {
|
||||
const [locale, setLocale] = useState(() => localeManager.getLocale());
|
||||
|
||||
useEffect(() => {
|
||||
return localeManager.subscribe(setLocale);
|
||||
}, []);
|
||||
|
||||
return { locale, setLocale: localeManager.setLocale.bind(localeManager) };
|
||||
}
|
||||
|
||||
// 主题 Hook
|
||||
export function useTheme() {
|
||||
const [theme, setTheme] = useState(() => themeManager.getTheme());
|
||||
|
||||
useEffect(() => {
|
||||
return themeManager.subscribe(setTheme);
|
||||
}, []);
|
||||
|
||||
return { theme, setTheme: themeManager.setTheme.bind(themeManager) };
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 架构设计
|
||||
|
||||
### 单例模式
|
||||
|
||||
两个服务都采用单例模式：
|
||||
|
||||
```typescript
|
||||
export const localeManager = new LocaleManager();
|
||||
export const themeManager = new ThemeManager();
|
||||
```
|
||||
|
||||
### 观察者模式
|
||||
|
||||
支持订阅状态变更：
|
||||
|
||||
```typescript
|
||||
// 订阅
|
||||
const unsubscribe = themeManager.subscribe((theme) => {
|
||||
// 更新 UI
|
||||
});
|
||||
|
||||
// 取消订阅
|
||||
unsubscribe();
|
||||
```
|
||||
|
||||
### 与 BimEngine 集成
|
||||
|
||||
```typescript
|
||||
const engine = new BimEngine('container', {
|
||||
locale: 'zh-CN',
|
||||
theme: 'dark'
|
||||
});
|
||||
|
||||
// 动态切换
|
||||
engine.setLocale('en-US');
|
||||
engine.setTheme('light');
|
||||
engine.setCustomTheme(customTheme);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 依赖关系
|
||||
|
||||
```
|
||||
BimEngine
|
||||
↓
|
||||
LocaleManager ←→ locales/*.ts
|
||||
↓
|
||||
ThemeManager ←→ themes/*.ts
|
||||
```
|
||||
|
||||
Services 模块无外部依赖，完全自包含。
|
||||
|
||||
---
|
||||
|
||||
**文档生成时间**: 2026-01-23
|
||||
Reference in New Issue
Block a user