@taole/giftstage 0.1.14 → 0.1.15

package/README.md

@@ -164,6 +164,32 @@ await stage.addGift({
 Promise<GiftHandle>;
 ```
 
+### `GiftHandle` API
+
+`addGift()` 返回的句柄可用于控制单个礼物：
+
+- `gift.id`
+- `gift.type`
+- `gift.pause()`
+- `gift.resume()`
+- `gift.destroy()`
+  - 立即移除当前礼物
+- `gift.animate(stepOrSteps?)`
+  - 创建链式动画并返回 `GiftAnimationChain`
+
+`GiftAnimationChain` 支持：
+
+- `.to(step)` / `.then(step)`
+  - 追加动画步骤（两者等价）
+- `.onComplete((gift) => void)`
+  - 整条链执行完成后的回调
+- `.start(mode?)`
+  - `mode: 'immediate' | 'afterGiftComplete'`
+  - `immediate`：立即开始（默认）
+  - `afterGiftComplete`：等待礼物主播放结束后再执行链
+- `.cancel()`
+  - 取消当前礼物正在执行的链式动画
+
 ### `stage.removeGift(id)`
 
 按 ID 移除礼物。
@@ -199,17 +225,12 @@ Promise<GiftHandle>;
 - `objectFit?: 'contain' | 'cover' | 'fill'`
 - `loop?: number`
   - `0` 表示无限循环
+- `clearsAfterStop?: boolean`
+  - 播放结束后，是否自动移除礼物
+  - 默认 `true`，传 `false` 时会停留最后一帧，方便后续继续调用 `gift.animate(...).start()`
 - `mute?: boolean`
 - `onComplete?: (gift) => void`
 
-飞行动画相关：
-
-- `flyTo?: { x: number; y: number }`
-- `scaleTo?: number`
-- `flyDuration?: number`
-- `easing?: (t: number) => number`
-- `onFlyComplete?: (gift) => void`
-
 层级规则：
 
 - `zIndex` 在 `SVGA / VAP / AlphaVideo` 三种礼物间通用
@@ -347,6 +368,54 @@ await stage.addGift({
 });
 ```
 
+## 动画控制
+
+### 链式动画
+
+`addGift()` 返回的 `GiftHandle` 支持 `animate()`。一次 `to()` 是组合动画，同一步里可以同时移动和缩放；多个 `to()` / `then()` 会按顺序播放：
+
+```ts
+const gift = await stage.addGift({
+  type: 'svga',
+  source: 'https://example.com/demo.svga',
+  x: '50%',
+  y: '50%',
+  width: 300,
+  height: 300,
+  loop: 0,
+});
+
+await gift
+  .animate()
+  .to({
+    flyTo: { x: 200, y: 240 },
+    scaleTo: 0.8,
+    duration: 500,
+  })
+  .then({
+    flyTo: { x: 600, y: 320 },
+    scaleTo: 1.1,
+    duration: 700,
+  })
+  .onComplete((g) => {
+    console.log('chain complete', g.id);
+  })
+  .start();
+```
+
+也可以传入单步或数组：
+
+```ts
+gift.animate({ flyTo: { x: 300, y: 300 }, scaleTo: 0.5 }).start();
+
+gift
+  .animate([
+    { flyTo: { x: 300, y: 300 }, duration: 400 },
+    { scaleTo: 1, duration: 300 },
+  ])
+  .start();
+```
+
 ## Slot 替换
 
 ### SVGA