@taole/giftstage 0.1.5 → 0.1.7

package/README.md

@@ -192,8 +192,10 @@ Promise<GiftHandle>
 - `source: string | ArrayBuffer`
 - `x: number | \`${number}%\``
 - `y: number | \`${number}%\``
+- `zIndex?: number`
 - `width?: number`
 - `height?: number`
+- `useOriginalSize?: boolean`
 - `objectFit?: 'contain' | 'fill'`
 - `loop?: number`
   - `0` 表示无限循环
@@ -208,6 +210,12 @@ Promise<GiftHandle>
 - `easing?: (t: number) => number`
 - `onFlyComplete?: (gift) => void`
 
+层级规则：
+
+- `zIndex` 在 `SVGA / VAP / AlphaVideo` 三种礼物间通用
+- 数值越大，渲染越靠上
+- 同层级下，后 `addGift()` 的礼物会覆盖先添加的礼物
+
 ### 宽高默认行为
 
 `width / height` 现在是可选参数，规则如下：
@@ -215,8 +223,10 @@ Promise<GiftHandle>
 - 两个都传：按传入值显示
 - 只传 `width`：`height` 按礼物原始宽高比自动补全
 - 只传 `height`：`width` 按礼物原始宽高比自动补全
-- 两个都不传：默认使用礼物原始宽高
-- 如果两个都不传，且礼物原始宽高大于当前画布，则会按画布尺寸等比缩小后再显示
+- 两个都不传：按当前画布尺寸做等比 `contain`
+- 也就是会在画布内尽可能放大或缩小，并保持礼物原始宽高比
+- 如果 `useOriginalSize: true`，且礼物原始尺寸本身小于画布，则优先使用礼物原始尺寸
+- 如果 `useOriginalSize: true`，但礼物原始尺寸超出画布，则仍会按画布尺寸等比缩小
 
 例如：
 
@@ -230,7 +240,20 @@ await stage.addGift({
 });
 ```
 
-这时会使用该礼物的原始尺寸；如果原始尺寸超出舞台，则自动缩放到舞台内。
+这时会按舞台尺寸做等比适配，并保持礼物原始宽高比。
+
+如果你希望“小礼物保持原始尺寸，大礼物再缩小”，可以这样：
+
+```ts
+await stage.addGift({
+  type: 'svga',
+  source: 'https://example.com/demo.svga',
+  x: '50%',
+  y: '50%',
+  useOriginalSize: true,
+  loop: 0,
+});
+```
 
 ### 百分比坐标