three OrbitControls 轨道控制器

OrbitControls 是 Three.js 中的一个控件，用于实现 3D 场景中的相机围绕目标物体的旋转、缩放和平移，常用于 3D 查看器和模型展示。

OrbitControls 有三个事件三十一个属性八个方法

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

    const controls = new OrbitControls(camera, renderer.domElement);
    controls.enableDamping = true; // 启用阻尼效果（惯性效果）
    controls.dampingFactor = 0.05; // 阻尼系数
    // 添加一个立方体作为示例物体
    const geometry = new THREE.BoxGeometry();
    const material = new THREE.MeshBasicMaterial({ color: 0x00ff00 });
    const cube = new THREE.Mesh(geometry, material);
    scene.add(cube);
    function animate() {
        requestAnimationFrame(animate);
        controls.update();
        renderer.render(scene, camera);
    }
    animate();

事件

• change 当摄像机被组件改变时触发。
• start 初始化交互时触发。
• end 当交互结束时触发。

    // 监听 change 事件
    controls.addEventListener('change', () => {
        console.log('OrbitControls changed');
        console.log(`Camera position: x=${camera.position.x}, y=${camera.position.y}, z=${camera.position.z}`);
        // 在此处添加其他需要执行的操作，例如重新渲染或更新 UI
        renderer.render(scene, camera);
    });

属性

• autoRotate : Boolean 将其设为true，以自动围绕目标旋转。 请注意，如果它被启用，你必须在你的动画循环里调用.update()。 如果希望自动旋转速度与帧速率（显示器的刷新率）无关，则必须将时间 deltaTime（以秒为单位）传递给 .update()。 此时只旋转相机，不做ZXY相关的位移
• utoRotateSpeed : Float 当.autoRotate为true时，围绕目标旋转的速度将有多快，默认值为2.0，相当于在60fps时每旋转一周需要30秒。 请注意，如果.autoRotate被启用，你必须在你的动画循环里调用.update()。
• dampingFactor : Float 当.enableDamping设置为true的时候，阻尼惯性有多大。 Default is 0.05. 请注意，要使得这一值生效，你必须在你的动画循环里调用.update()。使用时注意只要在相机移动时才会生效，当放大缩小时不全有阻尼
• enableDamping : Boolean 将其设置为true以启用阻尼（惯性），这将给控制器带来重量感。默认值为false。 请注意，如果该值被启用，你将必须在你的动画循环里调用.update()。
• enablePan : Boolean 启用或禁用摄像机平移，默认为true。 注意只有使用鼠标右键时才会能拖动机动，默认为右键
• enableRotate : Boolean 启用或禁用摄像机水平或垂直旋转。默认值为true。 请注意，可以通过将polar angle或者azimuth angle 的min和max设置为相同的值来禁用单个轴， 这将使得水平旋转或垂直旋转固定为所设置的值。
• enableZoom : Boolean 启用或禁用摄像机的缩放。
• keyPanSpeed : Float 当使用键盘按键的时候，相机平移的速度有多快。默认值为每次按下按键时平移7像素。
• keys : Object 这一对象包含了用于控制相机平移的按键代码的引用。默认值为4个箭头（方向）键。

    controls.keys = {
        LEFT: 'ArrowLeft', //left arrow
        UP: 'ArrowUp', // up arrow
        RIGHT: 'ArrowRight', // right arrow
        BOTTOM: 'ArrowDown' // down arrow
    }

• maxAzimuthAngle : Float 你能够水平旋转的角度上限。如果设置，其有效值范围为[-2 * Math.PI，2 * Math.PI]，且旋转角度的上限和下限差值小于2 * Math.PI。默认值为无穷大。
• maxDistance : Float 你能够将相机向外移动多少（仅适用于PerspectiveCamera），其默认值为Infinity。

    // 设置控制器的目标点 这里的目标点就是指的计算距离
    controls.target.set(0, 0, 0); // 将目标点设置为立方体的中心

• maxPolarAngle : Float 你能够垂直旋转的角度的上限，范围是0到Math.PI，其默认值为Math.PI。
• maxTargetRadius : Float 你能够让目标移动离 .cursor 有多远，其默认值为Infinity。

    // 创建 OrbitControls 实例
    const controls = new OrbitControls(camera, renderer.domElement);
    controls.enableDamping = true; // 启用阻尼
    controls.dampingFactor = 0.1;   // 设置阻尼系数
    controls.maxDistance = 20;      // 设置相机与目标点的最大距离
    controls.maxTargetRadius = 15;  // 设置相机围绕目标点的最大半径
    // 添加一个立方体作为示例物体
    const geometry = new THREE.BoxGeometry();
    const material = new THREE.MeshBasicMaterial({ color: 0x00ff00 });
    const cube = new THREE.Mesh(geometry, material);
    scene.add(cube);
    // 设置控制器的目标点
    controls.target.set(0, 0, 0); // 将目标点设置为立方体的中心
    function animate() {
        requestAnimationFrame(animate);
        controls.update(); // 更新 OrbitControls
        renderer.render(scene, camera);
    }
    animate();

• maxZoom : Float 你能够将相机缩小多少（仅适用于OrthographicCamera），其默认值为Infinity。
• minAzimuthAngle : Float 你能够水平旋转的角度下限。如果设置，其有效值范围为[-2 * Math.PI，2 * Math.PI]，且旋转角度的上限和下限差值小于2 * Math.PI。默认值为无穷大。
• minDistance : Float 你能够将相机向内移动多少（仅适用于PerspectiveCamera），其默认值为0。
• minPolarAngle : Float 你能够垂直旋转的角度的下限，范围是0到Math.PI，其默认值为0。
• minTargetRadius : Float 你能够让目标移动离 .cursor 有多近，其默认值为0。
• minZoom : Float 你能够将相机放大多少（仅适用于OrthographicCamera），其默认值为0。
• mouseButtons : Object 该对象包含由控件所使用的鼠标操作的引用。

    默认映射
        LEFT：默认值为 0，表示左键用于旋转相机。
        MIDDLE：默认值为 1，表示中键用于平移相机。
        RIGHT：默认值为 2，表示右键用于缩放相机。
    controls.mouseButtons = {
        LEFT: THREE.MOUSE.ROTATE,
        MIDDLE: THREE.MOUSE.DOLLY,
        RIGHT: THREE.MOUSE.PAN
    }

• panSpeed : Float 位移的速度，其默认值为1。
• position0 : Vector3 由.saveState和.reset方法在内部使用。
• rotateSpeed : Float 旋转的速度，其默认值为1。
• screenSpacePanning : Boolean 定义当平移的时候摄像机的位置将如何移动。如果为true，摄像机将在屏幕空间内平移。 否则，摄像机将在与摄像机向上方向垂直的平面中平移。当使用 OrbitControls 时， 默认值为true；当使用 MapControls 时，默认值为false。
• target0 : Vector3 由.saveState和.reset方法在内部使用。
• target : Vector3 控制器的焦点，.object的轨道围绕它运行。 它可以在任何时候被手动更新，以更改控制器的焦点。
• cursor : Vector3 被 .minTargetRadius 和 .maxTargetRadius 限制的焦点。可随时手动更新以更改 .target 的兴趣中心。
• touches : Object 该对象包含由控件所使用的触摸操作的引用。

    controls.touches = {
        ONE: THREE.TOUCH.ROTATE,
        TWO: THREE.TOUCH.DOLLY_PAN
    }

• zoom0 : Float 由.saveState和.reset方法在内部使用。
• zoomSpeed : Float 摄像机缩放的速度，其默认值为1。
• zoomToCursor : Boolean 将此属性设置为 true 可以缩放至光标位置。默认值为 false。

方法

• getAzimuthalAngle () : radians 获得当前的水平旋转，单位为弧度。
• getPolarAngle () : radians 获得当前的垂直旋转，单位为弧度。
• getDistance () : Float 返回从相机到目标的距离。
• listenToKeyEvents ( domElement : HTMLDOMElement ) : undefined 为指定的DOM元素添加按键监听。推荐将window作为指定的DOM元素。注意这个方法是配合 touches 或者 mouseButtons 使用

    // 开始监听键盘事件
    controls.listenToKeyEvents(window); // 监听窗口的键盘事件

• reset () : undefined 将控制器重置为上次调用.saveState时的状态，或者初始状态。
• saveState () : undefined 保存当前控制器的状态。这一状态可在之后由.reset所恢复。
• stopListenToKeyEvents () : undefined stopListenToKeyEvents() 是 OrbitControls 中的方法，用于停止监听键盘事件。调用此方法后，OrbitControls 将不再响应与相机控制相关的键盘输入。这对于在某些情况下需要禁用键盘控制的功能非常有用，例如在特定交互时或切换到其他输入模式时。
• update ( deltaTime : Number ) : Boolean 更新控制器。必须在摄像机的变换发生任何手动改变后调用，或如果.autoRotate或.enableDamping被设置时，在update循环里调用。deltaTime 以秒为单位，是可选的，并且仅当您希望自动旋转速度独立于帧速率（显示器的刷新率）时才是必需的。