xxf_react 0.6.3 → 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/flow/{promise_ext.d.ts → PromiseExt.d.ts}

@@ -5,4 +5,4 @@ declare global {
 }
 export declare function isSafariLoadFailed(error: unknown): boolean;
 export declare function initPromiseErrorExtension(): void;
-//# sourceMappingURL=promise_ext.d.ts.map
+//# sourceMappingURL=PromiseExt.d.ts.map

package/dist/flow/PromiseExt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PromiseExt.d.ts","sourceRoot":"","sources":["../../src/flow/PromiseExt.ts"],"names":[],"mappings":"AAIA,OAAO,CAAC,MAAM,CAAC;IACX,UAAU,OAAO,CAAC,CAAC;QACf,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;KACjE;CACJ;AAGD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAM1D;AAED,wBAAgB,yBAAyB,IAAI,IAAI,CAgDhD"}

package/dist/flow/PromiseLifecycle.d.ts

@@ -0,0 +1,33 @@
+export interface PromiseLifecycle<T> {
+    /** 开始执行时（同步调用） */
+    doOnStart?: () => void;
+    /** 成功时 */
+    doOnSuccess?: (value: T) => void;
+    /** 失败时 */
+    doOnError?: (error: unknown) => void;
+    /** 无论成功失败都会调用（类似 doFinally） */
+    doFinally?: () => void;
+}
+/**
+ * 为 Promise 添加生命周期钩子
+ *
+ * @param promiseFn - 返回 Promise 的函数（使用回调形式以确保 doOnStart 在 Promise 执行前调用）
+ * @param lifecycle - 生命周期回调配置
+ * @returns 原始 Promise 的结果
+ *
+ * @example
+ * ```ts
+ * // 基本用法：管理 loading 状态
+ * withLifecycle(
+ *   () => fetchUserData(userId),
+ *   {
+ *     doOnStart: () => setLoading(true),
+ *     doOnSuccess: (user) => setUser(user),
+ *     doOnError: (err) => setError(err.message),
+ *     doFinally: () => setLoading(false)
+ *   }
+ * );
+ * ```
+ */
+export declare function withLifecycle<T>(promiseFn: () => Promise<T>, lifecycle: PromiseLifecycle<T>): Promise<T>;
+//# sourceMappingURL=PromiseLifecycle.d.ts.map

package/dist/flow/PromiseLifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PromiseLifecycle.d.ts","sourceRoot":"","sources":["../../src/flow/PromiseLifecycle.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,gBAAgB,CAAC,CAAC;IAC/B,kBAAkB;IAClB,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,UAAU;IACV,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IACjC,UAAU;IACV,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACrC,+BAA+B;IAC/B,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC3B,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,SAAS,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAC/B,OAAO,CAAC,CAAC,CAAC,CAiBZ"}

package/dist/flow/PromiseLifecycle.js

@@ -0,0 +1,37 @@
+/**
+ * 为 Promise 添加生命周期钩子
+ *
+ * @param promiseFn - 返回 Promise 的函数（使用回调形式以确保 doOnStart 在 Promise 执行前调用）
+ * @param lifecycle - 生命周期回调配置
+ * @returns 原始 Promise 的结果
+ *
+ * @example
+ * ```ts
+ * // 基本用法：管理 loading 状态
+ * withLifecycle(
+ *   () => fetchUserData(userId),
+ *   {
+ *     doOnStart: () => setLoading(true),
+ *     doOnSuccess: (user) => setUser(user),
+ *     doOnError: (err) => setError(err.message),
+ *     doFinally: () => setLoading(false)
+ *   }
+ * );
+ * ```
+ */
+export function withLifecycle(promiseFn, lifecycle) {
+    const { doOnStart, doOnSuccess, doOnError, doFinally } = lifecycle;
+    doOnStart === null || doOnStart === void 0 ? void 0 : doOnStart();
+    return promiseFn()
+        .then((value) => {
+        doOnSuccess === null || doOnSuccess === void 0 ? void 0 : doOnSuccess(value);
+        return value;
+    })
+        .catch((error) => {
+        doOnError === null || doOnError === void 0 ? void 0 : doOnError(error);
+        throw error; // 继续抛出，不吞掉错误
+    })
+        .finally(() => {
+        doFinally === null || doFinally === void 0 ? void 0 : doFinally();
+    });
+}

package/dist/flow/PromiseLoading.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 为 Promise 自动绑定 loading 状态
+ *
+ * @param promiseFn - 返回 Promise 的函数
+ * @param setLoading - React 的 setState 函数，用于设置 loading 状态
+ * @returns 原始 Promise 的结果
+ *
+ * @example
+ * ```tsx
+ * const [loading, setLoading] = useState(false);
+ *
+ * // 自动管理 loading 状态
+ * const handleSubmit = () => {
+ *   withLoading(() => submitForm(data), setLoading);
+ * };
+ *
+ * // 等价于
+ * withLifecycle(() => submitForm(data), {
+ *   doOnStart: () => setLoading(true),
+ *   doFinally: () => setLoading(false)
+ * });
+ * ```
+ */
+export declare function withLoading<T>(promiseFn: () => Promise<T>, setLoading: (loading: boolean) => void): Promise<T>;
+//# sourceMappingURL=PromiseLoading.d.ts.map

package/dist/flow/PromiseLoading.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PromiseLoading.d.ts","sourceRoot":"","sources":["../../src/flow/PromiseLoading.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,WAAW,CAAC,CAAC,EACzB,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,UAAU,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GACvC,OAAO,CAAC,CAAC,CAAC,CAKZ"}

package/dist/flow/PromiseLoading.js

@@ -0,0 +1,30 @@
+import { withLifecycle } from "./PromiseLifecycle";
+/**
+ * 为 Promise 自动绑定 loading 状态
+ *
+ * @param promiseFn - 返回 Promise 的函数
+ * @param setLoading - React 的 setState 函数，用于设置 loading 状态
+ * @returns 原始 Promise 的结果
+ *
+ * @example
+ * ```tsx
+ * const [loading, setLoading] = useState(false);
+ *
+ * // 自动管理 loading 状态
+ * const handleSubmit = () => {
+ *   withLoading(() => submitForm(data), setLoading);
+ * };
+ *
+ * // 等价于
+ * withLifecycle(() => submitForm(data), {
+ *   doOnStart: () => setLoading(true),
+ *   doFinally: () => setLoading(false)
+ * });
+ * ```
+ */
+export function withLoading(promiseFn, setLoading) {
+    return withLifecycle(promiseFn, {
+        doOnStart: () => setLoading(true),
+        doFinally: () => setLoading(false)
+    });
+}

package/dist/flow/index.d.ts

@@ -1,2 +1,4 @@
-export * from './promise_ext';
+export * from './PromiseExt';
+export * from './PromiseLifecycle';
+export * from './PromiseLoading';
 //# sourceMappingURL=index.d.ts.map

package/dist/flow/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/flow/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/flow/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC"}

package/dist/flow/index.js

@@ -1 +1,3 @@
-export * from './promise_ext';
+export * from './PromiseExt';
+export * from './PromiseLifecycle';
+export * from './PromiseLoading';

package/dist/index.js

@@ -1,4 +1,4 @@
-import { initPromiseErrorExtension } from "./flow/promise_ext";
+import { initPromiseErrorExtension } from "./flow/PromiseExt";
 export * from './sse';
 export * from './fetch';
 export * from './utils';

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.3",
+  "version": "0.6.5",
   "private": false,
   "type": "module",
   "main": "dist/index.js",

package/dist/flow/promise_ext.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"promise_ext.d.ts","sourceRoot":"","sources":["../../src/flow/promise_ext.ts"],"names":[],"mappings":"AAIA,OAAO,CAAC,MAAM,CAAC;IACX,UAAU,OAAO,CAAC,CAAC;QACf,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;KACjE;CACJ;AAGD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAM1D;AAED,wBAAgB,yBAAyB,IAAI,IAAI,CAgDhD"}