object-controls

对场景中的 3D 对象进行交互式移动、旋转、缩放操作。继承自 Three.js TransformControls，集成了 u-space Viewer 生命周期管理。

typescript

import { ObjectControls } from 'u-space/plugins/object-controls';

const controls = new ObjectControls(viewer, {
  mode: 'translate', // 'translate' | 'rotate' | 'scale'，默认 'translate'
  space: 'world',    // 'world' | 'local'，默认 'world'
  size: 1,           // 控件显示大小，默认 1
});

controls.enable();
controls.attach(myMesh); // 将控件附加到目标对象

// 切换模式（直接赋值，继承自 TransformControls）
controls.mode = 'rotate';
controls.space = 'local';

// 监听变换事件
controls.addEventListener('objectChange', () => {
  console.log(myMesh.position);
});

controls.addEventListener('dragging-changed', ({ value }) => {
  console.log('拖拽中：', value); // true = 开始，false = 结束
});

说明：

enable() 时将 gizmo 加入场景并切换 frameloop 为 'always'，确保拖拽时连续渲染。
拖拽期间自动挂起 viewer.controls（CameraControls）以避免冲突；disable() 时无论如何都强制还原相机控制，防止 mid-drag 调用 disable 导致相机卡死。
监听 viewer 的 cameraChange 事件，viewer.setCamera() 切换相机后 gizmo 自动同步，无需手动更新。

构造选项（ObjectControlsOptions）：

选项	类型	默认值	说明
`mode`	`'translate' \| 'rotate' \| 'scale'`	`'translate'`	初始变换模式。
`space`	`'world' \| 'local'`	`'world'`	初始变换空间。
`size`	`number`	`1`	gizmo 大小。
`showX`	`boolean`	`true`	显示 X 轴手柄。
`showY`	`boolean`	`true`	显示 Y 轴手柄。
`showZ`	`boolean`	`true`	显示 Z 轴手柄。

方法：

方法	说明
`enable()`	将 gizmo 加入场景，切换 frameloop 为 `'always'`。
`disable()`	移除 gizmo，还原 frameloop 和 CameraControls。
`attach(object)`	将控件附加到指定 Object3D。
`detach()`	解除当前附加对象。
`dispose()`	完全释放所有资源。

属性：

属性	类型	说明
`isActive`	`boolean`	当前是否已调用 `enable()`（只读）。
`object`	`Object3D \| undefined`	当前附加的对象（继承自 TransformControls）。
`mode`	`string`	当前变换模式，可直接赋值切换。
`space`	`string`	当前变换空间，可直接赋值切换。

由于 ObjectControls 直接继承 TransformControls，所有原生属性（translationSnap、rotationSnap、scaleSnap、showX/Y/Z 等）和事件均可直接使用，参考 Three.js TransformControls 文档。

object-controls ​

object-controls