From a30e87e57780824b718ccb391db6442158825351 Mon Sep 17 00:00:00 2001
From: yuding <1023798085@qq.com>
Date: Wed, 4 Feb 2026 15:17:23 +0800
Subject: [PATCH] docs(engine): add JSDoc comments to all public methods
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add documentation for:
- saveMeasureSetting: 保存测量设置
- fitSectionBoxToModel: 剖切盒适应选中模型
- setWalkSpeed/Gravity/Collision: 漫游参数设置
- toggleMiniMap: 切换小地图
- getTypeTreeData/LevelTreeData/MajorTreeData: 模型树数据获取
- activateZoomBox: 框选放大
- getEngineInfo: 获取引擎信息
---
 src/components/engine/index.ts | 47 +++++++++++++++++++++++++++++++++-
 1 file changed, 46 insertions(+), 1 deletion(-)

diff --git a/src/components/engine/index.ts b/src/components/engine/index.ts
index 5dd903c..c15e400 100644
--- a/src/components/engine/index.ts
+++ b/src/components/engine/index.ts
@@ -342,6 +342,10 @@ export class Engine implements IBimComponent {
         this.engine.measure.clearAll();
     }
 
+    /**
+     * 保存测量设置
+     * @param setting 测量设置，包含单位和精度
+     */
     public saveMeasureSetting(setting: { unit: MeasureUnit; precision: MeasurePrecision }): void {
         if (!this._isInitialized || !this.engine?.measure) {
             return;
@@ -493,6 +497,10 @@ export class Engine implements IBimComponent {
         this.engine.clipping.recover();
     }
 
+    /**
+     * 剖切盒适应选中模型
+     * @remarks 将剖切盒调整为刚好包围选中的模型
+     */
     public fitSectionBoxToModel(): void {
         if (!this._isInitialized || !this.engine) {
             console.error('[Engine] Cannot fit section box: engine not initialized.');
@@ -560,6 +568,10 @@ export class Engine implements IBimComponent {
     private static WALK_GRAVITY_KEY = 'bim-walk-gravity';
     private static WALK_COLLISION_KEY = 'bim-walk-collision';
 
+    /**
+     * 设置漫游移动速度
+     * @param speed 移动速度值
+     */
     public setWalkSpeed(speed: number): void {
         if (!this._isInitialized || !this.engine?.controlModule) {
             console.error('[Engine] Cannot set walk speed: engine not initialized.');
@@ -569,6 +581,10 @@ export class Engine implements IBimComponent {
         this.engine.controlModule.setMoveSpeed(speed);
     }
 
+    /**
+     * 设置漫游重力开关
+     * @param enabled 是否启用重力
+     */
     public setWalkGravity(enabled: boolean): void {
         if (!this._isInitialized || !this.engine?.controlModule) {
             console.error('[Engine] Cannot set walk gravity: engine not initialized.');
@@ -578,6 +594,10 @@ export class Engine implements IBimComponent {
         this.engine.controlModule.setApplyGravity(enabled);
     }
 
+    /**
+     * 设置漫游碰撞检测开关
+     * @param enabled 是否启用碰撞检测
+     */
     public setWalkCollision(enabled: boolean): void {
         if (!this._isInitialized || !this.engine?.controlModule) {
             console.error('[Engine] Cannot set walk collision: engine not initialized.');
@@ -599,6 +619,9 @@ export class Engine implements IBimComponent {
         this.engine.controlModule.setApplyCollision(collision === 'true');
     }
 
+    /**
+     * 切换小地图显示状态
+     */
     public toggleMiniMap(): void {
         if (!this._isInitialized || !this.engine?.controlModule) {
             console.error('[Engine] Cannot toggle mini map: engine not initialized.');
@@ -656,6 +679,10 @@ export class Engine implements IBimComponent {
 
     // ==================== 模型树 ====================
 
+    /**
+     * 获取类型树数据
+     * @returns 类型树节点数组
+     */
     public getTypeTreeData(): any[] {
         if (!this._isInitialized || !this.engine?.modelTree) {
             return [];
@@ -663,6 +690,10 @@ export class Engine implements IBimComponent {
         return this.engine.modelTree.getTypeTreeData();
     }
 
+    /**
+     * 获取楼层树数据
+     * @returns 楼层树节点数组
+     */
     public getLevelTreeData(): any[] {
         if (!this._isInitialized || !this.engine?.modelTree) {
             return [];
@@ -670,6 +701,10 @@ export class Engine implements IBimComponent {
         return this.engine.modelTree.getLevelTreeData();
     }
 
+    /**
+     * 获取专业树数据
+     * @returns 专业树节点数组
+     */
     public getMajorTreeData(): any[] {
         if (!this._isInitialized || !this.engine?.modelTree) {
             return [];
@@ -679,7 +714,10 @@ export class Engine implements IBimComponent {
 
     // ==================== 结束：模型树 ====================
 
-    /** 激活框选放大功能 */
+    /**
+     * 激活框选放大功能
+     * @remarks 允许用户通过框选区域来放大视图
+     */
     public activateZoomBox(): void {
         if (!this._isInitialized || !this.engine) {
             console.warn('[Engine] Engine not initialized.');
@@ -688,6 +726,10 @@ export class Engine implements IBimComponent {
         this.engine.rangeScale?.active();
     }
 
+    /**
+     * 获取引擎基本信息
+     * @returns 引擎信息对象，包含构件数量、三角面数量、顶点数量等
+     */
     public getEngineInfo(): EngineInfo | null {
         if (!this._isInitialized || !this.engine) {
             console.warn('[Engine] Engine not initialized.');
@@ -866,6 +908,9 @@ export class Engine implements IBimComponent {
             console.warn('[Engine] Cannot show all models: engine not initialized.');
             return;
         }
+        // 取消剖切
+        this.deactivateSection()
+        // 显示所有模型
         this.engine.modelToolModule.showAllModels();
     }