zhengte.babylonjs-sdk/DRAG_USAGE.md

模型拖拽功能使用说明

功能概述

模型拖拽功能允许用户通过鼠标拖动 3D 模型，支持限制轴向移动，同时只能激活一个轴。

配置参数

在加载或替换模型时，可以添加 drag 参数：

drag: {
    enable: boolean,      // 是否启用拖拽
    axis?: string,        // 允许的轴向：'x' | 'y' | 'z' | 'xy' | 'xz' | 'yz' | 'xyz'
    step?: number,        // 移动步长，默认 0.1
}

使用示例

1. 加载模型时配置拖拽

// 单个模型加载
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. 替换模型时配置拖拽

await mainApp.appModel.replaceModel({
    modelId: 'model1',
    modelUrl: 'path/to/new-model.glb',
    drag: {
        enable: true,
        axis: 'xz',     // 允许 X 和 Z 轴移动
        step: 0.2,
    }
});

3. 动态控制拖拽

// 启用/禁用拖拽
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. 相机控制：拖拽模型时会自动禁用相机转动，松开鼠标后自动恢复相机控制

完整示例

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

  • 清理资源