From 6db24d23bb7e22d07a41cac7da776fe8e396cd78 Mon Sep 17 00:00:00 2001
From: yuding <1023798085@qq.com>
Date: Mon, 2 Feb 2026 16:30:07 +0800
Subject: [PATCH] docs(code): add JSDoc comments for clipping API methods

Add comprehensive documentation for:
- activeSection(mode): Unified activation API with mode descriptions
- getCurrentSectionMode(): Current mode getter
- setSectionBoxRange(range): Box range setter with percentage format
- deactivateSection(): Unified deactivation

Includes @param, @returns, @remarks, and @example sections in Chinese.
---
 src/components/engine/index.ts | 60 ++++++++++++++++++++++++++++++++++
 src/managers/engine-manager.ts | 18 ++++++++--
 2 files changed, 76 insertions(+), 2 deletions(-)

diff --git a/src/components/engine/index.ts b/src/components/engine/index.ts
index 1688a2a..6bdbb49 100644
--- a/src/components/engine/index.ts
+++ b/src/components/engine/index.ts
@@ -425,6 +425,27 @@ export class Engine implements IBimComponent {
 
     // ==================== 剖切功能（统一 API） ====================
 
+    /**
+     * 激活剖切功能（统一入口）
+     * @param mode 剖切模式
+     *   - 'x': X轴剖切面
+     *   - 'y': Y轴剖切面
+     *   - 'z': Z轴剖切面
+     *   - 'box': 剖切盒（六面体裁剪）
+     *   - 'face': 拾取面剖切（点选模型表面创建剖切面）
+     * @remarks
+     * - 幂等操作：如果当前模式与请求模式相同，则静默返回
+     * - 切换模式时会自动停用之前的剖切
+     * - 底层调用 engine.clipping.active(mode)
+     * @example
+     * ```typescript
+     * // 激活 X 轴剖切
+     * engine.activeSection('x');
+     * 
+     * // 切换到剖切盒
+     * engine.activeSection('box');
+     * ```
+     */
     public activeSection(mode: 'x' | 'y' | 'z' | 'box' | 'face'): void {
         if (!this._isInitialized || !this.engine?.clipping) {
             console.error('[Engine] Cannot activate section: engine not initialized.');
@@ -439,10 +460,37 @@ export class Engine implements IBimComponent {
         this.currentSectionMode = mode;
     }
 
+    /**
+     * 获取当前激活的剖切模式
+     * @returns 当前剖切模式，未激活时返回 null
+     * @example
+     * ```typescript
+     * const mode = engine.getCurrentSectionMode();
+     * if (mode === 'box') {
+     *     console.log('剖切盒已激活');
+     * }
+     * ```
+     */
     public getCurrentSectionMode(): 'x' | 'y' | 'z' | 'box' | 'face' | null {
         return this.currentSectionMode;
     }
 
+    /**
+     * 设置剖切盒范围
+     * @param range 剖切范围配置，每个轴的 min/max 值为百分比 (0-100)
+     * @remarks
+     * - 仅在 'box' 模式下有效
+     * - 底层调用 engine.clipping.updateClippingValue(range)
+     * @example
+     * ```typescript
+     * // 设置 X 轴裁剪 20%-80%，Y/Z 轴保持完整
+     * engine.setSectionBoxRange({
+     *     x: { min: 20, max: 80 },
+     *     y: { min: 0, max: 100 },
+     *     z: { min: 0, max: 100 }
+     * });
+     * ```
+     */
     public setSectionBoxRange(range: SectionBoxRange): void {
         if (!this._isInitialized || !this.engine?.clipping) {
             console.error('[Engine] Cannot set section box range: engine not initialized.');
@@ -452,6 +500,18 @@ export class Engine implements IBimComponent {
         this.engine.clipping.updateClippingValue(range);
     }
 
+    /**
+     * 停用所有剖切功能
+     * @remarks
+     * - 统一停用入口，无论当前是哪种剖切模式
+     * - 关闭剖切对话框时调用此方法
+     * - 底层调用 engine.clipping.disActive()
+     * @example
+     * ```typescript
+     * // 关闭剖切
+     * engine.deactivateSection();
+     * ```
+     */
     public deactivateSection(): void {
         if (!this._isInitialized || !this.engine?.clipping) {
             return;
diff --git a/src/managers/engine-manager.ts b/src/managers/engine-manager.ts
index ff51888..365bb80 100644
--- a/src/managers/engine-manager.ts
+++ b/src/managers/engine-manager.ts
@@ -255,8 +255,9 @@ export class EngineManager extends BaseManager {
     }
 
     /**
-     * 激活轴向剖切
-     * @param axis 要激活的轴向 ('x' | 'y' | 'z')
+     * 激活剖切功能（统一入口）
+     * @param mode 剖切模式: 'x' | 'y' | 'z' (轴向剖切) | 'box' (剖切盒) | 'face' (拾取面剖切)
+     * @remarks 代理调用 Engine.activeSection(mode)
      */
     public activeSection(mode: 'x' | 'y' | 'z' | 'box' | 'face'): void {
         if (!this.engineInstance) {
@@ -266,6 +267,10 @@ export class EngineManager extends BaseManager {
         this.engineInstance.activeSection(mode);
     }
 
+    /**
+     * 获取当前激活的剖切模式
+     * @returns 当前剖切模式，未激活时返回 null
+     */
     public getCurrentSectionMode(): 'x' | 'y' | 'z' | 'box' | 'face' | null {
         if (!this.engineInstance) {
             return null;
@@ -273,6 +278,10 @@ export class EngineManager extends BaseManager {
         return this.engineInstance.getCurrentSectionMode();
     }
 
+    /**
+     * 停用所有剖切功能
+     * @remarks 关闭剖切对话框时调用
+     */
     public deactivateSection(): void {
         if (!this.engineInstance) {
             return;
@@ -280,6 +289,11 @@ export class EngineManager extends BaseManager {
         this.engineInstance.deactivateSection();
     }
 
+    /**
+     * 设置剖切盒范围
+     * @param range 各轴的剖切范围 (百分比 0-100)
+     * @remarks 仅在 'box' 模式下有效
+     */
     public setSectionBoxRange(range: SectionBoxRange): void {
         if (!this.engineInstance) {
             console.warn('[EngineManager] 3D Engine not initialized.');