@pmndrs/handle 是 three.js 场景中的指针交互变换库。它的核心模型是:把对一个物体(句柄)的指针操作,转换为对另一个物体(目标)的变换;同一个句柄可以在鼠标、触摸、XR 射线或手部抓取等输入方式下工作。
接入方式
句柄监听来自 @pmndrs/pointer-events 的事件,因此需要有东西来派发这些事件:鼠标和触摸通过 forwardHtmlEvents(canvas, () => camera, scene) 转发,XR 输入通过 @pmndrs/xr 的 createXRStore 提供。createXRStore(canvas, scene, camera, renderer.xr) 本身已经会转发鼠标和触摸事件(除非以 htmlInput: false 创建),因此不要再重复做一次转发,否则每个事件都会被收到两次。
指针事件只负责记录输入,真正的变换由 update 计算并应用,所以必须每帧调用 update,否则物体不会移动。资料中的示例依次创建 forwardHtmlEvents、HandleStore、TransformHandles,并在 setAnimationLoop 中每帧调用 updateEvents、store.update(time) 与 transform.update(time, camera),最后渲染。
释放资源时,调用 bind 返回的每个 unbind 函数;DragHandle 使用 dispose(),forwardHtmlEvents 使用 destroy()。要切换 TransformHandles 的模式,先调用其 unbind,再用新模式调用 bind。
句柄类型选择
- 让多个物体可拖拽:使用 new DragHandle(objects),每个物体一个 store。
- 抓取一个物体、变换另一个物体或约束运动:使用 HandleStore(target, getOptions) 绑定到句柄物体。translate、rotate、scale 可接受 false、单个轴或按轴限制(如 { x: false, y: [-1, 1] });translate: 'as-rotate' 把拖拽变成绕目标原点的旋转(门、拉杆、旋钮),'as-scale' 按离中心拉开的距离缩放,'as-rotate-and-scale' 同时做两者。这些模式只使用一个指针。
- 编辑器 gizmo:TransformHandles(一次只处理 translate、rotate、scale 中的一种,space 可取 'world' 或 'local'),或 PivotHandles(同时处理三者,仅本地空间,bind(translation, rotation, scale))。轴选项可接受 false、限制值或 'disabled'(显示为灰色、不可交互)。自定义 gizmo 可把 HandlesContext 与单独的 translate、rotate、scale 句柄类组合使用。
- 屏幕上的相机控制:OrbitHandles(canvas, camera) 或 MapHandles(平面地图、在地面平面上平移),然后 bind(scene, damping),每帧调用 update(deltaMs)。它们只在场景的空物体上监听,因此仅当指针没有命中其他东西时才响应——拖动物体或 gizmo 不会同时移动相机——并且会忽略 XR 指针。可以用 createScreenCameraStore 在多个句柄之间共享相机状态,或用代码驱动它。
响应与控制交互
apply(state, target) 选项会收到每次变化;默认的 defaultApply 会把 state.current 复制到目标上。可以覆盖它来做钳制、吸附,或把变化接入自己的状态。state.first 和 state.last 标记一次交互的开始与结束;state.delta 和 state.offset 分别给出相对上一帧和相对起点的变化。若通过外部状态中转,需要把结果写回目标,因为每次新交互都从目标当前的变换开始。
getState() 在空闲时为 undefined;cancel() 中止当前交互;capture(pointerId, object) 从代码发起一次交互。
常见易错点
- 句柄默认会阻止事件传播,祖先对象收不到句柄交互;嵌套句柄需要在内层设置 stopPropagation: false。
- 如果句柄或目标的父级每帧都在移动,需要设置 alwaysUpdate: true,否则目标只在指针移动时更新。
- 默认开启 multitouch 时,两个指针会同时平移、旋转和缩放;单指针不会缩放,且其旋转跟随控制器的朝向。若只需要单指针移动,使用 rotate: false;若要沿单轴拖拽旋转(转盘、旋钮),使用 translate: 'as-rotate' 搭配 rotate: 'y',其中 rotate 用于限制轴。
- 模式名称必须精确为 translate、rotate、scale。
适用场景与限制
适合 three.js 场景中的物体拖拽、编辑器变换 gizmo、门和旋钮等受限交互、以及屏幕相机控制等场景;也可结合 XR 输入用于 WebXR 交互。限制在于:必须先接入事件派发并每帧调用 update,否则交互无效;资料未提供价格、收费或平台要求等信息。