JSAPIThree 事件系统学习笔记：处理交互的基础

时间：2025-11-26 11:00

人气：

作者：admin

标签：

导读：以初学者视角梳理 JSAPIThree（mapvthree）的事件系统，介绍如何在 3D 场景中绑定事件、读取事件参数，以及掌握事件冒泡与性能要点。...

作为刚接触 mapvthree 的新手，今天我专门学习了事件系统。这里汇总最实用的内容，帮助和我一样的初学者快速掌握交互的核心用法。

绑定与移除事件，只需记住 add/remove

mapvthree 复用了 Three.js 的 addEventListener / removeEventListener，所以任何继承自 Object3D 的对象都能直接绑定事件。引擎内部的调度器会帮我们处理拾取、命中检测等复杂逻辑，我们只需要专注于“监听哪一个对象”和“响应什么事件”。

const box = engine.add(new THREE.Mesh(
    new THREE.BoxGeometry(10, 10, 10),
    new THREE.MeshBasicMaterial({color: 0xaa0000}),
));

const handleClick = (e) => {
    console.log('盒子被点击，地理坐标：', e.point);
    box.removeEventListener('click', handleClick); // 一次性事件
};

box.addEventListener('click', handleClick);

常见事件：click、dblclick、mousemove、mouseenter、mouseleave、pointerdown、pointerup 等
一定记得在物体移除或销毁前调用 removeEventListener，避免内存泄漏

EventParam 里的信息足够丰富

每次事件触发，回调都会收到统一的 EventParam，其中最常用的字段如下：

属性	说明
`target` / `currentTarget`	触发事件的对象、绑定事件的对象
`position`	鼠标在世界坐标中的位置（Array[3]）
`point`	鼠标在地理坐标中的位置（经纬度）
`index` / `entity`	当事件来自支持 `dataSource` 的图层时，可获取对应的数据索引和实体
`event`	原始浏览器事件对象

box.addEventListener('mousemove', (e) => {
    if (e.position) {
        helper.position.fromArray(e.position); // 在 3D 空间显示鼠标所在点
    }
});

注意：当事件绑定在 engine.map 这类场景根对象上时，只能拿到 position 和 point，其它字段不存在。

事件不仅限于几何体，根对象也能监听

可以在可视化图层、地图根节点甚至 engine.map 上绑定事件，从而实现不同层级的交互。例如：

engine.map.addEventListener('pointerdown', () => {
    engine.clock.currentTime = new Date('2025-05-15 18:00:00');
});
engine.map.addEventListener('pointerup', () => {
    engine.clock.currentTime = new Date('2025-05-15 14:00:00');
});

这段代码演示了如何在地图级别监听按下/抬起事件，并根据交互切换天空时间。

事件冒泡：必要时调用 stopPropagation

事件从子节点向父节点冒泡，沿着场景树一直传递到根对象。我们可以利用冒泡做统一处理，也可以在需要时阻止冒泡。

ear.addEventListener('click', (e) => {
    alert('点击到了耳朵');
    e.stopPropagation(); // 阻止继续触发头部或整个人的点击事件
});
head.addEventListener('click', () => alert('点击到了头像'));
human.addEventListener('click', () => alert('点击到了整个人'));

当需要在某个层级拦截事件时，记得调用 stopPropagation()。