首页 / three.js / API 文档

OrbitControls

先看结论

轨道控制器。围绕一个目标点旋转、平移、缩放相机，是最常用的三维场景交互方式。它来自附加模块，不在核心包里。

最后验证 2026-11-03 · three.js 0.160.0 · 更新 2026-10-29 · 引用本文

import { OrbitControls } from 'three/addons/controls/OrbitControls.js'

构造参数

参数	说明
`object`	被控制的相机，通常是 `PerspectiveCamera`
`domElement`	接收事件的 DOM 元素，一般是 `renderer.domElement`

常用属性

属性	默认	说明
`enabled`	true	总开关
`target`	(0, 0, 0)	围绕的目标点，旋转与缩放都以它为中心
`minDistance` / `maxDistance`	0 / Infinity	相机到目标的距离上限与下限
`minZoom` / `maxZoom`	0 / Infinity	正交相机下的缩放范围
`minPolarAngle` / `maxPolarAngle`	0 / π	俯仰角范围，限制为 π/2 可禁止钻到地下
`minAzimuthAngle` / `maxAzimuthAngle`	-∞ / ∞	水平旋转范围
`enableDamping`	false	开启惯性阻尼，松手后缓慢停止
`dampingFactor`	0.05	阻尼系数，越小越顺滑
`enableZoom`	true	是否允许滚轮与双指缩放
`zoomSpeed`	1	缩放速度
`enableRotate`	true	是否允许旋转
`rotateSpeed`	1	旋转速度
`enablePan`	true	是否允许平移
`panSpeed`	1	平移速度
`screenSpacePanning`	true	按屏幕平面平移，false 时沿地面平移
`autoRotate`	false	自动绕目标旋转
`autoRotateSpeed`	2	自动旋转速度

方法

方法	说明
`update()`	按当前输入更新相机位置，每帧调用
`saveState()`	记录当前相机状态
`reset()`	回到 `saveState` 记录的状态
`getPolarAngle()`	当前俯仰角，弧度
`getAzimuthalAngle()`	当前水平角，弧度
`dispose()`	移除事件监听，释放资源

示例

const controls = new OrbitControls(camera, renderer.domElement);

controls.target.set(80, 12, -20);
controls.enableDamping = true;
controls.dampingFactor = 0.08;
controls.minDistance = 20;
controls.maxDistance = 600;
controls.maxPolarAngle = Math.PI * 0.495;   // 禁止钻到地面以下
controls.screenSpacePanning = false;        // 沿地面平移，符合地图操作习惯

controls.update();

renderer.setAnimationLoop(function () {
  controls.update();                        // 阻尼需要每帧调用
  renderer.render(scene, camera);
});

阻尼必须每帧 update

enableDamping: true 之后，松手时的速度会在 update() 中逐帧衰减。不在渲染循环里调用 update()，画面会停在松手瞬间，看起来像卡住。关闭阻尼时可以只在相机参数变化后调用，但统一每帧调用更省心。

与地图习惯的差异

默认的 screenSpacePanning: true 让平移跟随屏幕平面，适合查看单个物体。做城市或地形浏览时，改成 false 让平移贴着地面进行，拖动时地面跟随手指移动，更接近二维地图的操作感。

换相机后要重建控制器。控制器在构造时绑定相机与 DOM 元素，切换相机不会自动跟随。重建前先对旧实例调用 dispose()，否则旧的事件监听会继续消耗输入。

引用本文

经纬志（2026）。《OrbitControls》。https://www.jingweizhi.com/three/api/orbit-controls.html（访问日期 2026-11-03）。