SuperAPI AI 工具集

pointer-events

前端与建站

查看项目

更新于 11-08 11:40

技能介绍

用途

pointer-events 用于把真实输入转发进 Three.js 场景,使 3D 对象能够触发指针监听器,并按需过滤哪些对象被命中,同时允许自定义指针本身的形状与相交计算方式。

主要能力

库建立在三个核心机制上:

  1. 转发输入:forwardHtmlEvents 把 HTML 文档的 DOM 事件转发进 3D 场景;forwardObjectEvents 把某个表面(例如一个平面)上的事件转发到一个独立的门户场景,形成可交互的“传送门”。两者都会返回一个 update(),需要每帧调用。
  2. 过滤命中:对象上的 pointerEvents 属性(取自 CSS 语义:none/listener/auto)决定该对象是否可被直接命中;pointerEventsType 属性(all/allow/deny/function)按指针类型过滤。
  3. 自定义指针:可以自行构造 Pointer,并选择用普通 Ray、一组 Line 或用于 grab/touch 事件的 Sphere 来计算相交,例如让第一人称控制器与其环境交互。

使用方式

使用 forwardHtmlEvents(document.body, () => camera, scene) 转发 DOM 事件,返回 { update };在渲染循环中、renderer.render 之前调用 update()。随后对象通过 addEventListener('pointerover' | 'pointerout', (e: PointerEvent) => ...) 接收事件,PointerEvent 需从 @pmndrs/pointer-events 导入,事件提供 e.point(可用 e.point.toArray()),同类型可挂多个监听器。

使用 forwardObjectEvents(planeMesh, () => portalCamera, portalScene) 转发表面事件,返回自己的 update(示例中命名为 updatePortal),需与主 update() 一起每帧调用。

过滤方面,pointerEvents 取值:none 表示永不被直接命中;auto 表示始终可被命中;listener 为默认值,仅当对象挂有监听器时才被命中(对含粒子等半透明内容的 3D 场景更合理)。pointerEventsType 默认为 all,可设为 { allow: "screen-mouse" } 或 { deny: "screen-touch" },allow 与 deny 接受字符串或字符串数组,也可传入函数实现自定义逻辑。默认指针类型包括 screen-touch、screen-pen、ray、grab、touch;DOM 转发的事件带 screen- 前缀,门户转发的事件带 forward- 前缀。

适用场景

为 Three.js 场景中的 3D 网格、门户式界面添加点击/悬停交互;对半透明粒子等内容默认不拦截指针;按鼠标、触摸、射线等指针类型分别控制交互;配合第一人称控制器实现自定义指针交互。

限制与注意事项

克隆 Mesh/Object3D 时 pointerEvents 属性不会被复制,需要在克隆体上重新设置。资料未提供安装命令、收费方式或具体版本要求。