threejs-controls

何时使用此技能

用户提到以下内容时，务必使用此技能：

• 围绕目标进行轨道旋转／平移／推拉、惯性／阻尼、最小／最大距离／极角
• 类似地图的平移（MapControls）或飞行（FlyControls）
• 使用 TransformControls 变换控件进行平移／旋转／缩放
• 在平面上拖动对象（DragControls）、指针锁定 FPS（PointerLockControls）

重要：controls 与 webxr 的区别

上下文	技能
桌面端／浏览器摄像机导航	threejs-controls
XR 控制器姿态	threejs-webxr

触发短语包括：

• “OrbitControls”、“TransformControls”、“MapControls”、“PointerLockControls”
• “轨道”、“变换控制器”、“漫游”

如何使用此技能

1. 从 addons 路径导入（threejs-dev-setup）。
2. 使用 (camera, domElement) 构造；对于 TransformControls，还要附加到渲染器事件。
3. 动画循环：启用 enableDamping 时，每帧调用 controls.update()。
4. TransformControls：将 dragging-changed 连接到临时禁用 Orbit；与 threejs-objects 中的选择状态同步。
5. 约束：设置最小／最大距离／角度，以避免视角翻转或进入地下。
6. 释放资源：拆除时调用 controls.dispose()。

参见 examples/workflow-orbit-damping.md。

文档索引（官方）

文档部分	代表性链接
Controls	https://threejs.org/docs/OrbitControls.html
Controls	https://threejs.org/docs/TransformControls.html
Controls	https://threejs.org/docs/MapControls.html
Controls（索引）	https://threejs.org/docs/#Controls

范围

• 范围内： 官方 addons 控件的使用模式。
• 范围外： 完整的物理角色控制器；移动端手势框架。

常见问题与最佳实践

• 启用阻尼后忘记调用 update()，会导致漂移一直无法停止。
• TransformControls 与 Orbit 相互冲突——使用其中一个时暂停另一个。
• 指针锁定需要用户手势，并需处理退出逻辑。

文档与版本

控件位于 three.js 文档的 Controls（Addons）中。API 细节（enableDamping、事件）会不断变化——请链接到与用户所用 three.js 版本对应的 OrbitControls／TransformControls 页面。

Agent 回答检查清单

使用此技能回答时，优先做到以下几点：

1. 链接文档中对应的控件类。
2. 说明启用阻尼时，每帧都要调用 controls.update()。
3. 将 TransformControls 与选择状态／threejs-objects 射线检测协调起来。
4. 区分桌面端导航与 threejs-webxr 移动方式。
5. 卸载画布时，对控件调用 dispose()。

参考资料

• https://threejs.org/docs/#Controls
• https://threejs.org/docs/OrbitControls.html
• https://threejs.org/docs/TransformControls.html

关键词

English： orbitcontrols、transformcontrols、mapcontrols、阻尼、摄像机控件、three.js

中文： OrbitControls、轨道、TransformControls、变换控制器、阻尼、three.js