·
系列文章目录
Three.js 快速入门教程【一】开启你的 3D Web 开发之旅
Three.js 快速入门教程【二】透视投影相机
Three.js 快速入门教程【三】渲染器
Three.js 快速入门教程【四】三维坐标系
Three.js 快速入门教程【五】动画渲染循环
Three.js 快速入门教程【六】相机控件 OrbitControls
Three.js 快速入门教程【七】常见几何体类型
文章目录
一、前言
在3D可视化开发中，用户交互体验直接影响项目的成败。OrbitControls 是 Three.js 库中一个非常实用的相机控制辅助工具，它能极大地增强用户与 3D 场景的交互性，让用户可以像在现实世界中观察物体一样对场景进行操作，从而更好地观察 3D 场景。
二、OrbitControls控件作用
OrbitControls作为官方推荐的交互解决方案，能够实现：
鼠标拖拽旋转视图
滚轮缩放场景
平移观察视角
移动端触摸支持
三、工作原理
OrbitControls 会监听鼠标事件（如鼠标移动、鼠标滚轮滚动、鼠标按键点击等），根据用户的操作实时计算相机应该移动到的新位置和角度，然后更新相机的相关属性，从而改变相机在 3D 场景中的视角。例如，当用户按下鼠标左键并拖动时，OrbitControls 会计算鼠标移动的距离和方向，进而旋转相机；当用户滚动鼠标滚轮时，它会根据滚轮的滚动量来缩放相机。
操作指南:
- 旋转功能：用户按下鼠标左键并拖动，可以围绕一个目标点旋转相机，就像在现实中围绕一个物体走动观察一样。这样可以从不同的角度查看场景中的物体，全面了解其外观和结构。
- 平移功能：按下鼠标右键并拖动，能够在水平和垂直方向上平移相机。这在需要查看场景中特定区域或者调整观察范围时非常有用。
- 缩放功能：滚动鼠标滚轮可以实现相机的缩放操作，拉近或拉远与场景中物体的距离，以便更清晰地观察细节或者查看整个场景的全貌。
三、项目中添加 OrbitControls 控件
1、新建控件实例
const controls=new OrbitControls(camera, domElement);
构造函数接受两个参数：
camera：要控制的相机对象。
domElement：用于监听鼠标事件的 DOM 元素，通常是渲染器的 DOM 元素。
2、更新控件状态
controls.update()
该方法用于更新控件的状态，通常在每一帧渲染时调用。如果启用了阻尼效果，必须在每一帧调用此方法，以确保阻尼效果正常工作。
示例：
// 创建 OrbitControls 控件
const controls = new OrbitControls(camera, renderer.domElement);
// 设置阻尼（惯性），让控件的操作更平滑
controls.enableDamping = true;
controls.dampingFactor = 0.05;
// 更新控件
function animate() {
requestAnimationFrame(animate);
// 必须每帧更新！
controls.update();
renderer.render(scene, camera);
}
animate();
在上述代码中，我们创建了 OrbitControls 实例，然后启用了阻尼效果，并设置了阻尼因子，这样在操作相机时会有惯性的感觉，让交互更加自然。同时，在 animate 函数中，我们调用 controls.update() 方法来更新控件的状态，确保相机能够根据用户的操作实时更新。
四、OrbitControls 属性
常用属性大全：
| 属性名称 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| enableDamping | Boolean | 用于启用或禁用阻尼（惯性）效果，启用后，相机的运动会更平滑，就像有惯性一样 | false |
| dampingFactor | Number | 用于控制阻尼（惯性）效果强度的属性，通常取值范围在 0 到 1 之间 | 0.05 |
| autoRotate | Boolean | 相机是否围绕着目标点自动旋转 | false |
| autoRotateSpeed | Number | 自动旋转的速度 | 1.0 |
| enableRotate | Boolean | 用于控制是否启用鼠标旋转相机 | true |
| enablePan | Boolean | 用于控制是否启用鼠标平移相机 | true |
| enablePan | Boolean | 用于控制是否启用鼠标滚轮缩放相机 | true |
| maxDistance | Number | 设置相机到目标点的最大距离，限制缩放范围 | Infinity |
| minDistance | Number | 设置相机到目标点的最小距离，限制缩放范围 | 0 |
| minPolarAngle | Number | 相机垂直方向的最小角度（弧度制） | 0 |
| maxPolarAngle | Number | 相机垂直方向的最大角度（弧度制） | Math.PI |
| minAzimuthAngle | Number | 相机水平方向的最小角度（弧度制） | -Infinity |
| maxAzimuthAngle | Number | 相机水平方向的最大角度（弧度制） | Infinity |
| target | THREE.Vector3对象 | 相机观察目标点 | new THREE.Vector3(0, 0, 0) |
| screenSpacePanning | Boolean | 相机的平移操作是否基于屏幕空间 | true |
| mouseButtons | Object | 配置鼠标按钮与相机控制操作之间的映射关系。通过修改这个属性，你可以自定义鼠标不同按键对应的操作，默认鼠标左键旋转（THREE.MOUSE.ROTATE），滚轮缩放（THREE.MOUSE.DOLLY），右键平移（THREE.MOUSE.PAN） | { LEFT: THREE.MOUSE.ROTATE,MIDDLE: THREE.MOUSE.DOLLY, RIGHT: THREE.MOUSE.PAN } |
1、基础行为控制
controls.enableDamping = true; // 启用阻尼惯性
controls.dampingFactor = 0.05; // 惯性系数（0-1）
controls.autoRotate = true; // 启用自动旋转
controls.autoRotateSpeed = 2.0; // 旋转速度（默认1.0）
controls.enableZoom = false; // 禁用缩放
controls.enablePan = false; // 禁用平移
2、 视角限制
controls.minDistance = 3; // 最小缩放距离
controls.maxDistance = 50; // 最大缩放距离
controls.minPolarAngle = Math.PI/4; // 垂直视角下限（弧度）
controls.maxPolarAngle = Math.PI/2; // 垂直视角上限
controls.minAzimuthAngle = -Math.PI/2; // 水平旋转下限
controls.maxAzimuthAngle = Math.PI/2; // 水平旋转上限
3、 自定义按键配置
修改左键平移，右键旋转
controls.mouseButtons = {
LEFT:THREE.MOUSE.PAN,//平移
MIDDLE: THREE.MOUSE.DOLLY,
RIGHT: THREE.MOUSE.ROTATE//旋转
};
4、 禁用某个按钮的操作
把对应按键配置设置为null
// 禁用鼠标滚轮的操作
controls.mouseButtons.MIDDLE = null;
五、OrbitControls 方法
| 方法名称 | 说明 |
|---|---|
| update | 该方法用于更新控件的状态，通常在每一帧渲染时调用。如果启用了阻尼效果，必须在每一帧调用此方法，以确保阻尼效果正常工作 |
| reset | 将相机的位置和角度重置为初始状态 |
| saveState | 保存当前相机的位置、角度和目标点等状态 |
| restoreState | 恢复之前保存的相机状态 |
六、OrbitControls 事件监听
| 事件名称 | 说明 | 使用场景 |
|---|---|---|
| change | 当相机的位置、角度或者目标点发生变化时，就会触发 change 事件 | 可用于实时更新与相机状态相关的 UI 元素，或者在相机视角改变时执行一些特定操作。 |
| start | 当用户开始与控件进行交互（如按下鼠标按钮开始旋转、平移或缩放）时，会触发 start 事件。 | 可以在用户开始操作相机时，播放一些提示音或者显示操作提示信息。 |
| end | 当用户结束与控件的交互（如松开鼠标按钮）时，会触发 end 事件。 | 可用于在用户操作结束后，进行一些资源清理或者数据保存的操作 |
// 变化事件监听
controls.addEventListener('change', () => {
console.log('Camera position:', camera.position);
console.log('Camera rotation:', camera.rotation);
});
// 特定事件处理
controls.addEventListener('start', () => {
console.log('交互开始');
});
controls.addEventListener('end', () => {
console.log('交互结束');
});
五、总结
OrbitControls 作为 Three.js 生态中的重要控件，极大地简化了开发者在处理 3D 场景交互时的复杂度。它就像是一把钥匙，为用户打开了自由探索 3D 世界的大门，让用户能够以直观的方式与场景进行互动，从不同的角度、距离去观察和体验 3D 模型和场景。无论是在产品展示、建筑可视化还是游戏开发等领域，OrbitControls 都能发挥出巨大的作用，为项目增添独特的魅力。
更多three.js入门知识点请关注该系列教程后续的更新。