Threejs OrbitControls API

构造函数

OrbitControls( object : Camera, domElement : HTMLDOMElement )

• 参数:

• object: （必填）被控制的相机（必须是场景的直接子级）。

• domElement: 用于绑定事件的 HTML 元素（可选）。

事件（Events）
• change: 当相机位置/角度变化时触发。

• start: 交互开始时触发（如鼠标按下）。

• end: 交互结束时触发（如鼠标松开）。

核心属性（Properties）

属性	类型	描述
.autoRotate	`Boolean`	是否自动绕目标旋转（默认 `false`）。需在动画循环中调用 `.update()`。
.autoRotateSpeed	`Float`	自动旋转速度（默认 `2.0`，60fps 下约 30 秒/圈）。
.enableDamping	`Boolean`	是否启用阻尼惯性效果（默认 `false`）。启用后需在动画循环中调用 `.update()`。
.dampingFactor	`Float`	阻尼系数（默认 `0.05`）。
.enablePan	`Boolean`	是否允许平移相机（默认 `true`）。
.enableRotate	`Boolean`	是否允许旋转相机（默认 `true`）。
.enableZoom	`Boolean`	是否允许缩放（推拉）相机（默认 `true`）。
.screenSpacePanning	`Boolean`	平移时是否基于屏幕空间（默认 `true`）。若为 `false`，平移方向将与相机上方向正交。
.target	`Vector3`	控制焦点（相机围绕此点旋转）。
.cursor	`Vector3`	`.minTargetRadius` 和 `.maxTargetRadius` 的限制中心点。

限制范围（Limits）

属性	类型	描述
.minDistance / .maxDistance	`Float`	相机与焦点的最小/最大距离（透视相机 `PerspectiveCamera` 专用）。
.minZoom / .maxZoom	`Float`	最小/最大缩放值（正交相机 `OrthographicCamera` 专用）。
.minAzimuthAngle / .maxAzimuthAngle	`Float`	水平旋转角度（弧度）的上下限。
.minPolarAngle / .maxPolarAngle	`Float`	垂直旋转角度（弧度）的上下限（默认垂直范围 `0` 到 `π`）。

交互速度（Speed）

属性	类型	描述
.panSpeed	`Float`	平移速度（默认 `1`）。
.rotateSpeed	`Float`	旋转速度（默认 `1`）。
.zoomSpeed	`Float`	缩放速度（默认 `1`）。
.keyPanSpeed	`Float`	键盘平移速度（默认 `7.0`）。
.keyRotateSpeed	`Float`	键盘旋转速度（默认 `1`）。

按键绑定（Key Mappings）

// 默认键盘按键
.controls.keys = {
  LEFT: 'ArrowLeft',   // 左箭头
  UP: 'ArrowUp',       // 上箭头
  RIGHT: 'ArrowRight', // 右箭头
  BOTTOM: 'ArrowDown'  // 下箭头
}

// 默认鼠标按键
.controls.mouseButtons = {
  LEFT: THREE.MOUSE.ROTATE,   // 左键旋转
  MIDDLE: THREE.MOUSE.DOLLY,  // 中键推拉
  RIGHT: THREE.MOUSE.PAN      // 右键平移
}

// 默认触摸手势
.controls.touches = {
  ONE: THREE.TOUCH.ROTATE,     // 单指旋转
  TWO: THREE.TOUCH.DOLLY_PAN   // 双指推拉/平移
}

方法（Methods）

方法	描述
.update( deltaTime : Number )	更新控制器。启用 `autoRotate` 或 `enableDamping` 时，必须在动画循环中调用此方法。`deltaTime` 参数（秒）用于帧率无关的自动旋转。
.reset()	将控制器状态重置为上一次调用 `.saveState()` 或初始状态。
.saveState()	保存当前控制器状态（供 `.reset()` 恢复）。
.getAzimuthalAngle()	获取当前水平旋转角度（弧度）。
.getPolarAngle()	获取当前垂直旋转角度（弧度）。
.getDistance()	获取相机与目标点的距离。
.listenToKeyEvents( domElement )	为指定 DOM 元素绑定键盘事件监听（通常传入 `window`）。

代码示例

// 初始化控制器
const controls = new OrbitControls( camera, renderer.domElement );
controls.enableDamping = true;
controls.dampingFactor = 0.05;

// 动画循环
function animate() {
  requestAnimationFrame( animate );
  controls.update(); // 启用阻尼或自动旋转时必须调用
  renderer.render( scene, camera );
}

注意事项

若修改相机位置（如 camera.position.set(...)），需手动调用 controls.update()。
正交相机（OrthographicCamera）的缩放通过 .minZoom 和 .maxZoom 控制。
阻尼（Damping）功能会带来平滑的惯性效果，但会消耗额外性能。

弧度与角度的转换

// ============
// 弧度转角度
// ============
const convertRadToDeg = (rad:any) => {
    return rad * (180 / Math.PI);
}

// ============
// 角度转弧度
// ============
const convertDegToRad = (deg:any) => {
    return deg * (Math.PI / 180);
}