init: 2.B

2026-11-10 13:04:30 +08:00 · 2026-02-28 20:23:34 +08:00
commit 6bf32174d8
@@ -0,0 +1,386 @@
+# Camera API 文档
+
+本文档由 `DeepSeek R1` 模型生成并微调。
+
+---
+
+```mermaid
+graph LR
+    Camera --> EventEmitter
+
+    click EventEmitter "https://nodejs.org/api/events.html#class-eventemitter"
+```
+
+_继承自 `EventEmitter<CameraEvent>`，支持事件监听。_
+
+---
+
+## 属性说明
+
+| 属性名                | 类型                | 描述                                             |
+| --------------------- | ------------------- | ------------------------------------------------ |
+| `readonly binded`     | `RenderItem`        | 当前绑定的渲染元素                               |
+| `transform`           | `Transform`         | 目标变换矩阵，默认与 `binded.transform` 共享引用 |
+| `protected operation` | `CameraOperation[]` | 当前应用的变换操作列表（平移/旋转/缩放）         |
+
+---
+
+## 构造方法
+
+### `Camera.for`
+
+```typescript
+ function for(item: RenderItem): Camera
+```
+
+获取或创建与渲染元素关联的摄像机实例。  
+**示例：**
+
+```typescript
+const item = new RenderItem();
+const camera = Camera.for(item); // 获取或创建摄像机
+```
+
+### `constructor`
+
+```typescript
+function constructor(item: RenderItem): Camera;
+```
+
+直接创建摄像机实例（不会自动注册到全局映射）。  
+**注意：** 推荐优先使用 `Camera.for()` 方法。
+
+---
+
+## 方法说明
+
+### `disable`
+
+```typescript
+function disable(): void;
+```
+
+禁用摄像机变换效果。  
+**示例：**
+
+```typescript
+camera.disable(); // 暂停所有摄像机变换
+```
+
+### `enable`
+
+```typescript
+function enable(): void;
+```
+
+启用摄像机变换效果。
+
+### `requestUpdate`
+
+```typescript
+function requestUpdate(): void;
+```
+
+请求在下一帧强制更新变换矩阵。
+
+### `removeOperation`
+
+```typescript
+function removeOperation(operation: CameraOperation): void;
+```
+
+移除一个变换操作。
+**参数说明**
+
+-   `operation`: 要移除的操作
+
+**示例**
+
+```ts
+const operation = camera.addTranslate();
+camera.removeOperation(operation);
+```
+
+### `clearOperation`
+
+```ts
+function clearOperation(): void;
+```
+
+清空变换操作列表。
+
+### `addTranslate`
+
+```typescript
+function addTranslate(): ICameraTranslate;
+```
+
+添加平移操作并返回操作对象。  
+**示例：**
+
+```typescript
+const translateOp = camera.addTranslate();
+translateOp.x = 100; // 设置横向偏移
+camera.requestUpdate();
+```
+
+### `addRotate`
+
+```typescript
+function addRotate(): ICameraRotate;
+```
+
+添加旋转操作并返回操作对象。  
+**示例：**
+
+```typescript
+const rotateOp = camera.addRotate();
+rotateOp.angle = Math.PI / 2; // 设置90度旋转
+camera.requestUpdate();
+```
+
+### `addScale`
+
+```typescript
+function addScale(): ICameraScale;
+```
+
+添加缩放操作并返回操作对象。  
+**示例：**
+
+```typescript
+const scaleOp = camera.addScale();
+scaleOp.x = 2; // 横向放大2倍
+camera.requestUpdate();
+```
+
+### `applyAnimation`
+
+```ts
+function applyAnimation(time: number, update: () => void): void;
+```
+
+施加动画。
+
+**参数说明**
+
+-   `time`: 动画时长。
+-   `update`: 每帧执行的更新函数。
+
+### `applyTranslateAnimation`
+
+```typescript
+function applyTranslateAnimation(
+    operation: ICameraTranslate,
+    animate: Animation,
+    time: number
+): void;
+```
+
+为平移操作绑定动画。  
+**参数说明：**
+
+-   `animate`: 预定义的动画实例
+-   `time`: 动画持续时间（毫秒）
+
+### `applyRotateAnimation`
+
+```typescript
+function applyRotateAnimation(
+    operation: ICameraRotate,
+    animate: Animation,
+    time: number
+): void;
+```
+
+为旋转操作绑定动画。
+
+### `applyScaleAnimation`
+
+```typescript
+function applyScaleAnimation(
+    operation: ICameraScale,
+    animate: Animation,
+    time: number
+): void;
+```
+
+为缩放操作绑定动画。
+
+### `applyTranslateTransition`
+
+```typescript
+function applyTranslateTransition(
+    operation: ICameraTranslate,
+    animate: Transition,
+    time: number
+): void;
+```
+
+为平移操作绑定渐变。  
+**参数说明：**
+
+-   `animate`: 预定义的渐变实例
+-   `time`: 渐变持续时间（毫秒）
+
+### `applyRotateTransition`
+
+```typescript
+function applyRotateTransition(
+    operation: ICameraRotate,
+    animate: Transition,
+    time: number
+): void;
+```
+
+为旋转操作绑定渐变。
+
+### `applyScaleTransition`
+
+```typescript
+function applyScaleTransition(
+    operation: ICameraScale,
+    animate: Transition,
+    time: number
+): void;
+```
+
+为缩放操作绑定渐变。
+
+### `stopAllAnimates`
+
+```ts
+function stopAllAnimates(): void;
+```
+
+停止所有动画。
+
+### `destroy`
+
+```typescript
+function destroy(): void;
+```
+
+销毁摄像机并释放所有资源。  
+**示例：**
+
+```typescript
+camera.destroy(); // 解除绑定并清理动画
+```
+
+---
+
+## 事件说明
+
+| 事件名    | 参数 | 描述               |
+| --------- | ---- | ------------------ |
+| `destroy` | 无   | 摄像机被销毁时触发 |
+
+---
+
+## 总使用示例
+
+::: code-group
+
+```typescript [动画]
+import { Animation, linear } from 'mutate-animate';
+
+// 获取摄像机实例
+const item = new Sprite();
+const camera = Camera.for(item);
+
+// 添加平移和缩放操作
+const translate = camera.addTranslate();
+const scale = camera.addScale();
+
+// 创建动画实例
+const anim = new Animation()
+    .mode(linear())
+    .time(1000)
+    .move(100, 100)
+    .time(800)
+    .scale(1.5);
+
+// 绑定动画
+camera.applyTranslateAnimation(translate, anim, 1000);
+camera.applyScaleAnimation(scale, anim, 800);
+
+// 启用摄像机
+camera.enable();
+
+// 销毁（当不再需要时）
+setTimeout(() => camera.destroy(), 2000);
+```
+
+```typescript [渐变]
+import { Transition, hyper } from 'mutate-animate';
+// 获取摄像机实例
+const item = new Sprite();
+const camera = Camera.for(item);
+
+// 添加平移和缩放操作
+const translate = camera.addTranslate();
+const scale = camera.addScale();
+
+// 创建渐变实例，使用双曲正弦速率曲线
+const tran = new Transition().mode(hyper('sin', 'out')).time(1000);
+
+// 初始化参数，这一步不会执行渐变
+tran.value.x = 0;
+tran.value.y = 0;
+tran.value.size = 0;
+
+// 对参数执行渐变，直接设置即可
+tran.value.x = 100;
+tran.value.y = 200;
+tran.time(800); // 设置渐变时长为 800 毫秒
+tran.value.size = 1.5;
+
+// 绑定动画
+camera.applyTranslateTransition(translate, tran, 1000);
+camera.applyScaleTransition(scale, tran, 800);
+
+// 启用摄像机
+camera.enable();
+
+// 销毁（当不再需要时）
+setTimeout(() => camera.destroy(), 2000);
+```
+
+:::
+
+---
+
+## 接口说明
+
+### `ICameraTranslate`
+
+```typescript
+interface ICameraTranslate {
+    readonly type: 'translate';
+    readonly from: RenderItem;
+    x: number; // 横向偏移量
+    y: number; // 纵向偏移量
+}
+```
+
+### `ICameraRotate`
+
+```typescript
+interface ICameraRotate {
+    readonly type: 'rotate';
+    readonly from: RenderItem;
+    angle: number; // 旋转弧度值
+}
+```
+
+### `ICameraScale`
+
+```typescript
+interface ICameraScale {
+    readonly type: 'scale';
+    readonly from: RenderItem;
+    x: number; // 横向缩放比
+    y: number; // 纵向缩放比
+}
+```