bim_engine/docs/MODULES/核心模块.md

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

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;
}

使用示例

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

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;
  componentDetail: ComponentDetailManager | 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;
}

使用示例

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

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;
}

使用示例

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

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
}

使用示例

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