@pmndrs/pointer-events 用于给普通 three.js 场景提供类似 DOM 的指针事件。对象通过 three 自带的 addEventListener 接收事件,事件名称和语义与 DOM 指针事件一致:pointerdown/up/move/over/out/enter/leave/cancel、click、dblclick、contextmenu、wheel。所有事件源(鼠标、触摸、XR 射线、抓取的手)都被视为指针,因此同一个监听器可处理全部输入。
入口选择:屏幕输入(鼠标、触摸、笔)使用 forwardHtmlEvents(canvas, () => camera, scene);事件命中一个显示其他场景的网格(渲染目标屏幕、传送门、场景内编辑器视口)使用 forwardObjectEvents(mesh, () => innerCamera, innerScene),命中的 uv 会作为内部摄像机的屏幕坐标,因此网格需要 UV;会指向或触摸的跟踪对象(XR 控制器、手、场景中的工具)可使用 createRayPointer 沿对象 -Z 方向生成直线射线,createLinesPointer 生成曲线/折线射线(如传送弧),createGrabPointer 生成由你自己按下/抬起的球体(挤压抓取),createTouchPointer 生成靠近时自动按下的指尖球体。同一只手上的多个指针可注册到一个 CombinedPointer 中,使场景每帧只遍历一次;以 enableMultiplePointers = false 构造时只保留最近的指针处于活动状态。
接入方式示例:const { update, destroy } = forwardHtmlEvents(canvas, () => camera, scene);mesh.addEventListener('click', (e) => console.log(e.point));在 renderer.setAnimationLoop 中调用 update() 以传递自上一帧以来批量收集的 DOM 事件,再 renderer.render(scene, camera);销毁时调用 destroy()。事件默认批处理,只在 update() 内传递;若不调用 update() 则不会触发。批处理会把处理函数移出浏览器的用户手势调用栈,因此需要手势才能执行的操作(播放视频、在 Safari 中打开文件选择器)在 click 处理函数中会失败,此时可传 { batchEvents: false },或在场景并非每帧渲染时使用。当对象在静止鼠标下移动且悬停应跟随它们时,传 intersectEveryFrame: true。自己创建的指针需要每帧驱动:pointer.move(scene, { timeStamp }),输入时调用 down/up({ timeStamp, button }),输入源消失时调用 exit(...),使悬停对象收到 pointerout/pointerleave。指针读取空间对象的 matrix 而非 position/rotation,因此移动前要更新矩阵;在最后一次渲染后移动的对象需要在 move/update 前调用 scene.updateMatrixWorld()。
命中对象规则:pointerEvents 类似 CSS 并可继承,'none' 排除对象(子对象可用 'auto' 重新加入),'auto' 总是命中;默认是 'listener',即对象自身或祖先有指针监听器时才被命中。没有监听器的内容(粒子、装饰、透明覆盖层)既不接收事件也不阻挡事件;因此监听器挂在 Scene 上会让整个场景可命中。pointerEventsType 按指针类型过滤,如 { allow: 'ray' }、{ deny: ['grab', 'touch'] } 或函数;类型包括 DOM 输入的 screen-mouse、screen-touch、screen-pen,创建指针的 ray、lines、grab、touch,以及 forwardObjectEvents 内的 forward-<外层类型>。常见用法是在按钮上设置 { deny: 'grab' },避免手穿过时误点击。pointerEventsOrder(数值高者优先,类似 renderOrder)优先于距离,可让透视覆盖层或 gizmo 优先于其内部对象;抓取和触摸指针只按距离排序。这些属性不会被 object.clone() 复制。
易错点:拖拽时在 pointerdown 中调用 e.object.setPointerCapture(e.pointerId),后续事件会发送到该对象即使指针离开它,e.point 会继续沿最初命中面的平面跟随指针;捕获在 up、cancel、exit 时释放;e.pointerId 是 3D 指针 id,不是 DOM id。未命中任何对象的指针会命中场景的 void 对象(getVoidObject(scene),带 isVoidObject 标记),这些事件会冒泡到场景上的监听器,因此场景级 click 监听器也会在空白处触发;可检查 e.object.isVoidObject 或监听 void 对象来处理“点击空白”。click、dblclick、contextmenu 是在同一对象上的 pointerdown/pointerup 合成而来,而非取自 DOM。pointerenter/pointerleave 不冒泡,其他事件通过 .parent 冒泡并遵循 stopPropagation()。在 React Three Fiber 中,本包与 R3F 自带事件系统同时使用会导致事件触发两次;@react-three/xr 的 noEvents 加 PointerEvents 会用本系统替换 R3F 的事件系统。
适用场景:在 three.js 场景中实现点击、悬停、拖拽与指针捕获;为 XR 控制器、手部抓取、触摸或射线交互提供统一事件模型;在场景内嵌入可交互屏幕或视口。限制与前提:事件默认需每帧调用 update() 才传递,需要用户手势的操作要关闭批处理,自行创建的指针需手动驱动并维护矩阵,上述属性不随 clone 复制,且与 R3F 事件系统共存需专门替换。