# 轨道控制器（[name]）

Orbit controls（轨道控制器）可以使得相机围绕目标进行轨道运动。
要使用这一功能，就像在/examples（示例）目录中的所有文件一样， 您必须在HTML中包含这个文件。

## 进口

[name] 是一个附加组件，必须显式导入。 See [link:#manual/introduction/Installation Installation / Addons].

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

## 代码示例

`const renderer = new THREE.WebGLRenderer(); renderer.setSize( window.innerWidth, window.innerHeight ); document.body.appendChild( renderer.domElement ); const scene = new THREE.Scene(); const camera = new THREE.PerspectiveCamera( 45, window.innerWidth / window.innerHeight, 1, 10000 ); const controls = new OrbitControls( camera, renderer.domElement ); //controls.update() must be called after any manual changes to the camera's transform camera.position.set( 0, 20, 100 ); controls.update(); function animate() { requestAnimationFrame( animate ); // required if controls.enableDamping or controls.autoRotate are set to true controls.update(); renderer.render( scene, camera ); }`

## 例子

[example:misc_controls_orbit misc / controls / orbit ]

## Constructor

### [name]( [param:Camera object], [param:HTMLDOMElement domElement] )

[page:Camera object]: （必须）将要被控制的相机。该相机不允许是其他任何对象的子级，除非该对象是场景自身。
[page:HTMLDOMElement domElement]: 用于事件监听的HTML元素。

## Events

### change

当摄像机被组件改变时触发。

### start

初始化交互时触发。

### end

当交互结束时触发。

## 属性

### [property:Boolean autoRotate]

将其设为true，以自动围绕目标旋转。
请注意，如果它被启用，你必须在你的动画循环里调用[page:.update]()。 Set to true to automatically rotate around the target.
Note that if this is enabled, you must call [page:.update] () in your animation loop. If you want the auto-rotate speed to be independent of the frame rate (the refresh rate of the display), you must pass the time `deltaTime`, in seconds, to [page:.update]().

### [property:Float autoRotateSpeed]

当[page:.autoRotate]为true时，围绕目标旋转的速度将有多快，默认值为2.0，相当于在60fps时每旋转一周需要30秒。
请注意，如果[page:.autoRotate]被启用，你必须在你的动画循环里调用[page:.update]()。

### [property:Float dampingFactor]

当[page:.enableDamping]设置为`true`的时候，阻尼惯性有多大。 Default is `0.05`.
请注意，要使得这一值生效，你必须在你的动画循环里调用[page:.update]()。

### [property:HTMLDOMElement domElement]

该 HTMLDOMElement 用于监听鼠标/触摸事件，该属性必须在构造函数中传入。在此处改变它将不会设置新的事件监听。

### [property:Boolean enabled]

当设置为false时，控制器将不会响应用户的操作。默认值为true。

### [property:Boolean enableDamping]

将其设置为true以启用阻尼（惯性），这将给控制器带来重量感。默认值为false。
请注意，如果该值被启用，你将必须在你的动画循环里调用[page:.update]()。

### [property:Boolean enablePan]

启用或禁用摄像机平移，默认为true。

### [property:Boolean enableRotate]

启用或禁用摄像机水平或垂直旋转。默认值为true。
请注意，可以通过将[page:.minPolarAngle polar angle]或者[page:.minAzimuthAngle azimuth angle] 的min和max设置为相同的值来禁用单个轴， 这将使得水平旋转或垂直旋转固定为所设置的值。

### [property:Boolean enableZoom]

启用或禁用摄像机的缩放。

### [property:Float keyPanSpeed]

当使用键盘按键的时候，相机平移的速度有多快。默认值为每次按下按键时平移7像素。

### [property:Object keys]

这一对象包含了用于控制相机平移的按键代码的引用。默认值为4个箭头（方向）键。 `controls.keys = { LEFT: 'ArrowLeft', //left arrow UP: 'ArrowUp', // up arrow RIGHT: 'ArrowRight', // right arrow BOTTOM: 'ArrowDown' // down arrow }` 请参阅[link:https://developer.mozilla.org/zh-CN/docs/Web/API/KeyboardEvent/code KeyboardEvent.code]来查看所有按键的代码列表。

### [property:Float maxAzimuthAngle]

你能够水平旋转的角度上限。如果设置，其有效值范围为[-2 * Math.PI，2 * Math.PI]，且旋转角度的上限和下限差值小于2 * Math.PI。默认值为无穷大。

### [property:Float maxDistance]

你能够将相机向外移动多少（仅适用于[page:PerspectiveCamera]），其默认值为Infinity。

### [property:Float maxPolarAngle]

你能够垂直旋转的角度的上限，范围是0到Math.PI，其默认值为Math.PI。

### [property:Float maxZoom]

你能够将相机缩小多少（仅适用于[page:OrthographicCamera]），其默认值为Infinity。

### [property:Float minAzimuthAngle]

你能够水平旋转的角度下限。如果设置，其有效值范围为[-2 * Math.PI，2 * Math.PI]，且旋转角度的上限和下限差值小于2 * Math.PI。默认值为无穷大。

### [property:Float minDistance]

你能够将相机向内移动多少（仅适用于[page:PerspectiveCamera]），其默认值为0。

### [property:Float minPolarAngle]

你能够垂直旋转的角度的下限，范围是0到Math.PI，其默认值为0。

### [property:Float minZoom]

你能够将相机放大多少（仅适用于[page:OrthographicCamera]），其默认值为0。

### [property:Object mouseButtons]

该对象包含由控件所使用的鼠标操作的引用。 `controls.mouseButtons = { LEFT: THREE.MOUSE.ROTATE, MIDDLE: THREE.MOUSE.DOLLY, RIGHT: THREE.MOUSE.PAN }`

### [property:Camera object]

正被控制的摄像机。

### [property:Float panSpeed]

位移的速度，其默认值为1。

### [property:Vector3 position0]

由[page:.saveState]和[page:.reset]方法在内部使用。

### [property:Float rotateSpeed]

旋转的速度，其默认值为1。

### [property:Boolean screenSpacePanning]

定义当平移的时候摄像机的位置将如何移动。如果为true，摄像机将在屏幕空间内平移。 否则，摄像机将在与摄像机向上方向垂直的平面中平移。当使用 OrbitControls 时， 默认值为true；当使用 MapControls 时，默认值为false。

### [property:Vector3 target0]

由[page:.saveState]和[page:.reset]方法在内部使用。

### [property:Vector3 target]

控制器的焦点，[page:.object]的轨道围绕它运行。 它可以在任何时候被手动更新，以更改控制器的焦点。

### [property:Object touches]

该对象包含由控件所使用的触摸操作的引用。 `controls.touches = { ONE: THREE.TOUCH.ROTATE, TWO: THREE.TOUCH.DOLLY_PAN }`

### [property:Float zoom0]

由[page:.saveState]和[page:.reset]方法在内部使用。

### [property:Float zoomSpeed]

摄像机缩放的速度，其默认值为1。

### [property:Boolean zoomToCursor]

Setting this property to `true` allows to zoom to the cursor's position. Default is `false`.

## Methods

### [method:undefined dispose] ()

移除所有的事件监听。

### [method:radians getAzimuthalAngle] ()

获得当前的水平旋转，单位为弧度。

### [method:radians getPolarAngle] ()

获得当前的垂直旋转，单位为弧度。

### [method:Float getDistance] ()

Returns the distance from the camera to the target.

### [method:undefined listenToKeyEvents] ( [param:HTMLDOMElement domElement] )

为指定的DOM元素添加按键监听。推荐将window作为指定的DOM元素。

### [method:undefined reset] ()

将控制器重置为上次调用[page:.saveState]时的状态，或者初始状态。

### [method:undefined saveState] ()

保存当前控制器的状态。这一状态可在之后由[page:.reset]所恢复。

### [method:undefined stopListenToKeyEvents] ()

Removes the key event listener previously defined with [page:.listenToKeyEvents]().

### [method:Boolean update] ( [param:Number deltaTime] )

更新控制器。必须在摄像机的变换发生任何手动改变后调用， 或如果[page:.autoRotate]或[page:.enableDamping]被设置时，在update循环里调用。 Update the controls. Must be called after any manual changes to the camera's transform, or in the update loop if [page:.autoRotate] or [page:.enableDamping] are set. `deltaTime`, in seconds, is optional, and is only required if you want the auto-rotate speed to be independent of the frame rate (the refresh rate of the display).

## 源代码

[link:https://github.com/mrdoob/three.js/blob/master/examples/jsm/controls/OrbitControls.js examples/jsm/controls/OrbitControls.js]