1

2026-05-13 10:43:06 +08:00
parent 6cefd063f2
commit 223fa5dd4e
19 changed files with 2282 additions and 104 deletions
--- a/DRAG_USAGE.md
+++ b/DRAG_USAGE.md
@ -0,0 +1,169 @@
+# 模型拖拽功能使用说明
+
+## 功能概述
+
+模型拖拽功能允许用户通过鼠标拖动 3D 模型，支持限制轴向移动，同时只能激活一个轴。
+
+## 配置参数
+
+在加载或替换模型时，可以添加 `drag` 参数：
+
+```typescript
+drag: {
+    enable: boolean,      // 是否启用拖拽
+    axis?: string,        // 允许的轴向：'x' | 'y' | 'z' | 'xy' | 'xz' | 'yz' | 'xyz'
+    step?: number,        // 移动步长，默认 0.1
+}
+```
+
+## 使用示例
+
+### 1. 加载模型时配置拖拽
+
+```typescript
+// 单个模型加载
+await mainApp.appModel.add({
+    modelId: 'model1',
+    modelUrl: 'path/to/model.glb',
+    drag: {
+        enable: true,
+        axis: 'y',      // 只允许 Y 轴移动
+        step: 0.1,      // 每次移动 0.1 单位
+    }
+});
+
+// 批量模型加载
+await mainApp.appModel.add([
+    {
+        modelId: 'model1',
+        modelUrl: 'path/to/model1.glb',
+        drag: {
+            enable: true,
+            axis: 'x',
+            step: 0.5,
+        }
+    },
+    {
+        modelId: 'model2',
+        modelUrl: 'path/to/model2.glb',
+        drag: {
+            enable: true,
+            axis: 'xyz',    // 允许所有轴向
+            step: 0.1,
+        }
+    }
+]);
+```
+
+### 2. 替换模型时配置拖拽
+
+```typescript
+await mainApp.appModel.replaceModel({
+    modelId: 'model1',
+    modelUrl: 'path/to/new-model.glb',
+    drag: {
+        enable: true,
+        axis: 'xz',     // 允许 X 和 Z 轴移动
+        step: 0.2,
+    }
+});
+```
+
+### 3. 动态控制拖拽
+
+```typescript
+// 启用/禁用拖拽
+mainApp.appModelDrag.setDragEnabled('model1', true);
+mainApp.appModelDrag.setDragEnabled('model1', false);
+
+// 切换激活的轴向
+mainApp.appModelDrag.switchAxis('model1', 'x');  // 切换到 X 轴
+mainApp.appModelDrag.switchAxis('model1', 'y');  // 切换到 Y 轴
+mainApp.appModelDrag.switchAxis('model1', 'z');  // 切换到 Z 轴
+
+// 获取拖拽配置
+const config = mainApp.appModelDrag.getDragConfig('model1');
+console.log(config);
+```
+
+## 轴向说明
+
+- `'x'`: 只允许沿 X 轴移动
+- `'y'`: 只允许沿 Y 轴移动
+- `'z'`: 只允许沿 Z 轴移动
+- `'xy'`: 允许沿 X 和 Y 轴移动
+- `'xz'`: 允许沿 X 和 Z 轴移动
+- `'yz'`: 允许沿 Y 和 Z 轴移动
+- `'xyz'`: 允许沿所有轴移动（默认）
+
+## 注意事项
+
+1. **同时只能激活一个轴**：即使配置了多个轴（如 'xyz'），拖拽时也只会沿当前激活的轴移动
+2. **默认激活轴**：拖拽开始时，会自动激活配置中的第一个可用轴
+3. **步长控制**：`step` 参数控制移动的精度，值越小移动越精细
+4. **模型根节点**：拖拽功能作用于模型的根节点，会移动整个模型
+5. **相机控制**：拖拽模型时会自动禁用相机转动，松开鼠标后自动恢复相机控制
+
+## 完整示例
+
+```typescript
+import { MainApp } from './babylonjs/MainApp';
+
+// 创建应用
+const mainApp = new MainApp();
+
+// 加载配置
+mainApp.loadAConfig({
+    container: document.getElementById('canvas'),
+    modelUrlList: []
+});
+
+// 初始化
+await mainApp.Awake();
+
+// 添加可拖拽的模型
+await mainApp.appModel.add({
+    modelId: 'draggableModel',
+    modelUrl: 'models/example.glb',
+    drag: {
+        enable: true,
+        axis: 'y',
+        step: 0.1,
+    }
+});
+
+// 监听键盘事件切换轴向
+window.addEventListener('keydown', (e) => {
+    if (e.key === 'x') {
+        mainApp.appModelDrag.switchAxis('draggableModel', 'x');
+        console.log('切换到 X 轴');
+    } else if (e.key === 'y') {
+        mainApp.appModelDrag.switchAxis('draggableModel', 'y');
+        console.log('切换到 Y 轴');
+    } else if (e.key === 'z') {
+        mainApp.appModelDrag.switchAxis('draggableModel', 'z');
+        console.log('切换到 Z 轴');
+    }
+});
+```
+
+## API 参考
+
+### AppModelDrag 类
+
+#### 方法
+
+- `configureDrag(modelId: string, config: DragConfig): void`
+  - 为模型配置拖拽功能
+
+- `getDragConfig(modelId: string): DragConfig | undefined`
+  - 获取模型的拖拽配置
+
+- `setDragEnabled(modelId: string, enable: boolean): void`
+  - 启用/禁用模型拖拽
+
+- `switchAxis(modelId: string, axis: 'x' | 'y' | 'z'): void`
+  - 切换当前激活的轴向
+
+- `dispose(): void`
+  - 清理资源