xxf_react 0.6.4 → 0.6.5

package/README.md

@@ -35,3 +35,38 @@ This project was created using `bun init` in bun v1.3.2. [Bun](https://bun.com)
 ## 详细文档
 
 - [PlaybackQueue 播放队列状态管理](./src/media/playback-queue-store.md)
+
+### VideoPlaySafe 视频安全播放
+
+处理移动端自动播放限制，自动降级为静音播放。
+
+#### 功能特性
+
+- 按当前 `video.muted` 状态尝试播放
+- 如果非静音播放失败（`NotAllowedError` / `AbortError`），自动降级为静音重试
+- 支持扩展 `HTMLVideoElement` 原型，直接调用 `video.playSafe()`
+
+#### 使用方式
+
+```typescript
+import { playSafe, extendVideoElement } from '@xxf/react/media/video-play-safe';
+
+// 方式一：直接调用函数
+await playSafe(videoElement, {
+    mutedRetry: true,           // 是否在非静音播放失败时降级为静音重试，默认 true
+    onMutedChange: () => {      // 从有声降级为静音时回调
+        console.log('已降级为静音播放');
+    }
+});
+
+// 方式二：扩展原型后调用
+extendVideoElement();
+await videoElement.playSafe({ mutedRetry: true });
+```
+
+#### API
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `mutedRetry` | `boolean` | `true` | 是否在非静音播放失败时降级为静音重试 |
+| `onMutedChange` | `() => void` | - | 从有声降级为静音时的回调函数 |

package/dist/media/video-play-safe.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Video 安全播放扩展
+ * 处理移动端自动播放限制，自动降级为静音播放
+ */
+export interface PlaySafeOptions {
+    /** 是否在非静音播放失败时降级为静音重试，默认 true */
+    mutedRetry?: boolean;
+    /** 从有声降级为静音时回调 */
+    onMutedChange?: () => void;
+}
+declare global {
+    interface HTMLVideoElement {
+        playSafe(options?: PlaySafeOptions): Promise<void>;
+    }
+}
+/**
+ * 安全播放视频
+ * 1. 按当前 video.muted 状态尝试播放
+ * 2. 如果非静音播放失败，降级为静音再试
+ */
+export declare function playSafe(video: HTMLVideoElement, options?: PlaySafeOptions): Promise<void>;
+/**
+ * 扩展 HTMLVideoElement 原型
+ */
+export declare function extendVideoElement(): void;
+//# sourceMappingURL=video-play-safe.d.ts.map

package/dist/media/video-play-safe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"video-play-safe.d.ts","sourceRoot":"","sources":["../../src/media/video-play-safe.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,eAAe;IAC5B,iCAAiC;IACjC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,kBAAkB;IAClB,aAAa,CAAC,EAAE,MAAM,IAAI,CAAC;CAC9B;AAGD,OAAO,CAAC,MAAM,CAAC;IACX,UAAU,gBAAgB;QACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;KACtD;CACJ;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAC1B,KAAK,EAAE,gBAAgB,EACvB,OAAO,GAAE,eAAoB,GAC9B,OAAO,CAAC,IAAI,CAAC,CAiCf;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAYzC"}

package/dist/media/video-play-safe.js

@@ -0,0 +1,56 @@
+/**
+ * Video 安全播放扩展
+ * 处理移动端自动播放限制，自动降级为静音播放
+ */
+/**
+ * 安全播放视频
+ * 1. 按当前 video.muted 状态尝试播放
+ * 2. 如果非静音播放失败，降级为静音再试
+ */
+export async function playSafe(video, options = {}) {
+    const { mutedRetry = true, onMutedChange } = options;
+    if (!video || !video.parentElement || !document.contains(video)) {
+        return;
+    }
+    const wasMuted = video.muted;
+    try {
+        await video.play();
+    }
+    catch (error) {
+        // 处理自动播放被阻止的错误
+        // - NotAllowedError: Chrome/Firefox 自动播放策略阻止
+        // - AbortError: Safari/iOS 自动播放策略阻止（包括低电量模式）
+        const isAutoplayBlocked = error instanceof Error &&
+            (error.name === 'NotAllowedError' || error.name === 'AbortError');
+        if (!isAutoplayBlocked) {
+            throw error;
+        }
+        // 不启用静音重试，直接抛出
+        if (!mutedRetry)
+            throw error;
+        // 已经是静音还失败，直接抛出
+        if (wasMuted)
+            throw error;
+        // 降级为静音播放
+        video.muted = true;
+        onMutedChange === null || onMutedChange === void 0 ? void 0 : onMutedChange();
+        await video.play();
+    }
+}
+/**
+ * 扩展 HTMLVideoElement 原型
+ */
+export function extendVideoElement() {
+    if (typeof HTMLVideoElement === 'undefined')
+        return;
+    if ('playSafe' in HTMLVideoElement.prototype)
+        return;
+    Object.defineProperty(HTMLVideoElement.prototype, 'playSafe', {
+        value: function (options = {}) {
+            return playSafe(this, options);
+        },
+        writable: true,
+        configurable: true,
+        enumerable: false,
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xxf_react",
-  "version": "0.6.4",
+  "version": "0.6.5",
   "private": false,
   "type": "module",
   "main": "dist/index.js",