怎么在 Babylon.js 中实现鼠标点击与悬停交互

一、底层原理：从屏幕坐标到 3D 拾取

在传统的网页 DOM 开发中，浏览器会自动帮我们处理每一个按钮和链接的 :hover 状态与 click 事件。但在 WebGL 画布（<canvas>）中，整个三维世界本质上只是逐帧绘制在同一个画布上的像素矩阵，浏览器无法感知画布内部哪块区域属于哪个 3D 模型。

为了在三维空间中感知鼠标的位置，Babylon.js 内部依赖一套完整的射线拾取（Raycasting）管线：

1. 监听原生指针事件：引擎监听 Canvas 元素的原生 pointermove、pointerdown 和 pointerup 事件，捕获当前鼠标相对于视口的物理像素坐标。
2. 投影反向计算：利用当前活动相机（scene.activeCamera）的视图投影逆矩阵，从相机近裁剪面穿过鼠标坐标，向三维世界空间发射一条不可见的虚拟射线（BABYLON.Ray）。
3. 相交几何判定：引擎遍历场景中处于视锥体内的网格，先对包围盒（Bounding Box）进行粗筛，再对具体三角面进行相交计算，计算出射线最近碰撞到的网格对象，并包装为 PickingInfo 数据结构。
4. 事件分发通道：命中结果会被同时传递给两条互不干扰的分发轨道——若网格绑定了 ActionManager，则由网格内部的状态机触发对应动作；同时向全局的 scene.onPointerObservable 广播事件。

了解这个流程非常关键。很多初学者遇到“鼠标移上去完全没反应”的问题，其根源往往不是代码逻辑有误，而是在第二步或第三步中射线被意外阻挡或网格未开启拾取检测。

二、标准解法：使用 ActionManager 实现点击与悬停

BABYLON.ActionManager 是官方提供的声明式交互机制。每个网格都可以绑定独立的动作管理器，它可以自动追踪鼠标的移入与移出，甚至自动切换鼠标悬停时的光标样式，是实现局部物体交互最简单、最高效的手段。

1. 完整示例代码

下面的代码展示了如何为一个立方体网格绑定点击放大、悬停高亮与光标切换功能。这段代码可以直接嵌入到标准的 Babylon.js 场景初始化函数中执行：

// 1. 创建目标网格并设置材质
const box = BABYLON.MeshBuilder.CreateBox("interactiveBox", { size: 2 }, scene);
const mat = new BABYLON.StandardMaterial("boxMat", scene);
mat.diffuseColor = new BABYLON.Color3(0.2, 0.4, 0.6);
box.material = mat;

// 2. 确认网格开启拾取（默认即为 true）
box.isPickable = true;

// 3. 实例化 ActionManager 并挂载到网格
box.actionManager = new BABYLON.ActionManager(scene);

// 4. 配置鼠标悬停时的指针手势（自动变为小手）
box.actionManager.hoverCursor = "pointer";

// 5. 注册鼠标悬停移入动作（高亮）
box.actionManager.registerAction(
  new BABYLON.ExecuteCodeAction(
    BABYLON.ActionManager.OnPointerOverTrigger,
    (evt) => {
      mat.diffuseColor = new BABYLON.Color3(0.4, 0.6, 0.6); // 灰青高亮
      box.scaling.setAll(1.08); // 微微放大反馈
    }
  )
);

// 6. 注册鼠标悬停移出动作（恢复原状）
box.actionManager.registerAction(
  new BABYLON.ExecuteCodeAction(
    BABYLON.ActionManager.OnPointerOutTrigger,
    (evt) => {
      mat.diffuseColor = new BABYLON.Color3(0.2, 0.4, 0.6); // 恢复基础色
      box.scaling.setAll(1.0); // 恢复原始尺寸
    }
  )
);

// 7. 注册鼠标点击动作
box.actionManager.registerAction(
  new BABYLON.ExecuteCodeAction(
    BABYLON.ActionManager.OnPickTrigger,
    (evt) => {
      console.log("点击了网格：", evt.source.name);
      // 点击反馈：沿 Y 轴旋转 45 度
      box.rotation.y += Math.PI / 4;
    }
  )
);

2. 核心 API 细节解析

• hoverCursor 属性：通过给 box.actionManager.hoverCursor = "pointer" 赋值，当鼠标移入该网格表面时，画布的 CSS 光标样式会自动切换为指定值（如 pointer、grab、crosshair 等）；当鼠标离开时，引擎会自动恢复为画布默认光标。开发者无需在 JavaScript 中手动操作 DOM 样式。
• OnPickTrigger 与 OnPickDownTrigger 的区别：
  • OnPickDownTrigger：只要鼠标左键按下（PointerDown）就会立即触发。缺点是如果用户本意是按住鼠标旋转场景镜头（ArcRotateCamera），也会误触发点击。
  • OnPickTrigger：鼠标按下并在同一个物体上释放时才触发。而且如果用户拖拽了镜头一段距离，引擎会自动过滤掉点击事件，因此通常推荐首选 OnPickTrigger。
• 多种点击触发器支持：除了通用的 OnPickTrigger，Babylon.js 还细分了 OnLeftPickTrigger（左键点击）、OnRightPickTrigger（右键点击）以及 OnDoublePickTrigger（双击），可根据交互需求直接选用。

三、全局控制：使用 scene.onPointerObservable

虽然 ActionManager 简单易用，但在某些复杂项目中，例如具有数百个动态加载的设备模型、或者需要实现框选、多选、交互状态总线时，为每一个网格单独 new 一个 ActionManager 会显得代码分散，且增加内存开销。这时更推荐使用场景级的 onPointerObservable。

1. 响应式事件监听代码

以下代码展示了如何在一个集中的监听器中统一管理全场景网格的悬停高亮与点击：

// 维护当前处于悬停状态的网格引用
let currentHoveredMesh = null;

// 添加场景指针事件观察者
scene.onPointerObservable.add((pointerInfo) => {
  switch (pointerInfo.type) {
    case BABYLON.PointerEventTypes.POINTERMOVE: {
      // 检查当前射线是否击中任何网格
      const pick = pointerInfo.pickInfo;
      const hitMesh = (pick && pick.hit) ? pick.pickedMesh : null;

      if (hitMesh !== currentHoveredMesh) {
        // 1. 触发先前网格的“移出”逻辑
        if (currentHoveredMesh) {
          currentHoveredMesh.renderOutline = false;
        }

        // 2. 更新当前悬停网格
        currentHoveredMesh = hitMesh;

        // 3. 触发新网格的“移入”逻辑与光标切换
        if (currentHoveredMesh && currentHoveredMesh.isPickable) {
          currentHoveredMesh.renderOutline = true;
          currentHoveredMesh.outlineColor = new BABYLON.Color3(0.4, 0.61, 0.61);
          currentHoveredMesh.outlineWidth = 0.05;
          scene.hoverCursor = "pointer";
        } else {
          scene.hoverCursor = "default";
        }
      }
      break;
    }

    case BABYLON.PointerEventTypes.POINTERTAP: {
      // POINTERTAP 代表点击动作（由引擎内部根据位移阈值判定，非简单按下）
      const pick = pointerInfo.pickInfo;
      if (pick && pick.hit && pick.pickedMesh) {
        console.log("全局监听捕获到点击：", pick.pickedMesh.name);
        console.log("世界坐标交点：", pick.pickedPoint);
      }
      break;
    }
  }
});

四、方案对比与技术选型

在实际工程开发中，选择哪种方案取决于项目的网格规模与架构需求。下表梳理了关键特性的横向对比：

五、常见问题与避坑排障

1. 为什么点击或悬停完全没有响应？

如果发现代码无报错但鼠标交互没有任何反应，可以按以下顺序依次排查：

• 检查 isPickable：确认目标网格及其子网格没有被显式设置为 mesh.isPickable = false。如果使用了 SceneLoader 导入 glTF/GLB 模型，部分工具导出的网格默认可能会禁用拾取，可遍历子网格执行 m.isPickable = true。
• 检查是否被不可见网格遮挡：在 3D 场景中，天空盒（Skybox）、透明环境球或辅助地面也是网格。如果它们的 isPickable 保持为默认的 true，射线就会先打在它们身上，导致下方的模型永远接收不到光标。必须将环境与装饰性物体的拾取显式关闭：skybox.isPickable = false;。
• 检查 Canvas 容器的 CSS 属性：检查 HTML 页面中 <canvas> 上方是否有透明的浮动 <div>、弹窗或加载遮罩。如果遮罩层拦截了指针事件，或者 canvas 设置了 pointer-events: none;，WebGL 引擎就无法收到任何鼠标输入。

2. 如何避免相机旋转（拖拽视角）与点击冲突？

当使用 ArcRotateCamera 时，用户需要按住鼠标拖拽来旋转视角。如果不加以区分，当用户松开鼠标时很容易误触模型点击事件。解决方法是：

• 若使用 ActionManager：坚决使用 OnPickTrigger，严禁在交互业务中使用 OnPickDownTrigger。引擎内部会记录按下与抬起时的像素位移，当拖拽距离超过阈值时，自动丢弃点击判定。
• 若使用 Observable：优先监听 BABYLON.PointerEventTypes.POINTERTAP，而不是监听 POINTERUP。POINTERTAP 是引擎专为无拖拽点击优化的事件类型。

3. 复杂模型鼠标悬停掉帧怎么优化？

鼠标悬停需要每当鼠标移动一像素就执行一次相交测试（pointermove）。如果场景中有一个数十万面的高精模型，逐三角面求交会瞬间拉低帧率。以下是两项关键优化手段：

• 使用轻量代理包围网格（Proxy Mesh）：将高精模型的 isPickable 设为 false。为它创建一个尺寸相仿的不可见简易立方体（Box）或胶囊体，将简易立方体的 visibility = 0 但保留 isPickable = true，并将交互事件绑定在代理网格上。
• 配置 scene.pointerMovePredicate：

  // 只对标记了 hasInteraction 属性的网格进行鼠标移动检测
  scene.pointerMovePredicate = (mesh) => {
    return mesh.isPickable && mesh.metadata && mesh.metadata.hasInteraction;
  };

  通过这个过滤函数，引擎在执行鼠标移动射线检测时会直接跳过 95% 以上的背景装饰网格，显著降低 CPU 消耗。

六、总结

在 Babylon.js 中构建鼠标点击与悬停交互十分直观。在绝大多数常规功能开发中，mesh.actionManager 凭借内置的 hoverCursor、丰富的触发器枚举以及简洁的 API，提供了开发效率最高、表现最稳定的落地方案；而当面对大规模动态资产、需要细粒度性能裁剪或深度定制事件流时，scene.onPointerObservable 配合 pointerMovePredicate 则能提供极致的控制力。

在实际编码中，只要牢记确认 isPickable、关闭背景环境网格的拾取干扰、优先使用 OnPickTrigger 消解相机拖拽冲突，就能构建出流畅、自然的 3D 鼠标交互体验。