# 模型拖拽功能使用说明

## 功能概述

模型拖拽功能允许用户通过鼠标拖动 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`
  - 清理资源