xxf_react 0.5.9 → 0.6.1

package/dist/media/components/XVideo.d.ts

@@ -74,6 +74,35 @@ export interface XVideoProps extends Omit<VideoHTMLAttributes<HTMLVideoElement>,
      * ```
      */
     bufferingIndicator?: ReactNode;
+    /**
+     * 错误指示器回调（可选）
+     *
+     * - 视频加载或播放失败时调用此回调渲染错误 UI
+     * - 接收 MediaError 参数，可根据错误类型显示不同内容
+     * - 不传则使用默认的错误提示（显示封面 + 错误图标）
+     * - 传 null 可禁用错误指示器
+     *
+     * MediaError.code 错误码：
+     * - 1 (MEDIA_ERR_ABORTED): 用户中止
+     * - 2 (MEDIA_ERR_NETWORK): 网络错误
+     * - 3 (MEDIA_ERR_DECODE): 解码错误
+     * - 4 (MEDIA_ERR_SRC_NOT_SUPPORTED): 格式不支持
+     *
+     * @example
+     * ```tsx
+     * // 根据错误类型显示不同提示
+     * <XVideo
+     *   src={videoUrl}
+     *   errorIndicator={(error) => (
+     *     <div>{error.code === 2 ? '网络错误' : '播放失败'}</div>
+     *   )}
+     * />
+     *
+     * // 禁用错误指示器
+     * <XVideo src={videoUrl} errorIndicator={null} />
+     * ```
+     */
+    errorIndicator?: ((error: MediaError) => ReactNode) | null;
     /**
      * 容器 className（可选）
      *
@@ -172,5 +201,5 @@ export interface XVideoProps extends Omit<VideoHTMLAttributes<HTMLVideoElement>,
  * <XVideo src={videoUrl} videoRef={videoRef} poster={coverUrl} />
  * ```
  */
-export declare function XVideo({ src, poster, posterFadeOutDuration, bufferingIndicator, className, videoRef: externalVideoRef, onReady, preload, playsInline, crossOrigin, ...videoProps }: XVideoProps): React.JSX.Element;
+export declare function XVideo({ src, poster, posterFadeOutDuration, bufferingIndicator, errorIndicator, className, videoRef: externalVideoRef, onReady, preload, playsInline, crossOrigin, ...videoProps }: XVideoProps): React.JSX.Element;
 //# sourceMappingURL=XVideo.d.ts.map

package/dist/media/components/XVideo.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"XVideo.d.ts","sourceRoot":"","sources":["../../../src/media/components/XVideo.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,EAMV,SAAS,EACT,mBAAmB,EACnB,SAAS,EACZ,MAAM,OAAO,CAAA;AAKd;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,WAAY,SAAQ,IAAI,CAAC,mBAAmB,CAAC,gBAAgB,CAAC,EAAE,QAAQ,CAAC;IACtF;;;;;;;OAOG;IACH,GAAG,EAAE,MAAM,CAAA;IAEX;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAE3B;;;;;;;OAOG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAE9B;;;;;;;;;;;;;;;;;;OAkBG;IACH,kBAAkB,CAAC,EAAE,SAAS,CAAA;IAE9B;;;;;;;;;;;;;;OAcG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAA;IAE7C;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;CACvB;AAgBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,MAAM,CAAC,EACI,GAAG,EACH,MAAM,EACN,qBAA2B,EAC3B,kBAAkB,EAClB,SAAS,EACT,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,EACP,OAAgB,EAChB,WAAkB,EAClB,WAAyB,EACzB,GAAG,UAAU,EAChB,EAAE,WAAW,qBA6TpC"}
+{"version":3,"file":"XVideo.d.ts","sourceRoot":"","sources":["../../../src/media/components/XVideo.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,EAMV,SAAS,EACT,mBAAmB,EACnB,SAAS,EACZ,MAAM,OAAO,CAAA;AAOd;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,WAAY,SAAQ,IAAI,CAAC,mBAAmB,CAAC,gBAAgB,CAAC,EAAE,QAAQ,CAAC;IACtF;;;;;;;OAOG;IACH,GAAG,EAAE,MAAM,CAAA;IAEX;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAE3B;;;;;;;OAOG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAE9B;;;;;;;;;;;;;;;;;;OAkBG;IACH,kBAAkB,CAAC,EAAE,SAAS,CAAA;IAE9B;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,cAAc,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,UAAU,KAAK,SAAS,CAAC,GAAG,IAAI,CAAA;IAE1D;;;;;;;;;;;;;;OAcG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAA;IAE7C;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,MAAM,CAAC,EACI,GAAG,EACH,MAAM,EACN,qBAA2B,EAC3B,kBAAkB,EAClB,cAAc,EACd,SAAS,EACT,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,EACP,OAAgB,EAChB,WAAkB,EAClB,WAAyB,EACzB,GAAG,UAAU,EAChB,EAAE,WAAW,qBAgXpC"}

package/dist/media/components/XVideo.js

@@ -3,16 +3,8 @@ import React, { useRef, useState, useEffect, useCallback, useMemo, } from 'react
 import { cn } from 'tailwind-variants';
 import { XImage } from 'xxf_react';
 import { useVideoState } from 'xxf_react/media';
-/**
- * 默认缓冲指示器组件
- *
- * 显示一个居中的旋转 loading spinner
- * 使用 React.memo 优化，避免不必要的重渲染
- */
-const DefaultBufferingIndicator = React.memo(function DefaultBufferingIndicator() {
-    return (React.createElement("div", { className: "absolute inset-0 flex items-center justify-center pointer-events-none" },
-        React.createElement("div", { className: "w-8 h-8 border-4 border-white/30 border-t-white rounded-full animate-spin" })));
-});
+import { XVideoBufferingIndicator } from './XVideoBufferingIndicator';
+import { XVideoErrorIndicator } from './XVideoErrorIndicator';
 /**
  * XVideo - 通用视频组件
  *
@@ -50,7 +42,7 @@ const DefaultBufferingIndicator = React.memo(function DefaultBufferingIndicator(
  * <XVideo src={videoUrl} videoRef={videoRef} poster={coverUrl} />
  * ```
  */
-export function XVideo({ src, poster, posterFadeOutDuration = 300, bufferingIndicator, className, videoRef: externalVideoRef, onReady, preload = 'auto', playsInline = true, crossOrigin = "anonymous", ...videoProps }) {
+export function XVideo({ src, poster, posterFadeOutDuration = 300, bufferingIndicator, errorIndicator, className, videoRef: externalVideoRef, onReady, preload = 'auto', playsInline = true, crossOrigin = "anonymous", ...videoProps }) {
     // ==================== Refs ====================
     /**
      * 内部 video ref
@@ -163,6 +155,30 @@ export function XVideo({ src, poster, posterFadeOutDuration = 300, bufferingIndi
     useEffect(() => {
         checkAndSetReady();
     }, [playState.canPlay, checkAndSetReady]);
+    /**
+     * Effect: 暂停、播放结束或出错时显示封面
+     *
+     * 视频暂停时，重新显示封面
+     * 视频播放结束时，重新显示封面，避免最后一帧可能是黑屏的问题
+     * 视频播放出错时，重新显示封面，作为错误指示器的背景
+     *
+     * 当视频重新播放时，封面会通过正常的 checkAndSetReady 流程再次淡出
+     *
+     * 注意：必须同时重置 firstFrameRenderedRef，否则 checkAndSetReady 会立即再次隐藏封面
+     */
+    useEffect(() => {
+        if (poster && (playState.ended || playState.error || !playState.playing)) {
+            // 清理淡出定时器，防止正在进行的淡出继续执行
+            if (fadeOutTimerRef.current) {
+                clearTimeout(fadeOutTimerRef.current);
+                fadeOutTimerRef.current = null;
+            }
+            // 重置第一帧标记，防止 checkAndSetReady 立即隐藏封面
+            firstFrameRenderedRef.current = false;
+            setShowPoster(true);
+            setIsReady(false);
+        }
+    }, [playState.ended, playState.error, playState.playing, poster]);
     /**
      * Effect: 通过 currentTime 检测第一帧（回退方案）
      *
@@ -170,13 +186,15 @@ export function XVideo({ src, poster, posterFadeOutDuration = 300, bufferingIndi
      * 使用 currentTime > 0 作为第一帧渲染的近似检测
      *
      * 原理：currentTime > 0 表示视频已开始播放，此时第一帧大概率已渲染
+     *
+     * 注意：必须检查 playState.playing，否则暂停时 currentTime > 0 会立即触发封面隐藏
      */
     useEffect(() => {
-        if (!firstFrameRenderedRef.current && playState.currentTime > 0) {
+        if (!firstFrameRenderedRef.current && playState.currentTime > 0 && playState.playing) {
             firstFrameRenderedRef.current = true;
             checkAndSetReady();
         }
-    }, [playState.currentTime, checkAndSetReady]);
+    }, [playState.currentTime, playState.playing, checkAndSetReady]);
     /**
      * Effect: 第一帧检测 - 优先使用 requestVideoFrameCallback
      *
@@ -189,7 +207,9 @@ export function XVideo({ src, poster, posterFadeOutDuration = 300, bufferingIndi
      * 3. 第一帧渲染时标记 firstFrameRendered 并检查就绪状态
      * 4. cleanup 时取消回调，防止组件卸载后执行
      *
-     * 注意：cleanedUp flag 用于防止组件卸载后的状态更新（React 严格模式下的竞态条件）
+     * 注意：
+     * - cleanedUp flag 用于防止组件卸载后的状态更新（React 严格模式下的竞态条件）
+     * - 必须检查 playState.playing，否则暂停时可能错误触发
      */
     useEffect(() => {
         const video = videoRef.current;
@@ -198,6 +218,9 @@ export function XVideo({ src, poster, posterFadeOutDuration = 300, bufferingIndi
         // 如果已经检测到第一帧，无需重复检测
         if (firstFrameRenderedRef.current)
             return;
+        // 视频未播放时不注册回调
+        if (!playState.playing)
+            return;
         // 检查浏览器是否支持 requestVideoFrameCallback
         const supportsVideoFrameCallback = 'requestVideoFrameCallback' in HTMLVideoElement.prototype;
         if (supportsVideoFrameCallback) {
@@ -218,7 +241,7 @@ export function XVideo({ src, poster, posterFadeOutDuration = 300, bufferingIndi
             };
         }
         // 不支持 requestVideoFrameCallback 的浏览器由 currentTime effect 处理
-    }, [src, videoRef, checkAndSetReady]);
+    }, [src, videoRef, playState.playing, checkAndSetReady]);
     // ==================== 渲染逻辑 ====================
     /**
      * 封面元素 - 使用 useMemo 优化
@@ -265,5 +288,10 @@ export function XVideo({ src, poster, posterFadeOutDuration = 300, bufferingIndi
     return (React.createElement("div", { className: cn('relative overflow-hidden', className) },
         React.createElement("video", { ref: videoRef, src: src, preload: preload, crossOrigin: crossOrigin, playsInline: playsInline, className: "w-full h-full object-cover", ...videoProps }),
         posterElement && showPoster && (React.createElement("div", { className: cn('absolute inset-0 transition-opacity', isReady ? 'opacity-0 pointer-events-none' : 'opacity-100'), style: { transitionDuration: `${posterFadeOutDuration}ms` } }, posterElement)),
-        isReady && playState.buffering && (bufferingIndicator !== null && bufferingIndicator !== void 0 ? bufferingIndicator : React.createElement(DefaultBufferingIndicator, null))));
+        isReady && playState.buffering && !playState.error && (bufferingIndicator !== null && bufferingIndicator !== void 0 ? bufferingIndicator : React.createElement(XVideoBufferingIndicator, null)),
+        playState.error && (errorIndicator === null
+            ? null
+            : errorIndicator
+                ? errorIndicator(playState.error)
+                : React.createElement(XVideoErrorIndicator, { error: playState.error }))));
 }

package/dist/media/components/XVideoBufferingIndicator.d.ts

@@ -0,0 +1,13 @@
+import React from 'react';
+export interface XVideoBufferingIndicatorProps {
+    /** 自定义样式类名 */
+    className?: string;
+}
+/**
+ * XVideo 默认缓冲指示器组件
+ *
+ * 显示一个居中的旋转 loading spinner
+ * 使用 React.memo 优化，避免不必要的重渲染
+ */
+export declare const XVideoBufferingIndicator: React.NamedExoticComponent<XVideoBufferingIndicatorProps>;
+//# sourceMappingURL=XVideoBufferingIndicator.d.ts.map

package/dist/media/components/XVideoBufferingIndicator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"XVideoBufferingIndicator.d.ts","sourceRoot":"","sources":["../../../src/media/components/XVideoBufferingIndicator.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,MAAM,OAAO,CAAA;AAGzB,MAAM,WAAW,6BAA6B;IAC1C,cAAc;IACd,SAAS,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,2DAQnC,CAAA"}

package/dist/media/components/XVideoBufferingIndicator.js

@@ -0,0 +1,13 @@
+'use client';
+import React from 'react';
+import { cn } from 'tailwind-variants';
+/**
+ * XVideo 默认缓冲指示器组件
+ *
+ * 显示一个居中的旋转 loading spinner
+ * 使用 React.memo 优化，避免不必要的重渲染
+ */
+export const XVideoBufferingIndicator = React.memo(function XVideoBufferingIndicator({ className } = {}) {
+    return (React.createElement("div", { className: cn('absolute inset-0 flex items-center justify-center pointer-events-none', className) },
+        React.createElement("div", { className: "w-8 h-8 border-4 border-white/30 border-t-white rounded-full animate-spin" })));
+});

package/dist/media/components/XVideoErrorIndicator.d.ts

@@ -0,0 +1,15 @@
+import React from 'react';
+export interface XVideoErrorIndicatorProps {
+    /** 视频播放错误对象 */
+    error: MediaError;
+    /** 自定义样式类名 */
+    className?: string;
+}
+/**
+ * XVideo 默认错误指示器组件
+ *
+ * 显示一个居中的错误图标和错误信息（最多50字符）
+ * 使用 React.memo 优化，避免不必要的重渲染
+ */
+export declare const XVideoErrorIndicator: React.NamedExoticComponent<XVideoErrorIndicatorProps>;
+//# sourceMappingURL=XVideoErrorIndicator.d.ts.map

package/dist/media/components/XVideoErrorIndicator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"XVideoErrorIndicator.d.ts","sourceRoot":"","sources":["../../../src/media/components/XVideoErrorIndicator.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,MAAM,OAAO,CAAA;AAGzB,MAAM,WAAW,yBAAyB;IACtC,eAAe;IACf,KAAK,EAAE,UAAU,CAAA;IACjB,cAAc;IACd,SAAS,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,uDA6B/B,CAAA"}

package/dist/media/components/XVideoErrorIndicator.js

@@ -0,0 +1,19 @@
+'use client';
+import React from 'react';
+import { cn } from 'tailwind-variants';
+/**
+ * XVideo 默认错误指示器组件
+ *
+ * 显示一个居中的错误图标和错误信息（最多50字符）
+ * 使用 React.memo 优化，避免不必要的重渲染
+ */
+export const XVideoErrorIndicator = React.memo(function XVideoErrorIndicator({ error, className }) {
+    const errorMessage = error.message
+        ? error.message.slice(0, 50) + (error.message.length > 50 ? '...' : '')
+        : 'Video load failed';
+    const message = `code:${error.code} ${errorMessage}`;
+    return (React.createElement("div", { className: cn('absolute inset-0 flex flex-col items-center justify-center bg-black/60 pointer-events-none', className) },
+        React.createElement("svg", { className: "w-12 h-12 text-white/80", fill: "none", viewBox: "0 0 24 24", stroke: "currentColor", strokeWidth: 1.5 },
+            React.createElement("path", { strokeLinecap: "round", strokeLinejoin: "round", d: "M12 9v3.75m9-.75a9 9 0 11-18 0 9 9 0 0118 0zm-9 3.75h.008v.008H12v-.008z" })),
+        React.createElement("span", { className: "mt-2 text-sm text-white/80 px-4 text-center" }, message)));
+});

package/dist/media/index.d.ts

@@ -1,4 +1,6 @@
 export * from './video-state';
 export * from './playback-queue-store';
 export * from './components/XVideo';
+export * from './components/XVideoBufferingIndicator';
+export * from './components/XVideoErrorIndicator';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/media/index.ts"],"names":[],"mappings":"AAEA,cAAc,eAAe,CAAC;AAC9B,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/media/index.ts"],"names":[],"mappings":"AAEA,cAAc,eAAe,CAAC;AAC9B,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uCAAuC,CAAC;AACtD,cAAc,mCAAmC,CAAC"}

package/dist/media/index.js

@@ -2,3 +2,5 @@
 export * from './video-state';
 export * from './playback-queue-store';
 export * from './components/XVideo';
+export * from './components/XVideoBufferingIndicator';
+export * from './components/XVideoErrorIndicator';

package/package.json

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