Web 图形与 3D / 系统课时
OrbitControls 如何限制视角
OrbitControls 如何限制视角
产品展示页如果允许相机任意翻转、无限缩放或随意平移,用户很容易看不到产品主体。本课使用 Three.js 的 OrbitControls 固定观察中心,限制水平与垂直旋转角度、镜头距离和平移权限,并加入阻尼效果,完成一个可直接运行的受限三维浏览场景。
学习目标
- 理解 OrbitControls 的观察目标、极角、方位角与距离限制。
- 配置适合产品展示的旋转范围、缩放边界、平移权限和阻尼参数。
- 运行完整示例,通过鼠标操作和控制台数据验证视角约束。
视角限制如何工作
OrbitControls 通过调整相机位置,让相机围绕 controls.target 指定的观察点运动。用户拖拽时,相机会改变方位角和极角;滚动鼠标滚轮时,透视相机会靠近或远离观察点。
理解以下三个量,才能正确设置限制:
- 极角(Polar Angle):相机方向与世界坐标正 Y 轴之间的夹角。0° 表示位于观察点正上方,90° 表示与观察点等高,180° 表示正下方。
- 方位角(Azimuth Angle):相机围绕 Y 轴的水平旋转角度。默认以正 Z 方向为 0°,向正 X 方向旋转为正角度。
- 距离(Distance):相机到
target的空间距离,使用场景世界单位,并非镜头到模型表面的距离。
对于一个宽约 1.6、高 2、深 1.2 个世界单位的桌面产品,可以采用下面的限制:
| 控制属性 | 设置值 | 作用 |
|---|---|---|
target |
(0, 1, 0) |
围绕产品几何中心观察 |
minPolarAngle |
25° | 避免过度俯视 |
maxPolarAngle |
85° | 不允许相机转到产品下方 |
minAzimuthAngle |
-70° | 限制向一侧旋转 |
maxAzimuthAngle |
70° | 限制向另一侧旋转 |
minDistance |
3 | 防止镜头过度贴近 |
maxDistance |
9 | 防止产品缩得过小 |
enablePan |
false |
禁止用户平移观察中心 |
enableDamping |
true |
松开鼠标后平滑减速 |
dampingFactor |
0.08 |
控制阻尼衰减速度 |
角度限制的 API 使用弧度,因此代码中需要通过 THREE.MathUtils.degToRad() 转换。极角限制必须位于 0 到 π 之间;方位角区间需要满足控制器的有效范围要求,本例采用对称的 -70° 到 70°。

在项目中接入 OrbitControls
下面使用 Vite 和 Three.js 创建一个最小产品展示场景。适用于支持 three/addons/controls/OrbitControls.js 导入路径的现代 Three.js npm 版本。
先在终端创建原生 JavaScript 项目并安装依赖:
npm create vite@latest orbit-limits-demo -- --template vanilla
cd orbit-limits-demo
npm install
npm install three预期结果:创建 orbit-limits-demo 项目目录,生成 package.json 并安装 Three.js。npm 可能询问是否安装项目初始化工具,按提示确认即可;具体安装日志随环境和版本变化。
将 src/main.js 替换为以下完整代码:
import * as THREE from 'three';
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
const scene = new THREE.Scene();
scene.background = new THREE.Color(0xf5f7f9);
const camera = new THREE.PerspectiveCamera(
45,
window.innerWidth / window.innerHeight,
0.1,
100
);
camera.position.set(4, 3, 6);
const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
renderer.setSize(window.innerWidth, window.innerHeight);
document.body.style.margin = '0';
document.body.appendChild(renderer.domElement);
// 用长方体模拟一件放在地面上的展示产品。
const product = new THREE.Mesh(
new THREE.BoxGeometry(1.6, 2, 1.2),
new THREE.MeshStandardMaterial({
color: 0x27a99b,
roughness: 0.42,
metalness: 0.25
})
);
product.position.y = 1;
scene.add(product);
const floor = new THREE.Mesh(
new THREE.PlaneGeometry(20, 20),
new THREE.MeshStandardMaterial({ color: 0xe7ebef })
);
floor.rotation.x = -Math.PI / 2;
scene.add(floor);
scene.add(new THREE.HemisphereLight(0xffffff, 0x9fb0bd, 2));
const light = new THREE.DirectionalLight(0xffffff, 2);
light.position.set(4, 8, 5);
scene.add(light);
const controls = new OrbitControls(camera, renderer.domElement);
// 固定观察中心,并把角度限制转换为弧度。
controls.target.set(0, 1, 0);
controls.minPolarAngle = THREE.MathUtils.degToRad(25);
controls.maxPolarAngle = THREE.MathUtils.degToRad(85);
controls.minAzimuthAngle = THREE.MathUtils.degToRad(-70);
controls.maxAzimuthAngle = THREE.MathUtils.degToRad(70);
// 限制透视相机距离,禁止平移并保留旋转与缩放。
controls.minDistance = 3;
controls.maxDistance = 9;
controls.enablePan = false;
controls.enableDamping = true;
controls.dampingFactor = 0.08;
controls.update();
// 交互结束时记录角度和距离,便于检查约束。
controls.addEventListener('end', () => {
console.log({
polar: THREE.MathUtils.radToDeg(controls.getPolarAngle()).toFixed(1),
azimuth: THREE.MathUtils.radToDeg(controls.getAzimuthalAngle()).toFixed(1),
distance: controls.getDistance().toFixed(2)
});
});
window.addEventListener('resize', () => {
camera.aspect = window.innerWidth / window.innerHeight;
camera.updateProjectionMatrix();
renderer.setSize(window.innerWidth, window.innerHeight);
});
// 开启阻尼后,每帧都需要更新控制器。
renderer.setAnimationLoop(() => {
controls.update();
renderer.render(scene, camera);
});预期结果:在浏览器中能够看到青绿色长方体产品及浅灰色地面。鼠标左键拖拽可以旋转,滚轮可以缩放,右键拖拽无法平移场景。每次交互结束,开发者工具 Console 会输出包含 polar、azimuth、distance 三个字段的对象,具体数值由当前操作决定。
执行 npm run dev 启动项目,并访问终端显示的本地地址。服务端口可能不同,记为 <PORT>,不要假设所有环境都使用同一端口。
验证旋转、缩放与阻尼
打开浏览器开发者工具 Console,分别进行以下检查:
- 水平角度:按住鼠标左键持续向左右拖拽。镜头到达两侧边界后不应继续绕到产品背面。交互结束后,Console 中的
azimuth应在 -70 到 70 之间。 - 垂直角度:上下拖动鼠标。相机不能移动到产品正上方或地面下方,
polar应保持在 25 到 85 之间。 - 距离限制:反复滚动滚轮,直到画面不再明显放大或缩小。
distance应保持在 3 到 9 之间,允许显示精度产生的微小舍入差异。 - 禁止平移:按住鼠标右键拖动。观察目标仍应固定在产品中心;触控设备上也应检查双指操作不能将目标移走。
- 阻尼效果:拖动后松开左键,观察镜头是否逐渐停止。将
dampingFactor从0.08调到0.2,再次测试,通常会感觉旋转更快停下。
阻尼系数越大,每次更新时衰减越明显;较小的系数通常会保留更长的滑动尾迹。产品精细检查适合较快停下,展厅漫游则可以使用更柔和的阻尼。
如果项目还提供切换产品的按钮,切换产品后应同步更新 controls.target 到新产品的中心。对于已加载的模型,可通过 THREE.Box3().setFromObject(model).getCenter(center) 计算其世界空间包围盒中心,避免相机继续围绕旧产品旋转。
常见视角异常与修正
拖动后视角立刻停住,没有惯性。 检查 enableDamping 是否为 true,以及渲染循环里是否调用 controls.update()。只在初始化阶段调用一次 update(),无法持续处理阻尼衰减。
镜头围绕产品底部旋转。 通常是 target 仍停留在世界原点,而模型中心位于 (0, 1, 0)。应该调整观察目标,而不是不断调用 camera.lookAt() 与控制器争夺相机朝向。
缩放限制没有达到预期。 minDistance 和 maxDistance 限制的是透视相机到目标点的距离,不保证模型永不被裁切。模型尺寸、视场角和相机裁剪面仍需分别检查。如果改用 OrthographicCamera,通常应改用 minZoom、maxZoom 约束缩放。
镜头到达边界后仍然无法看到模型某一侧。 先确认水平范围是否过窄,再检查模型默认朝向。对于需要完整 360° 展示的商品,可以不设置方位角上下限,仅保留极角、距离和禁止平移约束。
禁用了平移但相机仍能穿过其他模型。 OrbitControls 的角度和距离限制不是碰撞检测。复杂展厅需要额外使用射线检测或场景碰撞约束;不能把 minDistance 当作所有障碍物的防穿透机制。
产品单体展示通常可以从本课的 25°~85° 极角、±70° 方位角、3~9 单位距离和 enablePan=false 开始,再根据模型尺寸、默认朝向及实际交互测试调整。属性定义与不同版本支持情况可查阅 OrbitControls 官方文档。