xxf_react 0.6.0 → 0.6.2

package/README.md

@@ -1,12 +1,14 @@
 # @xxf/react
 
-To install dependencies:
+React 工具库，提供常用的组件、Hooks 和工具函数。
+
+## 安装
 
 ```bash
 bun install
 ```
 
-To run:
+## 运行
 
 ```bash
 bun run src/index.ts
@@ -14,6 +16,22 @@ bun run src/index.ts
 
 This project was created using `bun init` in bun v1.3.2. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.
 
-## 文档
+## 模块文档
+
+| 模块 | 说明 |
+|------|------|
+| [event-bus](./src/event-bus/README.md) | 事件总线，支持跨 Tab 通信 |
+| [fetch](./src/fetch/README.md) | 带超时控制的 fetch 封装 |
+| [flow](./src/flow/README.md) | Promise 扩展，全局错误处理 |
+| [foundation](./src/foundation/README.md) | 基础工具，性能监控 |
+| [layout](./src/layout/README.md) | 布局组件，悬浮交互 |
+| [media](./src/media/README.md) | 媒体组件，视频播放 |
+| [models](./src/models/README.md) | 数据模型，API 响应类型 |
+| [refresh](./src/refresh/README.md) | 刷新加载，分页加载更多 |
+| [responsive](./src/responsive/README.md) | 响应式布局，设备检测 |
+| [sse](./src/sse/README.md) | Server-Sent Events 连接管理 |
+| [utils](./src/utils/README.md) | 工具函数，滚动定位、组件刷新 |
+
+## 详细文档
 
 - [PlaybackQueue 播放队列状态管理](./src/media/playback-queue-store.md)

package/dist/layout/button/XButton.d.ts

@@ -0,0 +1,97 @@
+import React, { ButtonHTMLAttributes, ReactNode } from 'react';
+/**
+ * 加载指示器位置
+ * - `start`: 指示器在内容左侧
+ * - `center`: 指示器居中，内容隐藏（保持宽度）
+ * - `end`: 指示器在内容右侧
+ */
+export type LoadingGravity = 'start' | 'center' | 'end';
+/**
+ * XButton 组件属性
+ * @extends ButtonHTMLAttributes<HTMLButtonElement> 继承原生 button 所有属性
+ */
+export interface XButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    /**
+     * 加载状态
+     * - 为 `true` 时按钮不可点击，显示加载指示器
+     * @default false
+     */
+    loading?: boolean;
+    /**
+     * 加载指示器位置
+     * - `start`: 左侧
+     * - `center`: 居中（隐藏内容，保持宽度避免抖动）
+     * - `end`: 右侧
+     * @default 'start'
+     */
+    loadingGravity?: LoadingGravity;
+    /**
+     * 自定义加载指示器
+     * - 不传则使用默认的旋转圆环
+     * - 尺寸建议使用 `em` 单位以跟随字体大小
+     */
+    loadingIndicator?: ReactNode;
+    /**
+     * 指示器与内容的间距（像素）
+     * - 仅在 `loadingGravity` 为 `start` 或 `end` 时生效
+     * @default 8
+     */
+    loadingGap?: number;
+    /**
+     * 点击防抖等待时间（毫秒）
+     * - 防止用户快速连续点击
+     * - 使用 leading 模式：首次点击立即执行，后续点击在等待时间内被忽略
+     * - 设为 0 时禁用防抖
+     * @default 500
+     */
+    debounceWait?: number;
+    /**
+     * 是否阻止事件冒泡
+     * @default false
+     */
+    stopPropagation?: boolean;
+    /** 按钮内容，支持任意 ReactNode（文本、元素、组件等） */
+    children?: ReactNode;
+}
+/**
+ * XButton - 支持加载状态的按钮组件
+ *
+ * @description
+ * 封装了常见的按钮加载交互：
+ * - 加载时自动禁用点击
+ * - 支持自定义加载指示器位置（左/中/右）
+ * - 居中模式保持按钮宽度，避免布局抖动
+ * - 支持 ref 转发
+ * - 支持点击防抖，防止重复提交
+ * - 不依赖外部库，纯内联样式实现
+ *
+ * @example
+ * ```tsx
+ * // 基本用法
+ * <XButton loading={isLoading} onClick={handleSubmit}>
+ *   提交
+ * </XButton>
+ *
+ * // 加载指示器在左侧
+ * <XButton loading loadingGravity="start">
+ *   加载中...
+ * </XButton>
+ *
+ * // 自定义加载指示器
+ * <XButton loading loadingIndicator={<MySpinner />}>
+ *   处理中
+ * </XButton>
+ *
+ * // 防抖点击（500ms 内只响应第一次）
+ * <XButton debounceWait={500} onClick={handleSubmit}>
+ *   提交订单
+ * </XButton>
+ *
+ * // 阻止冒泡 + 防抖
+ * <XButton debounceWait={500} stopPropagation onClick={handleSubmit}>
+ *   提交
+ * </XButton>
+ * ```
+ */
+export declare const XButton: React.ForwardRefExoticComponent<XButtonProps & React.RefAttributes<HTMLButtonElement>>;
+//# sourceMappingURL=XButton.d.ts.map

package/dist/layout/button/XButton.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"XButton.d.ts","sourceRoot":"","sources":["../../../src/layout/button/XButton.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,EAAa,oBAAoB,EAAE,SAAS,EAAgB,MAAM,OAAO,CAAC;AAIxF;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAC;AAExD;;;GAGG;AACH,MAAM,WAAW,YAAa,SAAQ,oBAAoB,CAAC,iBAAiB,CAAC;IACzE;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;IAEhC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,SAAS,CAAC;IAE7B;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B,qCAAqC;IACrC,QAAQ,CAAC,EAAE,SAAS,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,OAAO,wFAyInB,CAAC"}

package/dist/layout/button/XButton.js

@@ -0,0 +1,127 @@
+'use client';
+import React, { forwardRef } from 'react';
+import { useDebouncedCallback } from 'use-debounce';
+import { XSpinner } from "../spinner/XSpinner";
+/**
+ * XButton - 支持加载状态的按钮组件
+ *
+ * @description
+ * 封装了常见的按钮加载交互：
+ * - 加载时自动禁用点击
+ * - 支持自定义加载指示器位置（左/中/右）
+ * - 居中模式保持按钮宽度，避免布局抖动
+ * - 支持 ref 转发
+ * - 支持点击防抖，防止重复提交
+ * - 不依赖外部库，纯内联样式实现
+ *
+ * @example
+ * ```tsx
+ * // 基本用法
+ * <XButton loading={isLoading} onClick={handleSubmit}>
+ *   提交
+ * </XButton>
+ *
+ * // 加载指示器在左侧
+ * <XButton loading loadingGravity="start">
+ *   加载中...
+ * </XButton>
+ *
+ * // 自定义加载指示器
+ * <XButton loading loadingIndicator={<MySpinner />}>
+ *   处理中
+ * </XButton>
+ *
+ * // 防抖点击（500ms 内只响应第一次）
+ * <XButton debounceWait={500} onClick={handleSubmit}>
+ *   提交订单
+ * </XButton>
+ *
+ * // 阻止冒泡 + 防抖
+ * <XButton debounceWait={500} stopPropagation onClick={handleSubmit}>
+ *   提交
+ * </XButton>
+ * ```
+ */
+export const XButton = forwardRef(function XButton({ loading = false, loadingGravity = 'start', loadingIndicator, loadingGap = 8, debounceWait = 500, stopPropagation = false, children, onClick, disabled, style, type = 'button', ...rest }, ref) {
+    /** 使用自定义指示器或默认指示器 */
+    const indicator = loadingIndicator !== null && loadingIndicator !== void 0 ? loadingIndicator : React.createElement(XSpinner, null);
+    /**
+     * 防抖处理后的点击回调
+     * - leading: true  首次点击立即执行
+     * - trailing: false  等待时间结束后不再执行
+     */
+    const debouncedOnClick = useDebouncedCallback((e) => {
+        onClick === null || onClick === void 0 ? void 0 : onClick(e);
+    }, debounceWait, { leading: true, trailing: false });
+    /**
+     * 点击事件处理
+     * - 阻止冒泡（可选）
+     * - loading 或 disabled 时拦截
+     * - debounceWait > 0 时使用防抖回调
+     */
+    const handleClick = (e) => {
+        // 阻止冒泡
+        if (stopPropagation) {
+            e.stopPropagation();
+        }
+        // loading 或 disabled 时拦截
+        if (loading || disabled) {
+            e.preventDefault();
+            return;
+        }
+        // 根据 debounceWait 决定是否使用防抖
+        if (debounceWait > 0) {
+            debouncedOnClick(e);
+        }
+        else {
+            onClick === null || onClick === void 0 ? void 0 : onClick(e);
+        }
+    };
+    /** 按钮基础样式，使用 flexbox 布局 */
+    const baseStyle = {
+        display: 'inline-flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        position: 'relative',
+        // 仅在 start/end 模式下应用 gap
+        gap: loading && loadingGravity !== 'center' ? loadingGap : undefined,
+        ...style,
+    };
+    /**
+     * 渲染按钮内容
+     * - 非加载状态：直接渲染 children
+     * - start：指示器 + children
+     * - end：children + 指示器
+     * - center：children 隐藏占位 + 指示器绝对定位居中
+     */
+    const renderContent = () => {
+        if (!loading) {
+            return children;
+        }
+        switch (loadingGravity) {
+            case 'start':
+                return (React.createElement(React.Fragment, null,
+                    indicator,
+                    children));
+            case 'end':
+                return (React.createElement(React.Fragment, null,
+                    children,
+                    indicator));
+            case 'center':
+            default:
+                // children 保持可见，indicator 绝对定位叠加在上面
+                // 背景透明，可以看到 children 内容
+                return (React.createElement(React.Fragment, null,
+                    children,
+                    React.createElement("div", { style: {
+                            position: 'absolute',
+                            inset: 0,
+                            display: 'flex',
+                            alignItems: 'center',
+                            justifyContent: 'center',
+                            backgroundColor: 'transparent',
+                        } }, indicator)));
+        }
+    };
+    return (React.createElement("button", { ref: ref, type: type, ...rest, style: baseStyle, disabled: disabled || loading, onClick: handleClick, "aria-busy": loading, "aria-disabled": disabled || loading }, renderContent()));
+});

package/dist/layout/index.d.ts

@@ -7,4 +7,6 @@ export * from './image/XImage';
 export * from './visibility/ElementVisibilityHooks';
 export * from './virtualized/VirtualizedConfig';
 export * from './hover/XHover';
+export * from './button/XButton';
+export * from './spinner/XSpinner';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/layout/index.ts"],"names":[],"mappings":"AAAA,cAAc,gCAAgC,CAAA;AAC9C,cAAc,kCAAkC,CAAA;AAChD,cAAc,kCAAkC,CAAA;AAChD,cAAc,8BAA8B,CAAA;AAC5C,cAAc,2BAA2B,CAAA;AACzC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,qCAAqC,CAAA;AACnD,cAAc,iCAAiC,CAAA;AAC/C,cAAc,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/layout/index.ts"],"names":[],"mappings":"AAAA,cAAc,gCAAgC,CAAA;AAC9C,cAAc,kCAAkC,CAAA;AAChD,cAAc,kCAAkC,CAAA;AAChD,cAAc,8BAA8B,CAAA;AAC5C,cAAc,2BAA2B,CAAA;AACzC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,qCAAqC,CAAA;AACnD,cAAc,iCAAiC,CAAA;AAC/C,cAAc,gBAAgB,CAAA;AAC9B,cAAc,kBAAkB,CAAA;AAChC,cAAc,oBAAoB,CAAA"}

package/dist/layout/index.js

@@ -7,3 +7,5 @@ export * from './image/XImage';
 export * from './visibility/ElementVisibilityHooks';
 export * from './virtualized/VirtualizedConfig';
 export * from './hover/XHover';
+export * from './button/XButton';
+export * from './spinner/XSpinner';

package/dist/layout/spinner/XSpinner.d.ts

@@ -0,0 +1,43 @@
+import React from "react";
+/**
+ * XSpinner 组件属性
+ */
+export interface XSpinnerProps {
+    /**
+     * 自定义样式类名
+     * - 可覆盖默认的尺寸、颜色、动画等样式
+     * @example "w-8 h-8 border-blue-500"
+     */
+    className?: string;
+}
+/**
+ * XSpinner - 轻量级加载指示器组件
+ *
+ * @description
+ * 使用 CSS border + rotate 动画实现的高性能 spinner：
+ * - 基于 div + Tailwind CSS，无 SVG 解析开销
+ * - 尺寸使用 `1em`，自动跟随父元素字体大小
+ * - 默认白色边框，适合深色背景
+ * - 可通过 className 完全自定义样式
+ *
+ * @example
+ * ```tsx
+ * // 基本用法（跟随父元素字体大小）
+ * <XSpinner />
+ *
+ * // 自定义尺寸
+ * <XSpinner className="w-8 h-8" />
+ *
+ * // 自定义颜色（深色主题）
+ * <XSpinner className="border-gray-800 border-t-transparent" />
+ *
+ * // 在按钮中使用
+ * <button className="text-lg">
+ *   <XSpinner /> 加载中...
+ * </button>
+ * ```
+ *
+ * @see XButton - 内置 XSpinner 作为默认加载指示器
+ */
+export declare const XSpinner: ({ className }?: XSpinnerProps) => React.JSX.Element;
+//# sourceMappingURL=XSpinner.d.ts.map

package/dist/layout/spinner/XSpinner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"XSpinner.d.ts","sourceRoot":"","sources":["../../../src/layout/spinner/XSpinner.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,MAAM,OAAO,CAAC;AAG1B;;GAEG;AACH,MAAM,WAAW,aAAa;IAC1B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,QAAQ,GAAI,gBAAa,aAAkB,sBAevD,CAAC"}

package/dist/layout/spinner/XSpinner.js

@@ -0,0 +1,43 @@
+'use client';
+import React from "react";
+import { cn } from "tailwind-variants";
+/**
+ * XSpinner - 轻量级加载指示器组件
+ *
+ * @description
+ * 使用 CSS border + rotate 动画实现的高性能 spinner：
+ * - 基于 div + Tailwind CSS，无 SVG 解析开销
+ * - 尺寸使用 `1em`，自动跟随父元素字体大小
+ * - 默认白色边框，适合深色背景
+ * - 可通过 className 完全自定义样式
+ *
+ * @example
+ * ```tsx
+ * // 基本用法（跟随父元素字体大小）
+ * <XSpinner />
+ *
+ * // 自定义尺寸
+ * <XSpinner className="w-8 h-8" />
+ *
+ * // 自定义颜色（深色主题）
+ * <XSpinner className="border-gray-800 border-t-transparent" />
+ *
+ * // 在按钮中使用
+ * <button className="text-lg">
+ *   <XSpinner /> 加载中...
+ * </button>
+ * ```
+ *
+ * @see XButton - 内置 XSpinner 作为默认加载指示器
+ */
+export const XSpinner = ({ className } = {}) => (React.createElement("div", { className: cn(
+    // 尺寸：1em 跟随字体大小
+    "w-[1em] h-[1em]", 
+    // 边框样式：白色圆环，顶部透明形成缺口
+    "border-2 border-white border-t-transparent rounded-full", 
+    // 动画：无限旋转
+    "animate-spin", 
+    // 透明度：略微降低避免过亮
+    "opacity-80", 
+    // 用户自定义类名
+    className) }));

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;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,qBAiWpC"}
+{"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

@@ -156,21 +156,29 @@ export function XVideo({ src, poster, posterFadeOutDuration = 300, bufferingIndi
         checkAndSetReady();
     }, [playState.canPlay, checkAndSetReady]);
     /**
-     * Effect: 播放结束或出错时显示封面
+     * Effect: 暂停、播放结束或出错时显示封面
      *
+     * 视频暂停时，重新显示封面
      * 视频播放结束时，重新显示封面，避免最后一帧可能是黑屏的问题
      * 视频播放出错时，重新显示封面，作为错误指示器的背景
      *
-     * 当视频重新播放时（ended 从 true 变为 false），封面会通过
-     * 正常的 checkAndSetReady 流程再次淡出
+     * 当视频重新播放时，封面会通过正常的 checkAndSetReady 流程再次淡出
+     *
+     * 注意：必须同时重置 firstFrameRenderedRef，否则 checkAndSetReady 会立即再次隐藏封面
      */
     useEffect(() => {
-        if ((playState.ended || playState.error) && poster) {
-            // 播放结束或出错，显示封面
+        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, poster]);
+    }, [playState.ended, playState.error, playState.playing, poster]);
     /**
      * Effect: 通过 currentTime 检测第一帧（回退方案）
      *
@@ -178,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
      *
@@ -197,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;
@@ -206,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) {
@@ -226,7 +241,7 @@ export function XVideo({ src, poster, posterFadeOutDuration = 300, bufferingIndi
             };
         }
         // 不支持 requestVideoFrameCallback 的浏览器由 currentTime effect 处理
-    }, [src, videoRef, checkAndSetReady]);
+    }, [src, videoRef, playState.playing, checkAndSetReady]);
     // ==================== 渲染逻辑 ====================
     /**
      * 封面元素 - 使用 useMemo 优化

package/package.json

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