[page:EventDispatcher] →

# 轨迹球控制器（[name]）

[name] 与 [page:OrbitControls] 相类似。然而，它不能恒定保持摄像机的[page:Object3D.up up]向量。 这意味着，如果摄像机绕过“北极”和“南极”，则不会翻转以保持“右侧朝上”。

## 进口

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

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

## 例子

[example:misc_controls_trackball misc / controls / trackball ]

## 构造函数

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

[page:Camera camera]: 渲染场景的摄像机。

[page:HTMLDOMElement domElement]: 用于事件监听的HTML元素。

创建一个新的 [name] 实例。

## 事件

### change

当摄像机被控制器变换后触发。

### start

当交互（例如触摸）被初始化后触发。

### end

当交互完成后触发。

## 属性

### [property:HTMLDOMElement domElement]

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

### [property:Number dynamicDampingFactor]

设置阻尼的强度。仅在[page:.staticMoving staticMoving]设为*false*时考虑。默认为*0.2*。

### [property:Boolean enabled]

是否启用控制器。

### [property:Array keys]

该数组包含用于控制交互的按键代码。

- 当定义的第一个按键按下后，所有的鼠标交互（左/中/右键）表现为环绕。
- 当定义的第二个按键按下后，所有的鼠标交互（左/中/右键）表现为缩放。
- 当定义的第三个按键按下后，所有的鼠标交互（左/中/右键）表现为平移。

默认为*KeyA, KeyS, KeyD*，分别表示A, S, D。

### [property:Number maxDistance]

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

### [property:Number minDistance]

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

### [property:Float maxZoom]

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

### [property:Float minZoom]

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

### [property:Object mouseButtons]

该对象包含由控件所使用的鼠标操作的引用。

- .LEFT 指定给 *THREE.MOUSE.ROTATE*
- .MIDDLE 指定给 *THREE.MOUSE.ZOOM*
- .RIGHT 指定给 *THREE.MOUSE.PAN*

### [property:Boolean noPan]

是否禁用平移，默认为*false*。

### [property:Boolean noRotate]

是否禁用旋转，默认为*false*。

### [property:Boolean noZoom]

是否禁用缩放，默认为*false*。

### [property:Camera object]

正被控制的摄像机。

### [property:Number panSpeed]

平移的速度，其默认值为*0.3*。

### [property:Number rotateSpeed]

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

### [property:Object screen]

表示屏幕的属性。在[page:.handleResize handleResize]()被调用时会自动设置。

- left: 表示到屏幕左侧边界的偏移量（单位为像素）。
- top: 表示到屏幕顶部边界的偏移量（单位为像素）。
- width: 表示屏幕的宽度（单位为像素）。
- height: 表示屏幕的高度（单位为像素）。

### [property:Boolean staticMoving]

阻尼是否被禁用。默认为*false*。

### [property:Number zoomSpeed]

缩放的速度，其默认值为*1.2*。

## 方法

### [method:undefined checkDistances] ()

确保控制器位于 [minDistance, maxDistance] 范围内。由[page:.update update]()调用。

### [method:undefined dispose] ()

若不再需要该控制器，则应当调用此函数。

### [method:undefined handleResize] ()

若应用程序窗口大小发生改变，则应当调用此函数。

### [method:undefined panCamera] ()

如有必要，执行平移。由[page:.update update]()调用。

### [method:undefined reset] ()

重置控制器到初始状态。

### [method:undefined rotateCamera] ()

如有必要，旋转相机。由[page:.update update]()调用。

### [method:undefined update] ()

更新控制器，常被用在动画循环中。

### [method:undefined zoomCamera] ()

如有必要，执行缩放。由[page:.update update]()调用。

## 源代码

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