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()`~~ (已废弃) | - |

 #### 数据格式说明