[page:EventDispatcher] →

# 弧球控制器([name])

ArcballControls 允许通过具有完全触摸支持和高级导航功能的虚拟轨迹球控制相机。
光标/手指位置和移动被映射到由小控件表示的虚拟轨迹球表面上，并映射为直观且一致的相机移动。拖动光标/手指将使相机以保守的方式围绕轨迹球中心旋转（返回起始点将使相机返回到其起始方向）。
除了支持平移、缩放和捏合手势之外， ArcballControls 还通过双击/点击提供 聚焦 功能，以便直观地将对象的兴趣点移动到虚拟轨迹球的中心。焦点可以在复杂的环境中更好地检查和导航。此外， ArcballControls 允许 FOV 操作（以眩晕方式）和 z 轴旋转。还支持通过剪贴板保存和恢复相机状态（使用 ctrl+c 和 ctrl+v 快捷键复制和粘贴状态）。
不同于 [page:OrbitControls] 和 [page:TrackballControls]，[name] 不需要在动画打开时在动画循环中从外部调用 [page:.update]。
要使用此功能，与 /examples 目录中的所有文件一样，您必须将该文件单独包含在 HTML 中。

## 引入

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

`import { ArcballControls } from 'three/addons/controls/ArcballControls.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 ArcballControls( camera, renderer.domElement, scene ); controls.addEventListener( 'change', function () { renderer.render( scene, camera ); } ); //controls.update() must be called after any manual changes to the camera's transform camera.position.set( 0, 20, 100 ); controls.update();`

## 例子

[example:misc_controls_arcball misc / controls / arcball ]

## 构造函数

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

[page:Camera camera]：（必填）要控制的相机。相机不能是另一个对象的子对象，除非该对象是场景本身。
[page:HTMLDOMElement domElement]： 用于事件侦听器的 HTML 元素。
[page:Scene scene]： 相机渲染的场景。如果未给出，则小控件无法显示。

## 事件

### change

当相机被小控件改变时触发。

### start

当交互开始时触发。

### end

当交互完成时触发。

## 属性

### [property:Boolean adjustNearFar]

如果为 true，则每次执行缩放时都会调整相机的近端和远端值，尝试保持初始近端和远端值给出的相同可见部分（仅限 [page:PerspectiveCamera] ）。默认为 false。

### [property:Camera camera]

被控制的摄像机。

### [property:Boolean cursorZoom]

设置为 true 以使缩放变为光标居中。

### [property:Float dampingFactor]

设置为 [page:.enableAnimations] 为true 时使用的阻尼惯性。

### [property:HTMLDOMElement domElement]

HTMLDOMElement 用于监听鼠标/触摸事件。这必须在构造函数中传递；此处更改它不会设置新的事件侦听器。

### [property:Boolean enabled]

当设置为 时 `false`，小控件将不再响应用户交互。默认为 `true`。

### [property:Boolean enableAnimations]

设置为 true 以启用旋转（阻尼）和聚焦操作的动画。默认为 true。

### [property:Boolean enableGrid]

设置为 true 时，执行平移操作时将出现网格（仅限桌面交互）。默认为 false。

### [property:Boolean enablePan]

启用或禁用相机平移。默认为 true。

### [property:Boolean enableRotate]

启用或禁用相机旋转。默认为 true。

### [property:Boolean enableZoom]

启用或禁用相机变焦。

### [property:Float focusAnimationTime]

焦点动画的持续时间。

### [property:Float maxDistance]

最大移动距离（仅限 [page:PerspectiveCamera]）。默认为无穷大。

### [property:Float maxZoom]

最大缩放值（仅限 [page:OrthographicCamera] ）。默认为无穷大。

### [property:Float minDistance]

最小移动距离（仅限 [page:PerspectiveCamera] ）。默认值为 0。

### [property:Float minZoom]

最小缩放值（仅限 [page:OrthographicCamera] ）。默认值为 0。

### [property:Float radiusFactor]

小控件相对于屏幕宽度和高度的大小。默认值为 0.67。

### [property:Float rotateSpeed]

旋转速度。默认值为 1。

### [property:Float scaleFactor]

执行缩放操作时使用的缩放因子。

### [property:Scene scene]

相机渲染的场景。

### [property:Float wMax]

旋转动画开始时允许的最大角速度。

## 方法

### [method:undefined activateGizmos] ( [param:Boolean isActive] )

使小控件或多或少可见。

### [method:undefined copyState] ()

将当前状态复制到剪贴板（作为可读的 JSON 文本）。

### [method:undefined dispose] ()

删除所有事件侦听器，取消任何待处理的动画并清除场景中的小控件和网格。

### [method:undefined pasteState] ()

从剪贴板设置控件状态，假设剪贴板存储从 [page:.copyState] 保存的 JSON 文本。

### [method:undefined reset] ()

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

### [method:undefined saveState] ()

保存控件的当前状态。稍后可以使用 [page:.reset] 恢复。

### [method:undefined setCamera] ( [param:Camera camera] )

设置要控制的摄像机。必须调用才能设置要控制的新摄像机。

### [method:undefined setGizmosVisible] ( [param:Boolean value] )

设置小控件的可见属性。

### [method:undefined setTbRadius] ( [param:Float value] )

更新 `radiusFactor` 值，重新绘制小控件并发送 `changeEvent` 让可视化更新。

### [method:Boolean setMouseAction] ( [param:String operation], mouse, key )

通过指定要执行的操作和鼠标/按键组合来设置新的鼠标操作。如果发生冲突，则替换现有的。
操作可以指定为 'ROTATE'、'PAN'、'FOV' 或 'ZOOM'。
鼠标输入可以指定为鼠标按钮 0、1、2 或 'WHEEL'。
键盘修饰符可以指定为 'CTRL'、'SHIFT' 或 null(如果不再需要) 。

### [method:Boolean unsetMouseAction] ( mouse, key )

通过指定 鼠标/按键 组合来删除鼠标操作。
鼠标输入可以指定为鼠标按钮 0、1、2 或 'WHEEL'。
键盘修饰符可以指定为 'CTRL'、'SHIFT' 或 null(如果不再需要) 。

### [method:undefined update] ()

更新控件。必须在对相机变换进行任何手动更改后调用。

### [method:Raycaster getRaycaster] ()

返回用于用户交互的 [page:Raycaster] 对象。如果设置了 [name] 的 [page:Object3D.layers .layers] 属性，您还需要使用匹配的值设置 [page:Raycaster.layers .layers] 的 [page:Raycaster] 属性，否则 [name] 将无法按预期工作。 won't work as expected.

## 源代码

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