170 lines
4.1 KiB
Markdown
170 lines
4.1 KiB
Markdown
# 模型拖拽功能使用说明
|
||
|
||
## 功能概述
|
||
|
||
模型拖拽功能允许用户通过鼠标拖动 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`
|
||
- 清理资源
|