@taole/giftstage 0.1.14 → 0.1.16

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,14 @@ Promise<GiftHandle>;
 - `objectFit?: 'contain' | 'cover' | 'fill'`
 - `loop?: number`
   - `0` 表示无限循环
+- `opacity?: number`
+  - 全局透明度，范围 `0 ~ 1`，默认 `1`
+- `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 +370,56 @@ 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,
+    opacity: 0.6,
+    duration: 500,
+  })
+  .then({
+    flyTo: { x: 600, y: 320 },
+    scaleTo: 1.1,
+    opacity: 1,
+    duration: 700,
+  })
+  .onComplete((g) => {
+    console.log('chain complete', g.id);
+  })
+  .start();
+```
+
+也可以传入单步或数组：
+
+```ts
+gift.animate({ flyTo: { x: 300, y: 300 }, scaleTo: 0.5, opacity: 0.3 }).start();
+
+gift
+  .animate([
+    { flyTo: { x: 300, y: 300 }, duration: 400 },
+    { scaleTo: 1, opacity: 1, duration: 300 },
+  ])
+  .start();
+```
+
 ## Slot 替换
 
 ### SVGA
@@ -366,6 +439,7 @@ await stage.addGift({
     title: {
       text: 'Hello',
       color: '#ff0000',
+      fontSize: 28,
       mode: 'dynamic',
     },
   },
@@ -378,6 +452,15 @@ await stage.addGift({
 - 文本配置
 - 图片配置
 
+SVGA 文本配置会按目标 frame 自动适配字号，避免文字超出槽位：
+
+- `mode: 'dynamic'`：默认行为。生成文字自身尺寸的纹理，渲染时按自身逻辑尺寸居中到 frame 内，不会被拉伸。
+- `mode: 'replace'`：生成和 frame 一样大的纹理，按替换图逻辑铺满 frame。
+- `fontSize?: number`：期望字号；如果文字放不下，会自动缩小。
+- `minFontSize?: number` / `maxFontSize?: number`：限制自适应字号范围。
+- `padding?: number`：文字纹理内边距，默认 `2`。
+- `scale?: number`：文字纹理栅格倍率，SVGA 默认 `3`，用于保持清晰度。
+
 ### VAP / VAPX
 
 使用 `vapSlots`：