xxf_react 0.8.2 → 0.8.3

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

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

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

@@ -0,0 +1,16 @@
+/**
+ * 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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,77 @@
+/**
+ * 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/XImage.js

@@ -1,109 +1,99 @@
 "use client";
-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;
-// ============================================================================
-// 组件实现
-// ============================================================================
+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";
 /**
  * 生产级图片组件
  *
- * 基于 next/image 实现，支持：
- * - 双层渲染：placeholder 先加载，主图加载完成后 blur 过渡
- * - 自动图片优化（Next.js 内置）
+ * 基于 react-lazy-load-image-component 实现，支持：
+ * - 懒加载 + IntersectionObserver
+ * - 多种加载效果 (blur/opacity/black-and-white) - CSS 已内置，无需导入
  * - 错误处理 + 自动重试
  * - fallback 备用图/组件
+ * - 性能优化 (配合 XImageGallery 使用 trackWindowScroll)
  *
  * @example
  * ```tsx
  * // 基础用法
  * <XImage src="/photo.jpg" alt="Photo" width={400} height={300} />
  *
- * // 带 placeholder 模糊过渡（推荐使用小尺寸缩略图，如 w=20）
- * <XImage
- *   src="/photo.jpg?w=800"
- *   placeholder="/photo.jpg?w=20"
- *   width={400}
- *   height={300}
- * />
+ * // 带模糊效果（提供 placeholder URL 自动启用 blur）
+ * <XImage src="/photo.jpg" placeholder="/photo-tiny.jpg" />
+ *
+ * // 自定义占位组件
+ * <XImage src="/photo.jpg" placeholder={<Skeleton />} effect="opacity" />
  *
- * // 带错误处理和重试
+ * // 带错误处理
  * <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({ 
-// -------- 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);
-    // ========================================================================
-    // 状态管理
-    // ========================================================================
+// 基础属性
+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;
+    // ============ 状态管理 ============
     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);
-    // 使用 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 变化时重置状态
-    // ========================================================================
+    const hasCalledOnVisible = useRef(false);
+    // 使用 ref 存储回调，避免 effect 依赖问题
+    const onStatusChangeRef = useRef(onStatusChange);
+    onStatusChangeRef.current = onStatusChange;
+    // ============ src 变化重置状态 ============
     useEffect(() => {
+        var _a;
         setCurrentSrc(src);
         setHasError(false);
         setRetryAttempt(0);
-        setIsLoaded(false);
-        updateStatus("loading");
+        setStatus("idle");
+        (_a = onStatusChangeRef.current) === null || _a === void 0 ? void 0 : _a.call(onStatusChangeRef, "idle");
+        hasCalledOnVisible.current = false;
         // 清理重试定时器
         if (retryTimerRef.current) {
             clearTimeout(retryTimerRef.current);
             retryTimerRef.current = null;
         }
-    }, [src, updateStatus]);
-    // 组件卸载时清理定时器
+    }, [src]);
+    // 清理定时器
     useEffect(() => {
         return () => {
             if (retryTimerRef.current) {
@@ -111,146 +101,161 @@ src, alt = "", fill, style, className, onLoad, onError,
             }
         };
     }, []);
-    // ========================================================================
-    // ref 转发：将内部 img 元素暴露给外部
-    // ========================================================================
+    // ============ ref 转发：从 wrapper 中获取 img 元素 ============
     useEffect(() => {
         if (!ref || !wrapperRef.current)
             return;
-        // 获取主图 img 元素（双层渲染时取第二个，单层取第一个）
-        const imgs = wrapperRef.current.querySelectorAll("img");
-        const targetImg = imgs.length > 1 ? imgs[1] : imgs[0];
-        if (targetImg) {
+        const imgElement = wrapperRef.current.querySelector("img");
+        if (imgElement) {
             if (typeof ref === "function") {
-                ref(targetImg);
+                ref(imgElement);
             }
             else {
-                ref.current = targetImg;
+                ref.current = imgElement;
             }
         }
-    }, [ref, isLoaded]); // isLoaded 变化时重新获取，确保 img 已渲染
-    // ========================================================================
-    // 事件处理
-    // ========================================================================
-    /**
-     * 主图加载成功
-     */
-    const handleLoad = useCallback((e) => {
-        var _a, _b;
-        setIsLoaded(true);
+        // 依赖 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) => {
         updateStatus("loaded");
-        (_b = (_a = callbacksRef.current).onLoad) === null || _b === void 0 ? void 0 : _b.call(_a, e);
-    }, [updateStatus]);
-    /**
-     * 主图加载失败 - 处理重试和 fallback 逻辑
-     */
-    const handleError = useCallback((e) => {
+        onLoad === null || onLoad === void 0 ? void 0 : onLoad(event);
+    }, [updateStatus, onLoad]);
+    const handleError = useCallback((event) => {
         setRetryAttempt((currentRetry) => {
-            // 还有重试次数，延迟后重试
+            // 还有重试次数
             if (currentRetry < retryCount) {
+                updateStatus("loading");
                 retryTimerRef.current = setTimeout(() => {
-                    // 添加时间戳绕过缓存
-                    const srcStr = typeof src === "string" ? src : "";
-                    const separator = srcStr.includes("?") ? "&" : "?";
-                    setCurrentSrc(`${srcStr}${separator}_retry=${Date.now()}`);
+                    // 通过修改 src 触发重新加载（添加时间戳绕过缓存）
+                    const separator = src.includes("?") ? "&" : "?";
+                    setCurrentSrc(`${src}${separator}_retry=${Date.now()}`);
                 }, retryDelay);
                 return currentRetry + 1;
             }
-            // 重试耗尽，尝试 fallback
+            // 重试耗尽，检查 fallback
             setHasError((currentHasError) => {
-                var _a, _b;
                 if (fallback && !currentHasError) {
                     if (typeof fallback === "string") {
                         setCurrentSrc(fallback);
-                        return true;
+                        updateStatus("loading");
                     }
-                    // fallback 是 ReactNode，标记错误状态
-                    updateStatus("error");
                     return true;
                 }
-                // 无 fallback 或已经在 fallback 状态，触发错误回调
+                // 最终失败
                 updateStatus("error");
-                (_b = (_a = callbacksRef.current).onError) === null || _b === void 0 ? void 0 : _b.call(_a, e);
+                onError === null || onError === void 0 ? void 0 : onError(event);
                 return currentHasError;
             });
             return currentRetry;
         });
-    }, [retryCount, retryDelay, src, fallback, updateStatus]);
-    // ========================================================================
-    // 合并 wrapperProps 的 ref
-    // ========================================================================
-    const mergedWrapperRef = useCallback((node) => {
-        wrapperRef.current = node;
-        // 调用用户传入的 ref
+    }, [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（通过类型扩展）
         const userRef = wrapperProps === null || wrapperProps === void 0 ? void 0 : wrapperProps.ref;
-        if (userRef) {
-            if (typeof userRef === "function") {
-                userRef(node);
-            }
-            else {
-                userRef.current = node;
+        // 合并 ref
+        const combinedRef = (node) => {
+            // 设置内部 ref
+            wrapperRef.current = node;
+            // 调用用户的 ref
+            if (userRef) {
+                if (typeof userRef === "function") {
+                    userRef(node);
+                }
+                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
+        };
+        return {
+            ...wrapperProps,
+            ref: combinedRef,
+            style: wrapperStyle,
+            className: wrapperClassName,
+        };
+    }, [wrapperProps, wrapperStyle, wrapperClassName]);
+    // ============ 渲染 fallback ReactNode ============
     if (hasError && fallback && typeof fallback !== "string") {
-        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 })));
+        return (React.createElement("div", { ref: ref, className: className, style: {
+                width: parsedWidth,
+                height: parsedHeight,
+                position: fill ? "absolute" : undefined,
+                inset: fill ? 0 : undefined,
+                ...style,
+            } }, fallback));
     }
-    // 无 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 })));
+    // ============ 统一使用 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 }));
 }));
 export default XImage;

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

@@ -1,110 +1,130 @@
-import type { ImageProps } from "next/image";
-import type { ReactElement, ReactNode } from "react";
+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";
 /**
  * 图片加载状态
- *
- * - `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 extends Omit<ImageProps, "placeholder" | "ref"> {
+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;
     /**
-     * 占位内容（用于双层渲染 + blur 过渡）
-     *
-     * - `string`: 占位图片 URL（推荐使用小尺寸缩略图）
-     * - `ReactElement`: 自定义占位组件（如 Skeleton）
-     *
-     * @example
-     * ```tsx
-     * // URL 占位图（推荐）
-     * <XImage src="/photo.jpg" placeholder="/photo-tiny.jpg" />
-     *
-     * // 自定义 Skeleton
-     * <XImage src="/photo.jpg" placeholder={<Skeleton />} />
-     * ```
+     * 占位内容
+     * - string: 占位图片 URL（自动启用 blur 效果）
+     * - ReactElement: 自定义占位组件（如 Skeleton，需手动指定 effect）
      */
     placeholder?: string | ReactElement | null;
+    /** 是否使用 IntersectionObserver，默认 true */
+    useIntersectionObserver?: boolean;
+    /** 滚动/resize 事件的节流方法 */
+    delayMethod?: DelayMethod;
+    /** 节流延迟时间（毫秒） */
+    delayTime?: number;
     /**
      * 加载失败时显示的备用内容
-     *
-     * - `string`: 备用图片 URL（会尝试加载）
-     * - `ReactNode`: 自定义错误展示组件
-     *
-     * @example
-     * ```tsx
-     * // 备用图片
-     * <XImage src="/photo.jpg" fallback="/fallback.jpg" />
-     *
-     * // 自定义错误组件
-     * <XImage src="/photo.jpg" fallback={<ErrorPlaceholder />} />
-     * ```
+     * - string: 备用图片 URL
+     * - ReactNode: 自定义错误展示组件
      */
     fallback?: string | ReactNode;
-    /**
-     * 加载失败后的重试次数
-     *
-     * @default 0
-     */
+    /** 加载失败后的重试次数，默认 0 */
     retryCount?: number;
-    /**
-     * 重试间隔（毫秒）
-     *
-     * @default 1000
-     */
+    /** 重试间隔（毫秒），默认 1000 */
     retryDelay?: number;
     /**
-     * 加载状态变化回调
-     *
-     * @example
-     * ```tsx
-     * <XImage
-     *   src="/photo.jpg"
-     *   onStatusChange={(status) => console.log('Status:', status)}
-     * />
-     * ```
+     * 滚动位置（来自 trackWindowScroll HOC）
+     * 当父组件使用 withScrollTracking 包裹时自动传入
      */
-    onStatusChange?: (status: XImageStatus) => void;
-    /**
-     * 传递给包裹 div 元素的属性
-     *
-     * 用于自定义容器的事件处理、数据属性等
-     */
-    wrapperProps?: React.HTMLAttributes<HTMLDivElement>;
+    scrollPosition?: ScrollPosition;
     /**
-     * 包裹元素的类名
-     *
-     * 与 className 区分：className 应用于 img，wrapperClassName 应用于外层 div
+     * 设为 true 则图片立即显示（不触发懒加载）
+     * 适用于已在浏览器缓存中的图片
      */
+    visibleByDefault?: boolean;
+    /** 图片加载完成回调 */
+    onLoad?: (event: SyntheticEvent<HTMLImageElement>) => void;
+    /** 图片加载失败回调 */
+    onError?: (event: SyntheticEvent<HTMLImageElement>) => void;
+    /** 图片进入视口时回调 */
+    onVisible?: () => void;
+    /** 加载状态变化回调 */
+    onStatusChange?: (status: XImageStatus) => void;
+    /** 传递给包裹 span 元素的属性 */
+    wrapperProps?: React.HTMLAttributes<HTMLSpanElement>;
+    /** 包裹元素的类名 */
     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":"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"}
+{"version":3,"file":"XImage.types.d.ts","sourceRoot":"","sources":["../../../src/layout/image/XImage.types.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AAEpF;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,SAAS,GAAG,iBAAiB,CAAC;AAElE;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,UAAU,CAAC;AAElD;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEnE;;GAEG;AACH,MAAM,WAAW,cAAc;IAC3B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAExB,YAAY;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,WAAW;IACX,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,WAAW;IACX,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,aAAa;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW;IACX,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,aAAa;IACb,SAAS,CAAC,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IACvC,aAAa;IACb,cAAc,CAAC,EAAE,aAAa,CAAC,gBAAgB,CAAC,CAAC;IACjD,0BAA0B;IAC1B,IAAI,CAAC,EAAE,OAAO,CAAC;IAGf,sBAAsB;IACtB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,2BAA2B;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAAC;IAC3C,wCAAwC;IACxC,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,wBAAwB;IACxB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,iBAAiB;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IAGnB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,sBAAsB;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uBAAuB;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IAGpB;;;OAGG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAG3B,eAAe;IACf,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,CAAC,gBAAgB,CAAC,KAAK,IAAI,CAAC;IAC3D,eAAe;IACf,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,CAAC,gBAAgB,CAAC,KAAK,IAAI,CAAC;IAC5D,gBAAgB;IAChB,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,eAAe;IACf,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;IAGhD,uBAAuB;IACvB,YAAY,CAAC,EAAE,KAAK,CAAC,cAAc,CAAC,eAAe,CAAC,CAAC;IACrD,cAAc;IACd,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAG1B,cAAc;IACd,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B,WAAW;IACX,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;IACrC,cAAc;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW;IACX,WAAW,CAAC,EAAE,WAAW,GAAG,iBAAiB,GAAG,EAAE,CAAC;IACnD,kBAAkB;IAClB,cAAc,CAAC,EAAE,KAAK,CAAC,2BAA2B,CAAC;CACtD;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAC/B,QAAQ,EAAE,SAAS,CAAC;IACpB,cAAc;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc;IACd,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,gCAAgC;IAChC,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,oBAAoB;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACpC,cAAc,EAAE,cAAc,CAAC;CAClC"}

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

@@ -0,0 +1,76 @@
+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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,94 @@
+"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;

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

@@ -1,3 +1,12 @@
 export { XImage, default as XImageDefault } from "./XImage";
-export type { XImageProps, XImageStatus } from "./XImage.types";
+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" />
+ */
 //# 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;AAG5D,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC"}
+{"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"}

package/dist/layout/image/index.js

@@ -1,3 +1,4 @@
 "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.2",
+  "version": "0.8.3",
   "private": false,
   "type": "module",
   "main": "dist/index.js",
@@ -70,11 +70,11 @@
     "build": "tsc"
   },
   "peerDependencies": {
-    "react": ">=18",
-    "next": ">=13"
+    "react": ">=18"
   },
   "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,6 +97,7 @@
   "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"
   }