xxf_react 0.8.1 → 0.8.2

package/dist/layout/image/XImage.d.ts

@@ -3,31 +3,38 @@ import type { XImageProps } from "./XImage.types";
 /**
  * 生产级图片组件
  *
- * 基于 react-lazy-load-image-component 实现，支持：
- * - 懒加载 + IntersectionObserver
- * - 多种加载效果 (blur/opacity/black-and-white) - CSS 已内置，无需导入
+ * 基于 next/image 实现，支持：
+ * - 双层渲染：placeholder 先加载，主图加载完成后 blur 过渡
+ * - 自动图片优化（Next.js 内置）
  * - 错误处理 + 自动重试
  * - fallback 备用图/组件
- * - 性能优化 (配合 XImageGallery 使用 trackWindowScroll)
  *
  * @example
  * ```tsx
  * // 基础用法
  * <XImage src="/photo.jpg" alt="Photo" width={400} height={300} />
  *
- * // 带模糊效果（提供 placeholder URL 自动启用 blur）
- * <XImage src="/photo.jpg" placeholder="/photo-tiny.jpg" />
- *
- * // 自定义占位组件
- * <XImage src="/photo.jpg" placeholder={<Skeleton />} effect="opacity" />
+ * // 带 placeholder 模糊过渡（推荐使用小尺寸缩略图，如 w=20）
+ * <XImage
+ *   src="/photo.jpg?w=800"
+ *   placeholder="/photo.jpg?w=20"
+ *   width={400}
+ *   height={300}
+ * />
  *
- * // 带错误处理
+ * // 带错误处理和重试
  * <XImage
  *   src="/photo.jpg"
  *   fallback="/fallback.jpg"
  *   retryCount={2}
  *   retryDelay={1000}
  * />
+ *
+ * // 自定义占位组件
+ * <XImage
+ *   src="/photo.jpg"
+ *   placeholder={<Skeleton className="w-full h-full" />}
+ * />
  * ```
  */
 export declare const XImage: React.NamedExoticComponent<XImageProps & React.RefAttributes<HTMLDivElement | HTMLImageElement>>;

package/dist/layout/image/XImage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"XImage.d.ts","sourceRoot":"","sources":["../../../src/layout/image/XImage.tsx"],"names":[],"mappings":"AAEA,OAAO,KASN,MAAM,OAAO,CAAC;AAEf,OAAO,KAAK,EAAE,WAAW,EAAgB,MAAM,gBAAgB,CAAC;AAIhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,MAAM,kGAoUlB,CAAC;AAEF,eAAe,MAAM,CAAC"}
+{"version":3,"file":"XImage.d.ts","sourceRoot":"","sources":["../../../src/layout/image/XImage.tsx"],"names":[],"mappings":"AAEA,OAAO,KAQN,MAAM,OAAO,CAAC;AAEf,OAAO,KAAK,EAAE,WAAW,EAAgB,MAAM,gBAAgB,CAAC;AAmBhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,MAAM,kGA4TlB,CAAC;AAEF,eAAe,MAAM,CAAC"}

package/dist/layout/image/XImage.js

@@ -1,99 +1,109 @@
 "use client";
-import React, { useState, useEffect, useCallback, useRef, forwardRef, memo, useMemo, useContext, } from "react";
-import { LazyLoadImage } from "react-lazy-load-image-component";
-import { ScrollPositionContext } from "./XImageGallery";
-import { injectEffectStyles } from "./XImage.effects";
+import React, { useState, useEffect, useCallback, useRef, forwardRef, memo, useMemo, } from "react";
+import Image from "next/image";
+// ============================================================================
+// 常量定义
+// ============================================================================
+/** 过渡动画时长 */
+const TRANSITION_DURATION = "0.3s";
+/** 占位图模糊程度 */
+const PLACEHOLDER_BLUR = "20px";
+/** 占位图放大比例（防止模糊边缘露出） */
+const PLACEHOLDER_SCALE = 1.1;
+// ============================================================================
+// 组件实现
+// ============================================================================
 /**
  * 生产级图片组件
  *
- * 基于 react-lazy-load-image-component 实现，支持：
- * - 懒加载 + IntersectionObserver
- * - 多种加载效果 (blur/opacity/black-and-white) - CSS 已内置，无需导入
+ * 基于 next/image 实现，支持：
+ * - 双层渲染：placeholder 先加载，主图加载完成后 blur 过渡
+ * - 自动图片优化（Next.js 内置）
  * - 错误处理 + 自动重试
  * - fallback 备用图/组件
- * - 性能优化 (配合 XImageGallery 使用 trackWindowScroll)
  *
  * @example
  * ```tsx
  * // 基础用法
  * <XImage src="/photo.jpg" alt="Photo" width={400} height={300} />
  *
- * // 带模糊效果（提供 placeholder URL 自动启用 blur）
- * <XImage src="/photo.jpg" placeholder="/photo-tiny.jpg" />
- *
- * // 自定义占位组件
- * <XImage src="/photo.jpg" placeholder={<Skeleton />} effect="opacity" />
+ * // 带 placeholder 模糊过渡（推荐使用小尺寸缩略图，如 w=20）
+ * <XImage
+ *   src="/photo.jpg?w=800"
+ *   placeholder="/photo.jpg?w=20"
+ *   width={400}
+ *   height={300}
+ * />
  *
- * // 带错误处理
+ * // 带错误处理和重试
  * <XImage
  *   src="/photo.jpg"
  *   fallback="/fallback.jpg"
  *   retryCount={2}
  *   retryDelay={1000}
  * />
+ *
+ * // 自定义占位组件
+ * <XImage
+ *   src="/photo.jpg"
+ *   placeholder={<Skeleton className="w-full h-full" />}
+ * />
  * ```
  */
 export const XImage = memo(forwardRef(function XImage({ 
-// 基础属性
-src, alt = "", width, height, className, style, objectFit, objectPosition, fill, 
-// 懒加载配置
-lazy = true, threshold = 100, effect, placeholder, useIntersectionObserver = true, delayMethod, delayTime, 
-// 错误处理
-fallback, retryCount = 0, retryDelay = 1000, 
-// 性能优化
-scrollPosition, visibleByDefault = false, 
-// 事件回调
-onLoad, onError, onVisible, onStatusChange, 
-// 包裹元素属性
-wrapperProps, wrapperClassName, 
-// 原生属性
-loading, decoding = "async", srcSet, sizes, crossOrigin, referrerPolicy, }, ref) {
-    // ============ 解析 placeholder 类型 ============
-    const isPlaceholderSrc = typeof placeholder === "string";
-    const placeholderSrc = isPlaceholderSrc ? placeholder : undefined;
-    const placeholderElement = !isPlaceholderSrc ? placeholder : undefined;
-    // ============ 智能默认 effect ============
-    // 只有当 placeholder 是字符串（URL）时才自动启用 blur
-    // ReactElement 类型不自动启用（因为没有图片可以模糊）
-    const effectiveEffect = effect !== null && effect !== void 0 ? effect : (isPlaceholderSrc ? "blur" : undefined);
-    // ============ 自动注入效果 CSS ============
-    // 使用 effect 属性时自动注入，确保 SSR 兼容
-    useEffect(() => {
-        if (effectiveEffect) {
-            injectEffectStyles();
-        }
-    }, [effectiveEffect]);
-    // ============ Context: 自动获取 Gallery 的 scrollPosition ============
-    const contextScrollPosition = useContext(ScrollPositionContext);
-    const effectiveScrollPosition = scrollPosition !== null && scrollPosition !== void 0 ? scrollPosition : contextScrollPosition;
-    // ============ 状态管理 ============
+// -------- XImage 扩展属性 --------
+placeholder, fallback, retryCount = 0, retryDelay = 1000, onStatusChange, wrapperProps, wrapperClassName, 
+// -------- next/image 常用属性（需要特殊处理） --------
+src, alt = "", fill, style, className, onLoad, onError, 
+// -------- next/image 其余属性（透传） --------
+...imageProps }, ref) {
+    // ========================================================================
+    // 解析 placeholder 类型
+    // ========================================================================
+    const placeholderSrc = typeof placeholder === "string" ? placeholder : undefined;
+    const placeholderElement = typeof placeholder !== "string" ? placeholder : undefined;
+    const hasPlaceholder = Boolean(placeholderSrc || placeholderElement);
+    // ========================================================================
+    // 状态管理
+    // ========================================================================
     const [currentSrc, setCurrentSrc] = useState(src);
     const [status, setStatus] = useState("idle");
     const [hasError, setHasError] = useState(false);
     const [retryAttempt, setRetryAttempt] = useState(0);
+    const [isLoaded, setIsLoaded] = useState(false);
+    // ========================================================================
     // Refs
+    // ========================================================================
     const wrapperRef = useRef(null);
+    const mainImageRef = useRef(null);
     const retryTimerRef = useRef(null);
-    const hasCalledOnVisible = useRef(false);
-    // 使用 ref 存储回调，避免 effect 依赖问题
-    const onStatusChangeRef = useRef(onStatusChange);
-    onStatusChangeRef.current = onStatusChange;
-    // ============ src 变化重置状态 ============
+    // 使用 ref 存储回调，避免 useCallback 依赖问题
+    const callbacksRef = useRef({ onStatusChange, onLoad, onError });
+    callbacksRef.current = { onStatusChange, onLoad, onError };
+    // ========================================================================
+    // 状态更新辅助函数
+    // ========================================================================
+    const updateStatus = useCallback((newStatus) => {
+        var _a, _b;
+        setStatus(newStatus);
+        (_b = (_a = callbacksRef.current).onStatusChange) === null || _b === void 0 ? void 0 : _b.call(_a, newStatus);
+    }, []);
+    // ========================================================================
+    // src 变化时重置状态
+    // ========================================================================
     useEffect(() => {
-        var _a;
         setCurrentSrc(src);
         setHasError(false);
         setRetryAttempt(0);
-        setStatus("idle");
-        (_a = onStatusChangeRef.current) === null || _a === void 0 ? void 0 : _a.call(onStatusChangeRef, "idle");
-        hasCalledOnVisible.current = false;
+        setIsLoaded(false);
+        updateStatus("loading");
         // 清理重试定时器
         if (retryTimerRef.current) {
             clearTimeout(retryTimerRef.current);
             retryTimerRef.current = null;
         }
-    }, [src]);
-    // 清理定时器
+    }, [src, updateStatus]);
+    // 组件卸载时清理定时器
     useEffect(() => {
         return () => {
             if (retryTimerRef.current) {
@@ -101,161 +111,146 @@ loading, decoding = "async", srcSet, sizes, crossOrigin, referrerPolicy, }, ref)
             }
         };
     }, []);
-    // ============ ref 转发：从 wrapper 中获取 img 元素 ============
+    // ========================================================================
+    // ref 转发：将内部 img 元素暴露给外部
+    // ========================================================================
     useEffect(() => {
         if (!ref || !wrapperRef.current)
             return;
-        const imgElement = wrapperRef.current.querySelector("img");
-        if (imgElement) {
+        // 获取主图 img 元素（双层渲染时取第二个，单层取第一个）
+        const imgs = wrapperRef.current.querySelectorAll("img");
+        const targetImg = imgs.length > 1 ? imgs[1] : imgs[0];
+        if (targetImg) {
             if (typeof ref === "function") {
-                ref(imgElement);
+                ref(targetImg);
             }
             else {
-                ref.current = imgElement;
+                ref.current = targetImg;
             }
         }
-        // 依赖 status 确保图片加载后能获取到正确的 img 元素
-    }, [ref, status]);
-    // ============ 状态更新辅助 ============
-    const updateStatus = useCallback((newStatus) => {
-        var _a;
-        setStatus(newStatus);
-        (_a = onStatusChangeRef.current) === null || _a === void 0 ? void 0 : _a.call(onStatusChangeRef, newStatus);
-    }, []);
-    // ============ 事件处理 ============
-    const handleLoad = useCallback((event) => {
+    }, [ref, isLoaded]); // isLoaded 变化时重新获取，确保 img 已渲染
+    // ========================================================================
+    // 事件处理
+    // ========================================================================
+    /**
+     * 主图加载成功
+     */
+    const handleLoad = useCallback((e) => {
+        var _a, _b;
+        setIsLoaded(true);
         updateStatus("loaded");
-        onLoad === null || onLoad === void 0 ? void 0 : onLoad(event);
-    }, [updateStatus, onLoad]);
-    const handleError = useCallback((event) => {
+        (_b = (_a = callbacksRef.current).onLoad) === null || _b === void 0 ? void 0 : _b.call(_a, e);
+    }, [updateStatus]);
+    /**
+     * 主图加载失败 - 处理重试和 fallback 逻辑
+     */
+    const handleError = useCallback((e) => {
         setRetryAttempt((currentRetry) => {
-            // 还有重试次数
+            // 还有重试次数，延迟后重试
             if (currentRetry < retryCount) {
-                updateStatus("loading");
                 retryTimerRef.current = setTimeout(() => {
-                    // 通过修改 src 触发重新加载（添加时间戳绕过缓存）
-                    const separator = src.includes("?") ? "&" : "?";
-                    setCurrentSrc(`${src}${separator}_retry=${Date.now()}`);
+                    // 添加时间戳绕过缓存
+                    const srcStr = typeof src === "string" ? src : "";
+                    const separator = srcStr.includes("?") ? "&" : "?";
+                    setCurrentSrc(`${srcStr}${separator}_retry=${Date.now()}`);
                 }, retryDelay);
                 return currentRetry + 1;
             }
-            // 重试耗尽，检查 fallback
+            // 重试耗尽，尝试 fallback
             setHasError((currentHasError) => {
+                var _a, _b;
                 if (fallback && !currentHasError) {
                     if (typeof fallback === "string") {
                         setCurrentSrc(fallback);
-                        updateStatus("loading");
+                        return true;
                     }
+                    // fallback 是 ReactNode，标记错误状态
+                    updateStatus("error");
                     return true;
                 }
-                // 最终失败
+                // 无 fallback 或已经在 fallback 状态，触发错误回调
                 updateStatus("error");
-                onError === null || onError === void 0 ? void 0 : onError(event);
+                (_b = (_a = callbacksRef.current).onError) === null || _b === void 0 ? void 0 : _b.call(_a, e);
                 return currentHasError;
             });
             return currentRetry;
         });
-    }, [retryCount, retryDelay, src, fallback, updateStatus, onError]);
-    // beforeLoad: 进入视口，开始加载前调用
-    const handleBeforeLoad = useCallback(() => {
-        if (!hasCalledOnVisible.current) {
-            hasCalledOnVisible.current = true;
-            updateStatus("loading");
-            onVisible === null || onVisible === void 0 ? void 0 : onVisible();
-        }
-    }, [updateStatus, onVisible]);
-    // ============ 计算样式 ============
-    const computedStyle = useMemo(() => {
-        const baseStyle = { ...style };
-        if (objectFit) {
-            baseStyle.objectFit = objectFit;
-        }
-        if (objectPosition) {
-            baseStyle.objectPosition = objectPosition;
-        }
-        // fill 模式：图片绝对定位填充
-        if (fill) {
-            baseStyle.position = "absolute";
-            baseStyle.width = "100%";
-            baseStyle.height = "100%";
-            baseStyle.inset = 0;
-            baseStyle.objectFit = objectFit || "cover";
-        }
-        return baseStyle;
-    }, [style, objectFit, objectPosition, fill]);
-    const wrapperStyle = useMemo(() => {
-        const base = { ...wrapperProps === null || wrapperProps === void 0 ? void 0 : wrapperProps.style };
-        // fill 模式下包裹元素需要绝对定位并填满父容器
-        if (fill) {
-            base.display = "block";
-            base.position = "absolute";
-            base.inset = 0;
-            base.width = "100%";
-            base.height = "100%";
-        }
-        return base;
-    }, [fill, wrapperProps === null || wrapperProps === void 0 ? void 0 : wrapperProps.style]);
-    // ============ 解析尺寸（简单计算，不需要 useMemo） ============
-    const parsedWidth = fill
-        ? undefined
-        : typeof width === "number"
-            ? width
-            : typeof width === "string"
-                ? parseInt(width, 10) || undefined
-                : undefined;
-    const parsedHeight = fill
-        ? undefined
-        : typeof height === "number"
-            ? height
-            : typeof height === "string"
-                ? parseInt(height, 10) || undefined
-                : undefined;
-    // ============ 合并 wrapperProps（处理 ref 合并） ============
-    const mergedWrapperProps = useMemo(() => {
-        // wrapperProps 可能包含 ref（通过类型扩展）
+    }, [retryCount, retryDelay, src, fallback, updateStatus]);
+    // ========================================================================
+    // 合并 wrapperProps 的 ref
+    // ========================================================================
+    const mergedWrapperRef = useCallback((node) => {
+        wrapperRef.current = node;
+        // 调用用户传入的 ref
         const userRef = wrapperProps === null || wrapperProps === void 0 ? void 0 : wrapperProps.ref;
-        // 合并 ref
-        const combinedRef = (node) => {
-            // 设置内部 ref
-            wrapperRef.current = node;
-            // 调用用户的 ref
-            if (userRef) {
-                if (typeof userRef === "function") {
-                    userRef(node);
-                }
-                else {
-                    userRef.current = node;
-                }
+        if (userRef) {
+            if (typeof userRef === "function") {
+                userRef(node);
             }
-        };
-        return {
-            ...wrapperProps,
-            ref: combinedRef,
-            style: wrapperStyle,
-            className: wrapperClassName,
-        };
-    }, [wrapperProps, wrapperStyle, wrapperClassName]);
-    // ============ 渲染 fallback ReactNode ============
+            else {
+                userRef.current = node;
+            }
+        }
+    }, [wrapperProps]);
+    // ========================================================================
+    // 计算样式（使用 useMemo 避免重复创建对象）
+    // ========================================================================
+    /** 容器样式 */
+    const wrapperStyle = useMemo(() => ({
+        position: "relative",
+        display: "inline-block",
+        overflow: "hidden",
+        ...wrapperProps === null || wrapperProps === void 0 ? void 0 : wrapperProps.style,
+    }), [wrapperProps === null || wrapperProps === void 0 ? void 0 : wrapperProps.style]);
+    /** 占位图样式（带 blur 效果） */
+    const placeholderStyle = useMemo(() => ({
+        ...style,
+        position: "absolute",
+        inset: 0,
+        width: "100%",
+        height: "100%",
+        transition: `opacity ${TRANSITION_DURATION} ease-in-out, filter ${TRANSITION_DURATION} ease-in-out`,
+        opacity: isLoaded ? 0 : 1,
+        filter: isLoaded ? "blur(0px)" : `blur(${PLACEHOLDER_BLUR})`,
+        transform: `scale(${PLACEHOLDER_SCALE})`,
+        pointerEvents: "none", // 防止占位图拦截事件
+    }), [style, isLoaded]);
+    /** 主图样式（加载完成后显示） */
+    const mainImageStyle = useMemo(() => ({
+        ...style,
+        position: "absolute",
+        inset: 0,
+        width: "100%",
+        height: "100%",
+        transition: `opacity ${TRANSITION_DURATION} ease-in-out`,
+        opacity: isLoaded ? 1 : 0,
+    }), [style, isLoaded]);
+    // ========================================================================
+    // 渲染
+    // ========================================================================
+    // 错误状态 + ReactNode fallback
     if (hasError && fallback && typeof fallback !== "string") {
-        return (React.createElement("div", { ref: ref, className: className, style: {
-                width: parsedWidth,
-                height: parsedHeight,
-                position: fill ? "absolute" : undefined,
-                inset: fill ? 0 : undefined,
-                ...style,
-            } }, fallback));
+        return (React.createElement("div", { ref: ref, className: wrapperClassName || className, style: { ...wrapperStyle, ...style }, ...wrapperProps }, fallback));
+    }
+    // 有 placeholder（URL 或 ReactElement）：双层渲染
+    if (hasPlaceholder) {
+        return (React.createElement("div", { ...wrapperProps, ref: mergedWrapperRef, className: wrapperClassName, style: wrapperStyle },
+            placeholderSrc ? (
+            // URL 占位图：使用 next/image，priority 立即加载
+            React.createElement(Image, { src: placeholderSrc, alt: "" // 占位图不需要 alt（屏幕阅读器跳过）
+                , fill: true, priority: true, unoptimized: true, className: className, style: placeholderStyle, sizes: imageProps.sizes })) : (
+            // ReactElement 占位组件（如 Skeleton）
+            React.createElement("div", { style: {
+                    position: "absolute",
+                    inset: 0,
+                    transition: `opacity ${TRANSITION_DURATION} ease-in-out`,
+                    opacity: isLoaded ? 0 : 1,
+                    pointerEvents: "none",
+                } }, placeholderElement)),
+            React.createElement(Image, { ...imageProps, ref: mainImageRef, src: currentSrc, alt: alt, fill: true, className: className, style: mainImageStyle, onLoad: handleLoad, onError: handleError })));
     }
-    // ============ 统一使用 LazyLoadImage ============
-    return (React.createElement(LazyLoadImage, { src: currentSrc, alt: alt, width: parsedWidth, height: parsedHeight, className: className, style: computedStyle, 
-        // 懒加载配置 - lazy=false 时禁用懒加载特性
-        threshold: lazy ? threshold : 0, effect: lazy ? effectiveEffect : undefined, placeholderSrc: lazy ? placeholderSrc : undefined, placeholder: lazy ? placeholderElement : undefined, useIntersectionObserver: lazy ? useIntersectionObserver : false, visibleByDefault: !lazy || visibleByDefault, delayMethod: delayMethod, delayTime: delayTime, 
-        // 性能优化
-        scrollPosition: lazy ? effectiveScrollPosition : undefined, 
-        // 事件
-        beforeLoad: lazy ? handleBeforeLoad : undefined, onLoad: handleLoad, onError: handleError, 
-        // 包裹元素
-        wrapperProps: mergedWrapperProps, 
-        // 原生属性
-        loading: lazy ? loading : "eager", decoding: decoding, srcSet: srcSet, sizes: sizes, crossOrigin: crossOrigin, referrerPolicy: referrerPolicy }));
+    // 无 placeholder：单层渲染
+    return (React.createElement("div", { ...wrapperProps, ref: mergedWrapperRef, className: wrapperClassName, style: wrapperStyle },
+        React.createElement(Image, { ...imageProps, ref: mainImageRef, src: currentSrc, alt: alt, fill: fill, className: className, style: style, onLoad: handleLoad, onError: handleError })));
 }));
 export default XImage;

package/dist/layout/image/XImage.types.d.ts

@@ -1,130 +1,110 @@
-import type { CSSProperties, ReactElement, ReactNode, SyntheticEvent } from "react";
-/**
- * 懒加载效果类型
- * - blur: 模糊渐变效果
- * - opacity: 透明度渐变效果
- * - black-and-white: 黑白到彩色渐变效果
- */
-export type XImageEffect = "blur" | "opacity" | "black-and-white";
-/**
- * 节流/防抖方法类型
- */
-export type DelayMethod = "throttle" | "debounce";
+import type { ImageProps } from "next/image";
+import type { ReactElement, ReactNode } from "react";
 /**
  * 图片加载状态
+ *
+ * - `idle`: 初始状态（未开始加载）
+ * - `loading`: 加载中
+ * - `loaded`: 加载成功
+ * - `error`: 加载失败（重试耗尽且无 fallback）
  */
 export type XImageStatus = "idle" | "loading" | "loaded" | "error";
-/**
- * 滚动位置类型 (用于 trackWindowScroll HOC)
- */
-export interface ScrollPosition {
-    x: number;
-    y: number;
-}
 /**
  * XImage 组件 Props
+ *
+ * 继承 next/image 的所有属性，扩展双层渲染和错误处理能力。
+ *
+ * ## 性能建议
+ *
+ * 1. **placeholder 使用小尺寸缩略图**：推荐 20-40px 宽度，体积 < 1KB
+ *    ```tsx
+ *    <XImage
+ *      src="/photo.jpg?w=800"
+ *      placeholder="/photo.jpg?w=20"
+ *    />
+ *    ```
+ *
+ * 2. **首屏图片使用 priority**：跳过懒加载
+ *    ```tsx
+ *    <XImage src="/hero.jpg" priority />
+ *    ```
+ *
+ * 3. **设置正确的 sizes**：避免加载过大图片
+ *    ```tsx
+ *    <XImage
+ *      src="/photo.jpg"
+ *      sizes="(max-width: 768px) 100vw, 50vw"
+ *    />
+ *    ```
  */
-export interface XImageProps {
-    /** 图片源地址 */
-    src: string;
-    /** 图片描述文本 */
-    alt?: string;
-    /** 图片宽度 */
-    width?: number | string;
-    /** 图片高度 */
-    height?: number | string;
-    /** CSS 类名 */
-    className?: string;
-    /** 内联样式 */
-    style?: CSSProperties;
-    /** 图片填充方式 */
-    objectFit?: CSSProperties["objectFit"];
-    /** 图片对齐方式 */
-    objectPosition?: CSSProperties["objectPosition"];
-    /** 是否使用 fill 模式（占满父容器） */
-    fill?: boolean;
-    /** 是否启用懒加载，默认 true */
-    lazy?: boolean;
-    /** 进入视口前多少像素开始加载，默认 100 */
-    threshold?: number;
-    /** 加载效果类型（如果提供了 placeholder URL 但未指定 effect，默认为 'blur'） */
-    effect?: XImageEffect;
+export interface XImageProps extends Omit<ImageProps, "placeholder" | "ref"> {
     /**
-     * 占位内容
-     * - string: 占位图片 URL（自动启用 blur 效果）
-     * - ReactElement: 自定义占位组件（如 Skeleton，需手动指定 effect）
+     * 占位内容（用于双层渲染 + blur 过渡）
+     *
+     * - `string`: 占位图片 URL（推荐使用小尺寸缩略图）
+     * - `ReactElement`: 自定义占位组件（如 Skeleton）
+     *
+     * @example
+     * ```tsx
+     * // URL 占位图（推荐）
+     * <XImage src="/photo.jpg" placeholder="/photo-tiny.jpg" />
+     *
+     * // 自定义 Skeleton
+     * <XImage src="/photo.jpg" placeholder={<Skeleton />} />
+     * ```
      */
     placeholder?: string | ReactElement | null;
-    /** 是否使用 IntersectionObserver，默认 true */
-    useIntersectionObserver?: boolean;
-    /** 滚动/resize 事件的节流方法 */
-    delayMethod?: DelayMethod;
-    /** 节流延迟时间（毫秒） */
-    delayTime?: number;
     /**
      * 加载失败时显示的备用内容
-     * - string: 备用图片 URL
-     * - ReactNode: 自定义错误展示组件
+     *
+     * - `string`: 备用图片 URL（会尝试加载）
+     * - `ReactNode`: 自定义错误展示组件
+     *
+     * @example
+     * ```tsx
+     * // 备用图片
+     * <XImage src="/photo.jpg" fallback="/fallback.jpg" />
+     *
+     * // 自定义错误组件
+     * <XImage src="/photo.jpg" fallback={<ErrorPlaceholder />} />
+     * ```
      */
     fallback?: string | ReactNode;
-    /** 加载失败后的重试次数，默认 0 */
+    /**
+     * 加载失败后的重试次数
+     *
+     * @default 0
+     */
     retryCount?: number;
-    /** 重试间隔（毫秒），默认 1000 */
-    retryDelay?: number;
     /**
-     * 滚动位置（来自 trackWindowScroll HOC）
-     * 当父组件使用 withScrollTracking 包裹时自动传入
+     * 重试间隔（毫秒）
+     *
+     * @default 1000
      */
-    scrollPosition?: ScrollPosition;
+    retryDelay?: number;
     /**
-     * 设为 true 则图片立即显示（不触发懒加载）
-     * 适用于已在浏览器缓存中的图片
+     * 加载状态变化回调
+     *
+     * @example
+     * ```tsx
+     * <XImage
+     *   src="/photo.jpg"
+     *   onStatusChange={(status) => console.log('Status:', status)}
+     * />
+     * ```
      */
-    visibleByDefault?: boolean;
-    /** 图片加载完成回调 */
-    onLoad?: (event: SyntheticEvent<HTMLImageElement>) => void;
-    /** 图片加载失败回调 */
-    onError?: (event: SyntheticEvent<HTMLImageElement>) => void;
-    /** 图片进入视口时回调 */
-    onVisible?: () => void;
-    /** 加载状态变化回调 */
     onStatusChange?: (status: XImageStatus) => void;
-    /** 传递给包裹 span 元素的属性 */
-    wrapperProps?: React.HTMLAttributes<HTMLSpanElement>;
-    /** 包裹元素的类名 */
+    /**
+     * 传递给包裹 div 元素的属性
+     *
+     * 用于自定义容器的事件处理、数据属性等
+     */
+    wrapperProps?: React.HTMLAttributes<HTMLDivElement>;
+    /**
+     * 包裹元素的类名
+     *
+     * 与 className 区分：className 应用于 img，wrapperClassName 应用于外层 div
+     */
     wrapperClassName?: string;
-    /** 图片加载优先级 */
-    loading?: "lazy" | "eager";
-    /** 解码方式 */
-    decoding?: "async" | "auto" | "sync";
-    /** 响应式图片源集 */
-    srcSet?: string;
-    /** 响应式尺寸 */
-    sizes?: string;
-    /** 跨域设置 */
-    crossOrigin?: "anonymous" | "use-credentials" | "";
-    /** referrer 策略 */
-    referrerPolicy?: React.HTMLAttributeReferrerPolicy;
-}
-/**
- * XImageGallery 组件 Props
- * 用于包裹多个 XImage 实现统一的滚动监听优化
- */
-export interface XImageGalleryProps {
-    children: ReactNode;
-    /** 自定义容器类名 */
-    className?: string;
-    /** 自定义容器样式 */
-    style?: CSSProperties;
-    /** 节流方法: throttle 或 debounce */
-    delayMethod?: DelayMethod;
-    /** 节流/防抖延迟时间（毫秒） */
-    delayTime?: number;
-}
-/**
- * withScrollTracking HOC 注入的 Props
- */
-export interface WithScrollTrackingProps {
-    scrollPosition: ScrollPosition;
 }
 //# sourceMappingURL=XImage.types.d.ts.map

package/dist/layout/image/XImage.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"XImage.types.d.ts","sourceRoot":"","sources":["../../../src/layout/image/XImage.types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"XImage.types.d.ts","sourceRoot":"","sources":["../../../src/layout/image/XImage.types.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAErD;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,WAAW,WAAY,SAAQ,IAAI,CAAC,UAAU,EAAE,aAAa,GAAG,KAAK,CAAC;IACxE;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAAC;IAE3C;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAE9B;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;;;;;;;OAUG;IACH,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;IAEhD;;;;OAIG;IACH,YAAY,CAAC,EAAE,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC,CAAC;IAEpD;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC7B"}

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

@@ -1,12 +1,3 @@
 export { XImage, default as XImageDefault } from "./XImage";
-export { XImageGallery, withScrollTracking, useScrollPosition, ScrollPositionContext, } from "./XImageGallery";
-export type { XImageProps, XImageEffect, XImageStatus, XImageGalleryProps, ScrollPosition, WithScrollTrackingProps, DelayMethod, } from "./XImage.types";
-/**
- * XImage 效果 CSS 已内置，无需手动导入！
- *
- * 直接使用 effect 属性即可：
- * <XImage src="..." effect="blur" />
- * <XImage src="..." effect="opacity" />
- * <XImage src="..." effect="black-and-white" />
- */
+export type { XImageProps, XImageStatus } from "./XImage.types";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/layout/image/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,MAAM,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,UAAU,CAAC;AAC5D,OAAO,EACH,aAAa,EACb,kBAAkB,EAClB,iBAAiB,EACjB,qBAAqB,GACxB,MAAM,iBAAiB,CAAC;AAGzB,YAAY,EACR,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,kBAAkB,EAClB,cAAc,EACd,uBAAuB,EACvB,WAAW,GACd,MAAM,gBAAgB,CAAC;AAGxB;;;;;;;GAOG"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/layout/image/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,MAAM,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,UAAU,CAAC;AAG5D,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/layout/image/index.js

@@ -1,4 +1,3 @@
 "use client";
 // ============ 组件导出 ============
 export { XImage, default as XImageDefault } from "./XImage";
-export { XImageGallery, withScrollTracking, useScrollPosition, ScrollPositionContext, } from "./XImageGallery";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xxf_react",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "private": false,
   "type": "module",
   "main": "dist/index.js",
@@ -70,11 +70,11 @@
     "build": "tsc"
   },
   "peerDependencies": {
-    "react": ">=18"
+    "react": ">=18",
+    "next": ">=13"
   },
   "dependencies": {
     "@microsoft/fetch-event-source": "^2.0.1",
-    "react-lazy-load-image-component": "^1.6.2",
     "@use-gesture/react": "^10.3.1",
     "bowser": "^2.14.1",
     "broadcast-channel": "^7.3.0",
@@ -97,7 +97,6 @@
   "devDependencies": {
     "@types/node": "^25.3.0",
     "@types/react": "^19.2.14",
-    "@types/react-lazy-load-image-component": "^1.6.4",
     "next": "^16.1.6",
     "typescript": "^5.9.3"
   }

package/dist/layout/image/XImage.effects.d.ts

@@ -1,16 +0,0 @@
-/**
- * XImage 效果样式管理
- * 自动注入 CSS 到 document.head，用户无需手动导入
- */
-/**
- * 注入效果 CSS 到 document.head
- * - 仅在浏览器环境执行
- * - 只执行一次（多个 XImage 实例共享）
- * - SSR 安全
- */
-export declare function injectEffectStyles(): void;
-/**
- * 移除已注入的效果 CSS（用于测试或清理）
- */
-export declare function removeEffectStyles(): void;
-//# sourceMappingURL=XImage.effects.d.ts.map

package/dist/layout/image/XImage.effects.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"XImage.effects.d.ts","sourceRoot":"","sources":["../../../src/layout/image/XImage.effects.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA8CH;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAczC;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAQzC"}

package/dist/layout/image/XImage.effects.js

@@ -1,77 +0,0 @@
-/**
- * XImage 效果样式管理
- * 自动注入 CSS 到 document.head，用户无需手动导入
- */
-// ============ 效果 CSS 定义 ============
-const EFFECT_STYLES = `
-.lazy-load-image-background.blur {
-  filter: blur(15px);
-}
-.lazy-load-image-background.blur.lazy-load-image-loaded {
-  filter: blur(0);
-  transition: filter .3s;
-}
-.lazy-load-image-background.blur > img {
-  opacity: 0;
-}
-.lazy-load-image-background.blur.lazy-load-image-loaded > img {
-  opacity: 1;
-  transition: opacity .3s;
-}
-.lazy-load-image-background.opacity {
-  opacity: 0;
-}
-.lazy-load-image-background.opacity.lazy-load-image-loaded {
-  opacity: 1;
-  transition: opacity .3s;
-}
-.lazy-load-image-background.black-and-white {
-  filter: grayscale(1);
-}
-.lazy-load-image-background.black-and-white.lazy-load-image-loaded {
-  filter: grayscale(0);
-  transition: filter .3s;
-}
-.lazy-load-image-background.black-and-white > img {
-  opacity: 0;
-}
-.lazy-load-image-background.black-and-white.lazy-load-image-loaded > img {
-  opacity: 1;
-  transition: opacity .3s;
-}
-`;
-const STYLE_ID = "ximage-effect-styles";
-// CSS 注入标记，确保只注入一次
-let stylesInjected = false;
-/**
- * 注入效果 CSS 到 document.head
- * - 仅在浏览器环境执行
- * - 只执行一次（多个 XImage 实例共享）
- * - SSR 安全
- */
-export function injectEffectStyles() {
-    if (stylesInjected || typeof document === "undefined")
-        return;
-    // 双重检查：防止多实例并发注入
-    if (document.getElementById(STYLE_ID)) {
-        stylesInjected = true;
-        return;
-    }
-    const styleElement = document.createElement("style");
-    styleElement.id = STYLE_ID;
-    styleElement.textContent = EFFECT_STYLES;
-    document.head.appendChild(styleElement);
-    stylesInjected = true;
-}
-/**
- * 移除已注入的效果 CSS（用于测试或清理）
- */
-export function removeEffectStyles() {
-    if (typeof document === "undefined")
-        return;
-    const styleElement = document.getElementById(STYLE_ID);
-    if (styleElement) {
-        styleElement.remove();
-        stylesInjected = false;
-    }
-}

package/dist/layout/image/XImageGallery.d.ts

@@ -1,76 +0,0 @@
-import React, { ComponentType } from "react";
-import type { XImageGalleryProps, ScrollPosition, WithScrollTrackingProps } from "./XImage.types";
-/**
- * ScrollPosition Context
- * 用于在组件树中共享滚动位置，支持深层嵌套的 XImage 自动获取
- */
-export declare const ScrollPositionContext: React.Context<ScrollPosition | undefined>;
-/**
- * Hook: 获取当前的滚动位置
- * 在 XImageGallery 内部的任意深度使用
- */
-export declare function useScrollPosition(): ScrollPosition | undefined;
-/**
- * XImageGallery - 图片画廊/列表性能优化组件
- *
- * 当页面中有大量图片需要懒加载时，使用此组件包裹可以：
- * - 统一管理滚动监听，避免每个图片单独监听 scroll/resize 事件
- * - 通过 trackWindowScroll HOC 实现性能优化
- * - 通过 Context 自动向任意深度的子 XImage 组件传递 scrollPosition
- *
- * @example
- * ```tsx
- * // 基础用法 - 包裹多个 XImage（支持任意嵌套深度）
- * <XImageGallery>
- *   <div className="grid">
- *     {images.map(img => (
- *       <div key={img.id} className="card">
- *         <XImage src={img.url} effect="blur" />
- *       </div>
- *     ))}
- *   </div>
- * </XImageGallery>
- *
- * // 自定义节流配置
- * <XImageGallery delayMethod="debounce" delayTime={200}>
- *   {images.map(img => (
- *     <XImage key={img.id} src={img.url} />
- *   ))}
- * </XImageGallery>
- * ```
- *
- * @note 注意事项：
- * - 不要在 XImageGallery 内部嵌套另一个 XImageGallery
- * - 内部的 XImage 会自动通过 Context 获取 scrollPosition，无需手动传递
- */
-export declare const XImageGallery: React.NamedExoticComponent<XImageGalleryProps & React.RefAttributes<HTMLDivElement>>;
-/**
- * HOC: 为任意组件添加滚动位置追踪能力
- *
- * 适用于需要自定义容器但又想使用 trackWindowScroll 优化的场景
- *
- * @example
- * ```tsx
- * // 自定义图片网格组件
- * const ImageGrid = ({ images, scrollPosition }) => (
- *   <div className="grid grid-cols-3">
- *     {images.map(img => (
- *       <XImage
- *         key={img.id}
- *         src={img.url}
- *         scrollPosition={scrollPosition}
- *       />
- *     ))}
- *   </div>
- * );
- *
- * // 使用 HOC 包裹
- * const OptimizedImageGrid = withScrollTracking(ImageGrid);
- *
- * // 使用
- * <OptimizedImageGrid images={images} />
- * ```
- */
-export declare function withScrollTracking<P extends object>(WrappedComponent: ComponentType<P & WithScrollTrackingProps>): ComponentType<Omit<P, "scrollPosition">>;
-export default XImageGallery;
-//# sourceMappingURL=XImageGallery.d.ts.map

package/dist/layout/image/XImageGallery.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"XImageGallery.d.ts","sourceRoot":"","sources":["../../../src/layout/image/XImageGallery.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,EAAQ,aAAa,EAAyC,MAAM,OAAO,CAAC;AAE1F,OAAO,KAAK,EACR,kBAAkB,EAClB,cAAc,EACd,uBAAuB,EAC1B,MAAM,gBAAgB,CAAC;AAExB;;;GAGG;AACH,eAAO,MAAM,qBAAqB,2CAAuD,CAAC;AAE1F;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,GAAG,SAAS,CAE9D;AAgCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,aAAa,sFAiBzB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,EAC/C,gBAAgB,EAAE,aAAa,CAAC,CAAC,GAAG,uBAAuB,CAAC,GAC7D,aAAa,CAAC,IAAI,CAAC,CAAC,EAAE,gBAAgB,CAAC,CAAC,CAW1C;AAED,eAAe,aAAa,CAAC"}

package/dist/layout/image/XImageGallery.js

@@ -1,94 +0,0 @@
-"use client";
-import React, { memo, forwardRef, createContext, useContext } from "react";
-import { trackWindowScroll } from "react-lazy-load-image-component";
-/**
- * ScrollPosition Context
- * 用于在组件树中共享滚动位置，支持深层嵌套的 XImage 自动获取
- */
-export const ScrollPositionContext = createContext(undefined);
-/**
- * Hook: 获取当前的滚动位置
- * 在 XImageGallery 内部的任意深度使用
- */
-export function useScrollPosition() {
-    return useContext(ScrollPositionContext);
-}
-const InternalGallery = memo(forwardRef(function InternalGallery({ children, className, style, scrollPosition }, ref) {
-    return (React.createElement(ScrollPositionContext.Provider, { value: scrollPosition },
-        React.createElement("div", { ref: ref, className: className, style: style }, children)));
-}));
-/**
- * 使用 trackWindowScroll HOC 包裹的 Gallery
- */
-const TrackedGallery = trackWindowScroll(InternalGallery);
-/**
- * XImageGallery - 图片画廊/列表性能优化组件
- *
- * 当页面中有大量图片需要懒加载时，使用此组件包裹可以：
- * - 统一管理滚动监听，避免每个图片单独监听 scroll/resize 事件
- * - 通过 trackWindowScroll HOC 实现性能优化
- * - 通过 Context 自动向任意深度的子 XImage 组件传递 scrollPosition
- *
- * @example
- * ```tsx
- * // 基础用法 - 包裹多个 XImage（支持任意嵌套深度）
- * <XImageGallery>
- *   <div className="grid">
- *     {images.map(img => (
- *       <div key={img.id} className="card">
- *         <XImage src={img.url} effect="blur" />
- *       </div>
- *     ))}
- *   </div>
- * </XImageGallery>
- *
- * // 自定义节流配置
- * <XImageGallery delayMethod="debounce" delayTime={200}>
- *   {images.map(img => (
- *     <XImage key={img.id} src={img.url} />
- *   ))}
- * </XImageGallery>
- * ```
- *
- * @note 注意事项：
- * - 不要在 XImageGallery 内部嵌套另一个 XImageGallery
- * - 内部的 XImage 会自动通过 Context 获取 scrollPosition，无需手动传递
- */
-export const XImageGallery = memo(forwardRef(function XImageGallery({ children, className, style, delayMethod, delayTime }, ref) {
-    return (React.createElement(TrackedGallery, { ref: ref, className: className, style: style, delayMethod: delayMethod, delayTime: delayTime }, children));
-}));
-/**
- * HOC: 为任意组件添加滚动位置追踪能力
- *
- * 适用于需要自定义容器但又想使用 trackWindowScroll 优化的场景
- *
- * @example
- * ```tsx
- * // 自定义图片网格组件
- * const ImageGrid = ({ images, scrollPosition }) => (
- *   <div className="grid grid-cols-3">
- *     {images.map(img => (
- *       <XImage
- *         key={img.id}
- *         src={img.url}
- *         scrollPosition={scrollPosition}
- *       />
- *     ))}
- *   </div>
- * );
- *
- * // 使用 HOC 包裹
- * const OptimizedImageGrid = withScrollTracking(ImageGrid);
- *
- * // 使用
- * <OptimizedImageGrid images={images} />
- * ```
- */
-export function withScrollTracking(WrappedComponent) {
-    const WithScrollTracking = trackWindowScroll(WrappedComponent);
-    // 设置 displayName 便于调试
-    const wrappedName = WrappedComponent.displayName || WrappedComponent.name || "Component";
-    WithScrollTracking.displayName = `withScrollTracking(${wrappedName})`;
-    return WithScrollTracking;
-}
-export default XImageGallery;