docs: update clipping API documentation

- Update method references: activateSectionAxis → activeSection - Update call chains for all clipping modes (x/y/z/box/face) - Document new unified API: engine.clipping.active(mode) - Mark deprecated methods: fitSectionBoxToModel, resetSectionBox - Update underlying API: updateClippingValue instead of setboxPercent
2026-02-02 16:25:36 +08:00
parent 679d792de2
commit 5e02ebb8e9
2 changed files with 75 additions and 104 deletions
--- a/docs/API调用链.md
+++ b/docs/API调用链.md
@@ -314,15 +314,15 @@ Button onClick (buttons/section/section-axis/index.ts)
 SectionAxisDialogManager.show() (继承自 BaseDialogManager)
    │   createContent() → 创建 SectionAxisPanel
    │   onDialogCreated()
-    │       └── registry.engine3d.activateSectionAxis('x')  // 默认激活 X 轴
+    │       └── registry.engine3d.activeSection('x')  // 默认激活 X 轴
    ▼
-EngineManager.activateSectionAxis('x')
-    │   this.engineInstance.activateSectionAxis(axis)
+EngineManager.activeSection('x')
+    │   this.engineInstance.activeSection(mode)
    ▼
-Engine.activateSectionAxis('x')
-    │   this.engine.clipping.sectionPlaneX.active()
+Engine.activeSection('x')
+    │   this.engine.clipping.active('x')
    ▼
-底层引擎 API: engine.clipping.sectionPlaneX.active()
+底层引擎 API: engine.clipping.active('x')
 ```

 #### 调用链 - 切换轴向
@@ -335,20 +335,15 @@ SectionAxisPanel.onAxisChange('y')
    │
    ▼
 SectionAxisDialogManager 回调
-    │   registry.engine3d?.activateSectionAxis('y')
+    │   registry.engine3d?.activeSection('y')
    ▼
-EngineManager.activateSectionAxis('y')
-    │   this.engineInstance.activateSectionAxis(axis)
+EngineManager.activeSection('y')
+    │   this.engineInstance.activeSection(mode)
    ▼
-Engine.activateSectionAxis('y')
-    │   // 1. 先停用当前轴向 (X)
-    │   this.engine.clipping.sectionPlaneX.disActive()
-    │   // 2. 再激活新轴向 (Y)
-    │   this.engine.clipping.sectionPlaneY.active()
+Engine.activeSection('y')
+    │   this.engine.clipping.active('y')
    ▼
-底层引擎 API:
-    - engine.clipping.sectionPlaneX.disActive()
-    - engine.clipping.sectionPlaneY.active()
+底层引擎 API: engine.clipping.active('y')
 ```

 #### 调用链 - 关闭对话框
@@ -358,24 +353,26 @@ Engine.activateSectionAxis('y')
    │
    ▼
 SectionAxisDialogManager.onBeforeDestroy()
-    │   registry.engine3d?.deactivateSectionAxis()
+    │   registry.engine3d?.deactivateSection()
    ▼
-EngineManager.deactivateSectionAxis()
-    │   this.engineInstance.deactivateSectionAxis()
+EngineManager.deactivateSection()
+    │   this.engineInstance.deactivateSection()
    ▼
-Engine.deactivateSectionAxis()
+Engine.deactivateSection()
    │   this.engine.clipping.disActive()
    ▼
 底层引擎 API: engine.clipping.disActive()
 ```

-#### 轴向与底层 API 对照表
+#### 剖切模式与底层 API 对照表

-| 轴向 | Engine 内部调用 | 底层 API |
-|------|----------------|----------|
-| x | `planeMap['x']` | `engine.clipping.sectionPlaneX.active()` |
-| y | `planeMap['y']` | `engine.clipping.sectionPlaneY.active()` |
-| z | `planeMap['z']` | `engine.clipping.sectionPlaneZ.active()` |
+| 模式 | Engine 调用 | 底层 API |
+|------|-------------|----------|
+| x | `activeSection('x')` | `engine.clipping.active('x')` |
+| y | `activeSection('y')` | `engine.clipping.active('y')` |
+| z | `activeSection('z')` | `engine.clipping.active('z')` |
+| box | `activeSection('box')` | `engine.clipping.active('box')` |
+| face | `activeSection('face')` | `engine.clipping.active('face')` |

 ---

@@ -398,15 +395,15 @@ Button onClick (buttons/section/section-box/index.ts)
 SectionBoxDialogManager.show() (继承自 BaseDialogManager)
    │   createContent() → 创建 SectionBoxPanel
    │   onDialogCreated()
-    │       └── registry.engine3d?.activateSectionBox()
+    │       └── registry.engine3d?.activeSection('box')
    ▼
-EngineManager.activateSectionBox()
-    │   this.engineInstance.activateSectionBox()
+EngineManager.activeSection('box')
+    │   this.engineInstance.activeSection(mode)
    ▼
-Engine.activateSectionBox()
-    │   this.engine.clipping.sectionBox.active()
+Engine.activeSection('box')
+    │   this.engine.clipping.active('box')
    ▼
-底层引擎 API: engine.clipping.sectionBox.active()
+底层引擎 API: engine.clipping.active('box')
 ```

 #### 调用链 - 调整范围（拖动滑块）
@@ -425,56 +422,16 @@ EngineManager.setSectionBoxRange(range)
    │   this.engineInstance.setSectionBoxRange(range)
    ▼
 Engine.setSectionBoxRange(range)
-    │   this.engine.clipping.sectionBox.setboxPercent(range)  // 直传百分比
+    │   this.engine.clipping.updateClippingValue(range)
    ▼
-底层引擎 API: engine.clipping.sectionBox.setboxPercent(range)
-    │   （底层负责百分比→坐标转换）
+底层引擎 API: engine.clipping.updateClippingValue(range)
 ```

-#### 调用链 - 适应到模型
+#### 调用链 - 适应到模型 / 重置 (已废弃)

-```
-用户点击 [适应到模型] 按钮
-    │
-    ▼
-SectionBoxPanel.onFitToModel()
-    │
-    ▼
-SectionBoxDialogManager 回调
-    │   registry.engine3d?.fitSectionBoxToModel()
-    ▼
-EngineManager.fitSectionBoxToModel()
-    │   this.engineInstance.fitSectionBoxToModel()
-    ▼
-Engine.fitSectionBoxToModel()
-    │   const box = this.engine.octreeBox?.getBoundingBox()
-    │   this.engine.clipping.sectionBox.setBox(box)
-    ▼
-底层引擎 API:
-    - engine.octreeBox.getBoundingBox()
-    - engine.clipping.sectionBox.setBox(box)
-```
-
-#### 调用链 - 重置
-
-```
-用户点击 [重置] 按钮
-    │
-    ▼
-SectionBoxPanel.onReset()
-    │
-    ▼
-SectionBoxDialogManager 回调
-    │   registry.engine3d?.resetSectionBox()
-    ▼
-EngineManager.resetSectionBox()
-    │   this.engineInstance.resetSectionBox()
-    ▼
-Engine.resetSectionBox()
-    │   this.fitSectionBoxToModel()  // 内部调用适应到模型
-    ▼
-（同上 "适应到模型" 流程）
-```
+**注意**: `fitSectionBoxToModel()` 和 `resetSectionBox()` 已从新 API 中移除。
+- 用户点击这些按钮时，现在仅输出日志，不执行任何操作
+- 统一使用 `setSectionBoxRange()` 和 `updateClippingValue()` 调整范围

 #### 调用链 - 关闭对话框

@@ -483,27 +440,26 @@ Engine.resetSectionBox()
    │
    ▼
 SectionBoxDialogManager.onBeforeDestroy()
-    │   registry.engine3d?.deactivateSectionBox()
+    │   registry.engine3d?.deactivateSection()
    ▼
-EngineManager.deactivateSectionBox()
-    │   this.engineInstance.deactivateSectionBox()
+EngineManager.deactivateSection()
+    │   this.engineInstance.deactivateSection()
    ▼
-Engine.deactivateSectionBox()
-    │   this.engine.clipping.sectionBox.disActive()
+Engine.deactivateSection()
+    │   this.engine.clipping.disActive()
    ▼
-底层引擎 API: engine.clipping.sectionBox.disActive()
+底层引擎 API: engine.clipping.disActive()
 ```

-#### 剖切盒 API 汇总
+#### 剖切盒 API 汇总 (新版统一 API)

 | 操作 | Engine 方法 | 底层 API |
 |------|-------------|----------|
-| 激活 | `activateSectionBox()` | `engine.clipping.sectionBox.active()` |
-| 停用 | `deactivateSectionBox()` | `engine.clipping.sectionBox.disActive()` |
-| 设置范围（百分比） | `setSectionBoxRange(range)` | `engine.clipping.sectionBox.setboxPercent(range)` |
-| 设置范围（坐标） | - | `engine.clipping.sectionBox.setboxXyz(xyz)` |
-| 适应到模型 | `fitSectionBoxToModel()` | `engine.clipping.sectionBox.setBox(box)` |
-| 获取包围盒 | - | `engine.octreeBox.getBoundingBox()` |
+| 激活 | `activeSection('box')` | `engine.clipping.active('box')` |
+| 停用 | `deactivateSection()` | `engine.clipping.disActive()` |
+| 设置范围 | `setSectionBoxRange(range)` | `engine.clipping.updateClippingValue(range)` |
+| ~~适应到模型~~ | ~~`fitSectionBoxToModel()`~~ (已废弃) | - |
+| ~~重置~~ | ~~`resetSectionBox()`~~ (已废弃) | - |

 #### 数据格式说明

--- a/docs/引擎API对接.md
+++ b/docs/引擎API对接.md
@@ -113,10 +113,10 @@ export class SectionBoxDialogManager extends BaseDialogManager {
    protected createContent(): HTMLElement {
        this.panel = new SectionBoxPanel({
            onFitToModel: () => {
-                this.registry.engine3d?.fitSectionBoxToModel();  // ← 调用 EngineManager
+                console.log('[SectionBoxDialogManager] Fit to model not supported');
            },
            onReset: () => {
-                this.registry.engine3d?.resetSectionBox();
+                console.log('[SectionBoxDialogManager] Reset not supported');
            },
            onRangeChange: (range) => {
                this.registry.engine3d?.setSectionBoxRange(range);
@@ -128,13 +128,13 @@ export class SectionBoxDialogManager extends BaseDialogManager {

    // 对话框创建后，激活剖切盒
    protected onDialogCreated(): void {
-        this.registry.engine3d?.activateSectionBox();  // ← 调用 EngineManager
+        this.registry.engine3d?.activeSection('box');  // ← 调用 EngineManager 统一 API
        this.dialog?.fitHeight(false);
    }

-    // 对话框销毁前，停用剖切盒
+    // 对话框销毁前，停用剖切
    protected onBeforeDestroy(): void {
-        this.registry.engine3d?.deactivateSectionBox();
+        this.registry.engine3d?.deactivateSection();  // ← 统一停用方法
        // ... 清理
    }

@@ -159,13 +159,29 @@ export class SectionBoxDialogManager extends BaseDialogManager {
 export class EngineManager extends BaseManager {
    private engineInstance: Engine | null = null;

-    // 激活剖切盒
-    public activateSectionBox(): void {
+    // 激活剖切（统一入口）
+    public activeSection(mode: 'x' | 'y' | 'z' | 'box' | 'face'): void {
        if (!this.engineInstance) {
            console.warn('[EngineManager] 3D Engine not initialized.');
            return;
        }
-        this.engineInstance.activateSectionBox();  // ← 调用 Engine 组件
+        this.engineInstance.activeSection(mode);  // ← 调用 Engine 组件
+    }
+
+    // 获取当前剖切模式
+    public getCurrentSectionMode(): 'x' | 'y' | 'z' | 'box' | 'face' | null {
+        if (!this.engineInstance) {
+            return null;
+        }
+        return this.engineInstance.getCurrentSectionMode();
+    }
+
+    // 停用剖切（统一出口）
+    public deactivateSection(): void {
+        if (!this.engineInstance) {
+            return;
+        }
+        this.engineInstance.deactivateSection();
    }

    // 设置剖切盒范围
@@ -193,11 +209,10 @@ export class EngineManager extends BaseManager {
 ```typescript
 export class Engine implements IBimComponent {
    private engine: any = null;                    // 底层引擎实例
-    private isSectionBoxActive: boolean = false;   // 状态标记
-    private sectionBoxFullBounds: any = null;      // 缓存的包围盒
+    private currentSectionMode: 'x' | 'y' | 'z' | 'box' | 'face' | null = null;  // 当前剖切模式

-    // 激活剖切盒
-    public activateSectionBox(): void {
+    // 激活剖切（统一入口）
+    public activeSection(mode: 'x' | 'y' | 'z' | 'box' | 'face'): void {
        if (!this._isInitialized || !this.engine) {
            console.error('[Engine] Cannot activate section box: engine not initialized.');
            return;