@taole/giftstage 0.1.15 → 0.1.17

package/README.md

@@ -225,6 +225,8 @@ Promise<GiftHandle>;
 - `objectFit?: 'contain' | 'cover' | 'fill'`
 - `loop?: number`
   - `0` 表示无限循环
+- `opacity?: number`
+  - 全局透明度，范围 `0 ~ 1`，默认 `1`
 - `clearsAfterStop?: boolean`
   - 播放结束后，是否自动移除礼物
   - 默认 `true`，传 `false` 时会停留最后一帧，方便后续继续调用 `gift.animate(...).start()`
@@ -372,7 +374,7 @@ await stage.addGift({
 
 ### 链式动画
 
-`addGift()` 返回的 `GiftHandle` 支持 `animate()`。一次 `to()` 是组合动画，同一步里可以同时移动和缩放；多个 `to()` / `then()` 会按顺序播放：
+`addGift()` 返回的 `GiftHandle` 支持 `animate()`。一次 `to()` 是组合动画，同一步里可以同时移动、缩放和改变透明度；多个 `to()` / `then()` 会按顺序播放：
 
 ```ts
 const gift = await stage.addGift({
@@ -390,11 +392,13 @@ await gift
   .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) => {
@@ -406,12 +410,12 @@ await gift
 也可以传入单步或数组：
 
 ```ts
-gift.animate({ flyTo: { x: 300, y: 300 }, scaleTo: 0.5 }).start();
+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, duration: 300 },
+    { scaleTo: 1, opacity: 1, duration: 300 },
   ])
   .start();
 ```
@@ -435,6 +439,7 @@ await stage.addGift({
     title: {
       text: 'Hello',
       color: '#ff0000',
+      fontSize: 28,
       mode: 'dynamic',
     },
   },
@@ -447,6 +452,43 @@ 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`，用于保持清晰度。
+- `fontStyle?: string | { font?: string; color?: string }`：字体样式，SVGA / VAP 都支持。
+
+`fontStyle` 可以直接传 canvas font 字符串：
+
+```ts
+svgaSlots: {
+  title: {
+    text: 'Hello',
+    fontStyle: 'bold 40px Arial',
+  },
+}
+```
+
+也可以传对象：
+
+```ts
+vapSlots: {
+  welcome01: {
+    text: '欢迎进入房间',
+    fontStyle: {
+      font: 'bold 40px Arial',
+      color: '#ffffff',
+    },
+  },
+}
+```
+
+对象形式目前生效字段是 `font` 和 `color`。如果同时传了外层 `color` 和 `fontStyle.color`，以 `fontStyle.color` 为准。VAP 文本如果没有传 `fontStyle`，会回退使用 VAP 配置里的 `src.fontStyle`。
+
 ### VAP / VAPX
 
 使用 `vapSlots`：