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

作为刚接触 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()。

使用建议

• 善用一次性事件：如果某个事件只需要触发一次，回调里立即调用 removeEventListener。
• 场景根对象的事件：仅能获取位置坐标，适合做“全局点击”或“拖拽地图切换模式”之类的功能。
• 粒度控制：能在具体对象上监听就不要放在根节点，粒度越精细，代码越容易维护。
• 性能提示：事件调度器会在帧末集中处理，并做异步、去重等优化，正常使用不必担心性能问题。

---

学习笔记就到这里！事件系统本身并不复杂，关键是熟悉 addEventListener、EventParam 和冒泡这几个核心概念。掌握它们之后，构建交互式地图就顺手多了。希望这份笔记也能帮到你！