@taole/giftstage 0.1.13 → 0.1.15

package/README.md

@@ -161,9 +161,35 @@ await stage.addGift({
 插入一个礼物，返回：
 
 ```ts
-Promise<GiftHandle>
+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 移除礼物。
@@ -196,20 +222,15 @@ Promise<GiftHandle>
 - `width?: number`
 - `height?: number`
 - `useOriginalSize?: boolean`
-- `objectFit?: 'contain' | 'fill'`
+- `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` 三种礼物间通用
@@ -223,7 +244,8 @@ Promise<GiftHandle>
 - 两个都传：按传入值显示
 - 只传 `width`：`height` 按礼物原始宽高比自动补全
 - 只传 `height`：`width` 按礼物原始宽高比自动补全
-- 两个都不传：按当前画布尺寸做等比 `contain`
+- 两个都不传：默认按当前画布尺寸做等比 `contain`
+- 如果 `objectFit: 'cover'` 且两个都不传：按整个画布作为显示区域做等比 `cover`
 - 也就是会在画布内尽可能放大或缩小，并保持礼物原始宽高比
 - 如果 `useOriginalSize: true`，且礼物原始尺寸本身小于画布，则优先使用礼物原始尺寸
 - 如果 `useOriginalSize: true`，但礼物原始尺寸超出画布，则仍会按画布尺寸等比缩小
@@ -242,6 +264,21 @@ await stage.addGift({
 
 这时会按舞台尺寸做等比适配，并保持礼物原始宽高比。
 
+如果希望礼物铺满整个画布，并按中心裁剪超出的部分，可以使用 `cover`：
+
+```ts
+await stage.addGift({
+  type: 'svga',
+  source: 'https://example.com/demo.svga',
+  x: '50%',
+  y: '50%',
+  objectFit: 'cover',
+  loop: 0,
+});
+```
+
+当 `x: '50%'`、`y: '50%'` 且未传 `width / height` 时，显示区域会居中放在整个画布上；`cover` 会保持礼物原始宽高比铺满该区域，并从中心裁剪溢出的部分。
+
 如果你希望“小礼物保持原始尺寸，大礼物再缩小”，可以这样：
 
 ```ts
@@ -331,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
@@ -448,7 +533,7 @@ await stage.addGift({
 
 入口文件：
 
-- [src/index.ts](</D:/MyDocuments/UnityProjects/SVGAPlayer-Unity/gift-stage/src/index.ts>)
+- [src/index.ts](/D:/MyDocuments/UnityProjects/SVGAPlayer-Unity/gift-stage/src/index.ts)
 
 主要导出：
 
@@ -466,7 +551,7 @@ await stage.addGift({
 
 Demo 入口：
 
-- [index.html](</D:/MyDocuments/UnityProjects/SVGAPlayer-Unity/gift-stage/index.html>)
+- [index.html](/D:/MyDocuments/UnityProjects/SVGAPlayer-Unity/gift-stage/index.html)
 
 可用于验证：
 
@@ -478,4 +563,4 @@ Demo 入口：
 ## 相关文档
 
 - 优化汇总：
-  [docs/giftstage-optimization-summary.md](</D:/MyDocuments/UnityProjects/SVGAPlayer-Unity/gift-stage/docs/giftstage-optimization-summary.md>)
+  [docs/giftstage-optimization-summary.md](/D:/MyDocuments/UnityProjects/SVGAPlayer-Unity/gift-stage/docs/giftstage-optimization-summary.md)