·

系列文章目录

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入门知识点请关注该系列教程后续的更新。