# 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 文档](https://threejs.org/docs/#examples/en/controls/TransformControls)。