@tarojs/components-advanced 4.1.12-beta.2 → 4.1.12-beta.21

package/dist/components/list/hooks/useResizeObserver.js

@@ -0,0 +1,152 @@
+import Taro from '@tarojs/taro';
+import { useRef, useCallback, useEffect } from 'react';
+import { isH5, isMiniProgram } from '../utils.js';
+
+function useResizeObserver(options) {
+    const { enabled, isHorizontal, listId, onResize } = options;
+    // H5: ResizeObserver 实例
+    const observerRef = useRef(null);
+    // 小程序: IntersectionObserver 实例 Map
+    const intersectionObserversRef = useRef(new Map());
+    // 已观察的元素 Map（用于去重）
+    const observedElementsRef = useRef(new Map());
+    /**
+     * H5 实现：使用 ResizeObserver
+     */
+    const observeH5 = useCallback((element, index) => {
+        if (!element || !enabled)
+            return;
+        // 避免重复观察
+        if (observedElementsRef.current.has(index))
+            return;
+        // 创建 ResizeObserver（懒加载）
+        if (!observerRef.current) {
+            observerRef.current = new ResizeObserver((entries) => {
+                entries.forEach((entry) => {
+                    const idx = Number(entry.target.getAttribute('data-index'));
+                    if (isNaN(idx))
+                        return;
+                    const size = isHorizontal
+                        ? entry.contentRect.width
+                        : entry.contentRect.height;
+                    onResize(idx, size);
+                });
+            });
+        }
+        // 设置 data-index 属性
+        element.setAttribute('data-index', String(index));
+        // 开始观察
+        observerRef.current.observe(element);
+        observedElementsRef.current.set(index, element);
+    }, [enabled, isHorizontal, onResize]);
+    /**
+     * 小程序实现：使用 IntersectionObserver + SelectorQuery
+     * 使用唯一 id 选择器，避免多 List 并存时误命中（index>=0 为 item，index<0 为 header）
+     * 使用 Taro.nextTick 延后 observe，确保 setData 已提交、节点已挂载，避免 "Node is not found" 报错
+     */
+    const observeMiniProgram = useCallback((_element, index) => {
+        if (!enabled)
+            return;
+        // 避免重复观察
+        if (intersectionObserversRef.current.has(index))
+            return;
+        const selector = index >= 0
+            ? `#${listId}-list-item-inner-${index}`
+            : `#${listId}-list-header-inner-${-index - 1}`;
+        const doObserve = () => {
+            try {
+                // 创建 IntersectionObserver
+                const observer = Taro.createIntersectionObserver(Taro.getCurrentInstance().page, {
+                    observeAll: true
+                });
+                // 相对于 List 容器
+                observer.relativeTo(`#${listId}`);
+                // 观察元素进入可见区域（唯一 id 避免跨 List 误命中）
+                observer.observe(selector, (res) => {
+                    if (res.intersectionRatio > 0) {
+                        Taro.createSelectorQuery()
+                            .select(selector)
+                            .boundingClientRect((rect) => {
+                            if (rect) {
+                                const size = isHorizontal ? rect.width : rect.height;
+                                onResize(index, size);
+                            }
+                        })
+                            .exec();
+                    }
+                });
+                intersectionObserversRef.current.set(index, observer);
+            }
+            catch (_a) {
+                // ignore observe failure
+            }
+        };
+        Taro.nextTick(doObserve);
+    }, [enabled, isHorizontal, listId, onResize]);
+    /**
+     * 观察元素（平台自动适配）
+     */
+    const observe = useCallback((element, index) => {
+        if (!enabled)
+            return;
+        if (isH5) {
+            observeH5(element, index);
+        }
+        else if (isMiniProgram) {
+            observeMiniProgram(element, index);
+        }
+    }, [enabled, observeH5, observeMiniProgram]);
+    /**
+     * 取消观察元素
+     */
+    const unobserve = useCallback((element) => {
+        if (!element)
+            return;
+        const index = Number(element.getAttribute('data-index'));
+        if (isNaN(index))
+            return;
+        if (isH5 && observerRef.current) {
+            observerRef.current.unobserve(element);
+            observedElementsRef.current.delete(index);
+        }
+        else if (isMiniProgram) {
+            const observer = intersectionObserversRef.current.get(index);
+            if (observer) {
+                observer.disconnect();
+                intersectionObserversRef.current.delete(index);
+            }
+        }
+    }, []);
+    /**
+     * 断开所有观察
+     */
+    const disconnect = useCallback(() => {
+        if (isH5 && observerRef.current) {
+            observerRef.current.disconnect();
+            observerRef.current = null;
+            observedElementsRef.current.clear();
+        }
+        else if (isMiniProgram) {
+            intersectionObserversRef.current.forEach((observer) => {
+                observer.disconnect();
+            });
+            intersectionObserversRef.current.clear();
+        }
+    }, []);
+    /**
+     * 组件卸载时清理
+     */
+    useEffect(() => {
+        return () => {
+            disconnect();
+        };
+    }, [disconnect]);
+    return {
+        observe,
+        unobserve,
+        disconnect
+    };
+}
+
+export { useResizeObserver };
+//# sourceMappingURL=useResizeObserver.js.map

package/dist/components/list/hooks/useResizeObserver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useResizeObserver.js","sources":["../../../../src/components/list/hooks/useResizeObserver.ts"],"sourcesContent":["import Taro from '@tarojs/taro'\nimport { useCallback, useEffect, useRef } from 'react'\n\nimport { isH5, isMiniProgram } from '../utils'\n\n/**\n * useResizeObserver Hook - 尺寸变化监听（平台适配）\n *\n * H5: 使用 ResizeObserver API\n * 小程序: 使用 IntersectionObserver + SelectorQuery\n */\n\ninterface UseResizeObserverOptions {\n  /** 是否启用监听 */\n  enabled: boolean\n\n  /** 是否水平滚动（监听 width 还是 height） */\n  isHorizontal: boolean\n\n  /** List 容器 ID（小程序用于 SelectorQuery） */\n  listId: string\n\n  /** 尺寸变化回调 */\n  onResize: (index: number, size: number) => void\n}\n\ninterface UseResizeObserverReturn {\n  /** 观察指定元素（传入 ref 和索引） */\n  observe: (element: HTMLElement | null, index: number) => void\n\n  /** 取消观察指定元素 */\n  unobserve: (element: HTMLElement | null) => void\n\n  /** 断开所有观察 */\n  disconnect: () => void\n}\n\nexport function useResizeObserver(\n  options: UseResizeObserverOptions\n): UseResizeObserverReturn {\n  const { enabled, isHorizontal, listId, onResize } = options\n\n  // H5: ResizeObserver 实例\n  const observerRef = useRef<ResizeObserver | null>(null)\n\n  // 小程序: IntersectionObserver 实例 Map\n  const intersectionObserversRef = useRef<Map<number, Taro.IntersectionObserver>>(new Map())\n\n  // 已观察的元素 Map（用于去重）\n  const observedElementsRef = useRef<Map<number, HTMLElement | null>>(new Map())\n\n  /**\n   * H5 实现：使用 ResizeObserver\n   */\n  const observeH5 = useCallback((element: HTMLElement | null, index: number) => {\n    if (!element || !enabled) return\n\n    // 避免重复观察\n    if (observedElementsRef.current.has(index)) return\n\n    // 创建 ResizeObserver（懒加载）\n    if (!observerRef.current) {\n      observerRef.current = new ResizeObserver((entries) => {\n        entries.forEach((entry) => {\n          const idx = Number(entry.target.getAttribute('data-index'))\n          if (isNaN(idx)) return\n\n          const size = isHorizontal\n            ? entry.contentRect.width\n            : entry.contentRect.height\n\n          onResize(idx, size)\n        })\n      })\n    }\n\n    // 设置 data-index 属性\n    element.setAttribute('data-index', String(index))\n\n    // 开始观察\n    observerRef.current.observe(element)\n    observedElementsRef.current.set(index, element)\n  }, [enabled, isHorizontal, onResize])\n\n  /**\n   * 小程序实现：使用 IntersectionObserver + SelectorQuery\n   * 使用唯一 id 选择器，避免多 List 并存时误命中（index>=0 为 item，index<0 为 header）\n   * 使用 Taro.nextTick 延后 observe，确保 setData 已提交、节点已挂载，避免 \"Node is not found\" 报错\n   */\n  const observeMiniProgram = useCallback((_element: any, index: number) => {\n    if (!enabled) return\n\n    // 避免重复观察\n    if (intersectionObserversRef.current.has(index)) return\n\n    const selector = index >= 0\n      ? `#${listId}-list-item-inner-${index}`\n      : `#${listId}-list-header-inner-${-index - 1}`\n\n    const doObserve = () => {\n      try {\n        // 创建 IntersectionObserver\n        const observer = Taro.createIntersectionObserver(Taro.getCurrentInstance().page as any, {\n          observeAll: true\n        })\n\n        // 相对于 List 容器\n        observer.relativeTo(`#${listId}`)\n\n        // 观察元素进入可见区域（唯一 id 避免跨 List 误命中）\n        observer.observe(selector, (res) => {\n          if (res.intersectionRatio > 0) {\n            Taro.createSelectorQuery()\n              .select(selector)\n              .boundingClientRect((rect: any) => {\n                if (rect) {\n                  const size = isHorizontal ? rect.width : rect.height\n                  onResize(index, size)\n                }\n              })\n              .exec()\n          }\n        })\n\n        intersectionObserversRef.current.set(index, observer)\n      } catch {\n        // ignore observe failure\n      }\n    }\n\n    Taro.nextTick(doObserve)\n  }, [enabled, isHorizontal, listId, onResize])\n\n  /**\n   * 观察元素（平台自动适配）\n   */\n  const observe = useCallback((element: HTMLElement | null, index: number) => {\n    if (!enabled) return\n\n    if (isH5) {\n      observeH5(element, index)\n    } else if (isMiniProgram) {\n      observeMiniProgram(element, index)\n    }\n  }, [enabled, observeH5, observeMiniProgram])\n\n  /**\n   * 取消观察元素\n   */\n  const unobserve = useCallback((element: HTMLElement | null) => {\n    if (!element) return\n\n    const index = Number(element.getAttribute('data-index'))\n    if (isNaN(index)) return\n\n    if (isH5 && observerRef.current) {\n      observerRef.current.unobserve(element)\n      observedElementsRef.current.delete(index)\n    } else if (isMiniProgram) {\n      const observer = intersectionObserversRef.current.get(index)\n      if (observer) {\n        observer.disconnect()\n        intersectionObserversRef.current.delete(index)\n      }\n    }\n  }, [])\n\n  /**\n   * 断开所有观察\n   */\n  const disconnect = useCallback(() => {\n    if (isH5 && observerRef.current) {\n      observerRef.current.disconnect()\n      observerRef.current = null\n      observedElementsRef.current.clear()\n    } else if (isMiniProgram) {\n      intersectionObserversRef.current.forEach((observer) => {\n        observer.disconnect()\n      })\n      intersectionObserversRef.current.clear()\n    }\n  }, [])\n\n  /**\n   * 组件卸载时清理\n   */\n  useEffect(() => {\n    return () => {\n      disconnect()\n    }\n  }, [disconnect])\n\n  return {\n    observe,\n    unobserve,\n    disconnect\n  }\n}\n"],"names":[],"mappings":"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"}

package/dist/components/list/hooks/useScrollCorrection.d.ts

@@ -0,0 +1,19 @@
+import { type MutableRefObject } from 'react';
+interface UseScrollCorrectionOptions {
+    /** 是否启用修正 */
+    enabled: boolean;
+    /** 可见区域起始索引（取值时读 ref.current，避免 stale） */
+    visibleStartIndexRef: MutableRefObject<number>;
+    /** 设置滚动位置的回调 */
+    setScrollOffset: (offset: number | ((prev: number) => number)) => void;
+}
+interface UseScrollCorrectionReturn {
+    /** 记录尺寸变化 */
+    recordSizeChange: (index: number, oldSize: number, newSize: number) => void;
+    /** 标记用户正在滚动 */
+    markUserScrolling: () => void;
+    /** 清空修正队列 */
+    clearQueue: () => void;
+}
+export declare function useScrollCorrection(options: UseScrollCorrectionOptions): UseScrollCorrectionReturn;
+export {};

package/dist/components/list/hooks/useScrollCorrection.js

@@ -0,0 +1,73 @@
+import { useRef, useCallback } from 'react';
+
+function useScrollCorrection(options) {
+    const { enabled, visibleStartIndexRef, setScrollOffset } = options;
+    // 修正队列
+    const queueRef = useRef([]);
+    // 修正定时器
+    const timerRef = useRef(null);
+    // 用户最后滚动时间
+    const lastUserScrollTimeRef = useRef(0);
+    /**
+     * 记录尺寸变化
+     */
+    const recordSizeChange = useCallback((index, oldSize, newSize) => {
+        if (!enabled)
+            return;
+        const diff = newSize - oldSize;
+        // 阈值过滤：小于 1px 的变化忽略
+        if (Math.abs(diff) < 1)
+            return;
+        // 添加到队列
+        queueRef.current.push({ index, diff });
+        // 清除旧定时器
+        if (timerRef.current) {
+            clearTimeout(timerRef.current);
+        }
+        // 延迟执行修正（批量窗口 100ms）
+        timerRef.current = setTimeout(() => {
+            const now = Date.now();
+            // 如果用户最近 300ms 内主动滚动，跳过修正
+            if (now - lastUserScrollTimeRef.current < 300) {
+                queueRef.current = [];
+                return;
+            }
+            // 批量计算修正量（仅修正可见区域之前的变化；读 ref 获取最新值）
+            const visibleStart = visibleStartIndexRef.current;
+            const totalCorrection = queueRef.current
+                .filter(item => item.index < visibleStart)
+                .reduce((sum, item) => sum + item.diff, 0);
+            // 应用修正
+            if (Math.abs(totalCorrection) > 1) {
+                setScrollOffset(prev => prev + totalCorrection);
+            }
+            // 清空队列
+            queueRef.current = [];
+        }, 100);
+    }, [enabled, visibleStartIndexRef, setScrollOffset]);
+    /**
+     * 标记用户正在滚动
+     * 在 onScroll 事件中调用
+     */
+    const markUserScrolling = useCallback(() => {
+        lastUserScrollTimeRef.current = Date.now();
+    }, []);
+    /**
+     * 清空修正队列
+     */
+    const clearQueue = useCallback(() => {
+        if (timerRef.current) {
+            clearTimeout(timerRef.current);
+            timerRef.current = null;
+        }
+        queueRef.current = [];
+    }, []);
+    return {
+        recordSizeChange,
+        markUserScrolling,
+        clearQueue
+    };
+}
+
+export { useScrollCorrection };
+//# sourceMappingURL=useScrollCorrection.js.map

package/dist/components/list/hooks/useScrollCorrection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useScrollCorrection.js","sources":["../../../../src/components/list/hooks/useScrollCorrection.ts"],"sourcesContent":["import { type MutableRefObject, useCallback, useRef } from 'react'\n\n/**\n * useScrollCorrection Hook - ScrollTop/Left 修正\n *\n * 当列表项尺寸变化时，自动修正滚动位置，避免视觉跳动\n *\n * 策略：\n * 1. 批量处理：100ms 窗口内的多次变化合并\n * 2. 智能判断：用户滚动后 300ms 内不修正\n * 3. 范围限制：仅修正可见区域之前的变化\n * 4. 阈值过滤：小于 1px 的变化忽略\n */\n\ninterface ScrollCorrectionItem {\n  index: number\n  diff: number // 尺寸变化量\n}\n\ninterface UseScrollCorrectionOptions {\n  /** 是否启用修正 */\n  enabled: boolean\n\n  /** 可见区域起始索引（取值时读 ref.current，避免 stale） */\n  visibleStartIndexRef: MutableRefObject<number>\n\n  /** 设置滚动位置的回调 */\n  setScrollOffset: (offset: number | ((prev: number) => number)) => void\n}\n\ninterface UseScrollCorrectionReturn {\n  /** 记录尺寸变化 */\n  recordSizeChange: (index: number, oldSize: number, newSize: number) => void\n\n  /** 标记用户正在滚动 */\n  markUserScrolling: () => void\n\n  /** 清空修正队列 */\n  clearQueue: () => void\n}\n\nexport function useScrollCorrection(\n  options: UseScrollCorrectionOptions\n): UseScrollCorrectionReturn {\n  const { enabled, visibleStartIndexRef, setScrollOffset } = options\n\n  // 修正队列\n  const queueRef = useRef<ScrollCorrectionItem[]>([])\n\n  // 修正定时器\n  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null)\n\n  // 用户最后滚动时间\n  const lastUserScrollTimeRef = useRef(0)\n\n  /**\n   * 记录尺寸变化\n   */\n  const recordSizeChange = useCallback((\n    index: number,\n    oldSize: number,\n    newSize: number\n  ) => {\n    if (!enabled) return\n\n    const diff = newSize - oldSize\n\n    // 阈值过滤：小于 1px 的变化忽略\n    if (Math.abs(diff) < 1) return\n\n    // 添加到队列\n    queueRef.current.push({ index, diff })\n\n    // 清除旧定时器\n    if (timerRef.current) {\n      clearTimeout(timerRef.current)\n    }\n\n    // 延迟执行修正（批量窗口 100ms）\n    timerRef.current = setTimeout(() => {\n      const now = Date.now()\n\n      // 如果用户最近 300ms 内主动滚动，跳过修正\n      if (now - lastUserScrollTimeRef.current < 300) {\n        queueRef.current = []\n        return\n      }\n\n      // 批量计算修正量（仅修正可见区域之前的变化；读 ref 获取最新值）\n      const visibleStart = visibleStartIndexRef.current\n      const totalCorrection = queueRef.current\n        .filter(item => item.index < visibleStart)\n        .reduce((sum, item) => sum + item.diff, 0)\n\n      // 应用修正\n      if (Math.abs(totalCorrection) > 1) {\n        setScrollOffset(prev => prev + totalCorrection)\n      }\n\n      // 清空队列\n      queueRef.current = []\n    }, 100)\n  }, [enabled, visibleStartIndexRef, setScrollOffset])\n\n  /**\n   * 标记用户正在滚动\n   * 在 onScroll 事件中调用\n   */\n  const markUserScrolling = useCallback(() => {\n    lastUserScrollTimeRef.current = Date.now()\n  }, [])\n\n  /**\n   * 清空修正队列\n   */\n  const clearQueue = useCallback(() => {\n    if (timerRef.current) {\n      clearTimeout(timerRef.current)\n      timerRef.current = null\n    }\n    queueRef.current = []\n  }, [])\n\n  return {\n    recordSizeChange,\n    markUserScrolling,\n    clearQueue\n  }\n}\n"],"names":[],"mappings":";;AAyCM,SAAU,mBAAmB,CACjC,OAAmC,EAAA;IAEnC,MAAM,EAAE,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,GAAG,OAAO;;AAGlE,IAAA,MAAM,QAAQ,GAAG,MAAM,CAAyB,EAAE,CAAC;;AAGnD,IAAA,MAAM,QAAQ,GAAG,MAAM,CAAuC,IAAI,CAAC;;AAGnE,IAAA,MAAM,qBAAqB,GAAG,MAAM,CAAC,CAAC,CAAC;AAEvC;;AAEG;IACH,MAAM,gBAAgB,GAAG,WAAW,CAAC,CACnC,KAAa,EACb,OAAe,EACf,OAAe,KACb;AACF,QAAA,IAAI,CAAC,OAAO;YAAE;AAEd,QAAA,MAAM,IAAI,GAAG,OAAO,GAAG,OAAO;;AAG9B,QAAA,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC;YAAE;;QAGxB,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;;AAGtC,QAAA,IAAI,QAAQ,CAAC,OAAO,EAAE;AACpB,YAAA,YAAY,CAAC,QAAQ,CAAC,OAAO,CAAC;;;AAIhC,QAAA,QAAQ,CAAC,OAAO,GAAG,UAAU,CAAC,MAAK;AACjC,YAAA,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;;YAGtB,IAAI,GAAG,GAAG,qBAAqB,CAAC,OAAO,GAAG,GAAG,EAAE;AAC7C,gBAAA,QAAQ,CAAC,OAAO,GAAG,EAAE;gBACrB;;;AAIF,YAAA,MAAM,YAAY,GAAG,oBAAoB,CAAC,OAAO;AACjD,YAAA,MAAM,eAAe,GAAG,QAAQ,CAAC;iBAC9B,MAAM,CAAC,IAAI,IAAI,IAAI,CAAC,KAAK,GAAG,YAAY;AACxC,iBAAA,MAAM,CAAC,CAAC,GAAG,EAAE,IAAI,KAAK,GAAG,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;;YAG5C,IAAI,IAAI,CAAC,GAAG,CAAC,eAAe,CAAC,GAAG,CAAC,EAAE;gBACjC,eAAe,CAAC,IAAI,IAAI,IAAI,GAAG,eAAe,CAAC;;;AAIjD,YAAA,QAAQ,CAAC,OAAO,GAAG,EAAE;SACtB,EAAE,GAAG,CAAC;KACR,EAAE,CAAC,OAAO,EAAE,oBAAoB,EAAE,eAAe,CAAC,CAAC;AAEpD;;;AAGG;AACH,IAAA,MAAM,iBAAiB,GAAG,WAAW,CAAC,MAAK;AACzC,QAAA,qBAAqB,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE;KAC3C,EAAE,EAAE,CAAC;AAEN;;AAEG;AACH,IAAA,MAAM,UAAU,GAAG,WAAW,CAAC,MAAK;AAClC,QAAA,IAAI,QAAQ,CAAC,OAAO,EAAE;AACpB,YAAA,YAAY,CAAC,QAAQ,CAAC,OAAO,CAAC;AAC9B,YAAA,QAAQ,CAAC,OAAO,GAAG,IAAI;;AAEzB,QAAA,QAAQ,CAAC,OAAO,GAAG,EAAE;KACtB,EAAE,EAAE,CAAC;IAEN,OAAO;QACL,gBAAgB;QAChB,iBAAiB;QACjB;KACD;AACH;;;;"}

package/dist/components/list/hooks/useScrollParentAutoFind.d.ts

@@ -0,0 +1,20 @@
+import type { RefObject } from 'react';
+export type ScrollParentAutoFindStatus = 'pending' | 'found' | 'not-found';
+/**
+ * 自动查找 content 元素的真实滚动父节点。
+ * 用于 nestedScroll 模式下无 scrollElement props/Context 时，作为第三优先级来源。
+ *
+ * - H5：DOM 遍历 findScrollParent(contentEl)
+ * - 小程序：Taro 虚拟 DOM findScrollParentTaro(contentId)
+ * - ref 未就绪时自动重试
+ * - 找到后通过 setState 触发 re-render，供 effectiveScrollElement 读取
+ * - status 用于 probe 阶段：pending=尚未完成，found=已找到，not-found=已尝试未找到
+ */
+export declare function useScrollParentAutoFind(contentRef: RefObject<HTMLElement | null>, options: {
+    enabled: boolean;
+    isHorizontal?: boolean;
+    contentId?: string;
+}): {
+    scrollParentRef: RefObject<HTMLElement | null>;
+    status: ScrollParentAutoFindStatus;
+};

package/dist/components/list/hooks/useScrollParentAutoFind.js

@@ -0,0 +1,81 @@
+import { useRef, useState, useEffect } from 'react';
+import { findScrollParentTaro, findScrollParent } from '../../../utils/scrollParent.js';
+import { isWeapp } from '../utils.js';
+
+const MAX_RETRY = 20;
+const RETRY_DELAY = 50;
+/**
+ * 自动查找 content 元素的真实滚动父节点。
+ * 用于 nestedScroll 模式下无 scrollElement props/Context 时，作为第三优先级来源。
+ *
+ * - H5：DOM 遍历 findScrollParent(contentEl)
+ * - 小程序：Taro 虚拟 DOM findScrollParentTaro(contentId)
+ * - ref 未就绪时自动重试
+ * - 找到后通过 setState 触发 re-render，供 effectiveScrollElement 读取
+ * - status 用于 probe 阶段：pending=尚未完成，found=已找到，not-found=已尝试未找到
+ */
+function useScrollParentAutoFind(contentRef, options) {
+    const { enabled, isHorizontal = false, contentId } = options;
+    const scrollParentRef = useRef(null);
+    const [status, setStatus] = useState('pending');
+    const [retryTrigger, setRetryTrigger] = useState(0);
+    const retryCountRef = useRef(0);
+    useEffect(() => {
+        if (!enabled) {
+            retryCountRef.current = 0;
+            scrollParentRef.current = null;
+            setStatus('pending');
+            return;
+        }
+        if (isWeapp) {
+            // 小程序：基于 contentId 在 Taro 虚拟 DOM 中查找 scroll-view
+            if (!contentId) {
+                setStatus('not-found');
+                return;
+            }
+            const found = findScrollParentTaro(contentId);
+            if (found) {
+                retryCountRef.current = 0;
+                scrollParentRef.current = found;
+                setStatus('found');
+            }
+            else {
+                if (retryCountRef.current < MAX_RETRY) {
+                    retryCountRef.current += 1;
+                    const id = setTimeout(() => setRetryTrigger((t) => t + 1), RETRY_DELAY);
+                    return () => clearTimeout(id);
+                }
+                scrollParentRef.current = null;
+                setStatus('not-found');
+            }
+            return;
+        }
+        // H5：DOM 遍历
+        const contentEl = contentRef.current;
+        if (!contentEl) {
+            if (retryCountRef.current < MAX_RETRY) {
+                retryCountRef.current += 1;
+                const id = setTimeout(() => setRetryTrigger((t) => t + 1), RETRY_DELAY);
+                return () => clearTimeout(id);
+            }
+            setStatus('not-found');
+            return;
+        }
+        retryCountRef.current = 0;
+        const found = findScrollParent(contentEl, !isHorizontal);
+        if (found) {
+            if (found !== scrollParentRef.current) {
+                scrollParentRef.current = found;
+                setStatus('found');
+            }
+        }
+        else {
+            scrollParentRef.current = null;
+            setStatus('not-found');
+        }
+    }, [enabled, contentRef, isHorizontal, contentId, retryTrigger]);
+    return { scrollParentRef, status };
+}
+
+export { useScrollParentAutoFind };
+//# sourceMappingURL=useScrollParentAutoFind.js.map

package/dist/components/list/hooks/useScrollParentAutoFind.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useScrollParentAutoFind.js","sources":["../../../../src/components/list/hooks/useScrollParentAutoFind.ts"],"sourcesContent":["import { useEffect, useRef, useState } from 'react'\n\nimport { findScrollParent, findScrollParentTaro } from '../../../utils/scrollParent'\nimport { isWeapp } from '../utils'\n\nimport type { RefObject } from 'react'\n\nconst MAX_RETRY = 20\nconst RETRY_DELAY = 50\n\nexport type ScrollParentAutoFindStatus = 'pending' | 'found' | 'not-found'\n\n/**\n * 自动查找 content 元素的真实滚动父节点。\n * 用于 nestedScroll 模式下无 scrollElement props/Context 时，作为第三优先级来源。\n *\n * - H5：DOM 遍历 findScrollParent(contentEl)\n * - 小程序：Taro 虚拟 DOM findScrollParentTaro(contentId)\n * - ref 未就绪时自动重试\n * - 找到后通过 setState 触发 re-render，供 effectiveScrollElement 读取\n * - status 用于 probe 阶段：pending=尚未完成，found=已找到，not-found=已尝试未找到\n */\nexport function useScrollParentAutoFind(\n  contentRef: RefObject<HTMLElement | null>,\n  options: { enabled: boolean, isHorizontal?: boolean, contentId?: string }\n): { scrollParentRef: RefObject<HTMLElement | null>, status: ScrollParentAutoFindStatus } {\n  const { enabled, isHorizontal = false, contentId } = options\n  const scrollParentRef = useRef<HTMLElement | null>(null)\n  const [status, setStatus] = useState<ScrollParentAutoFindStatus>('pending')\n  const [retryTrigger, setRetryTrigger] = useState(0)\n  const retryCountRef = useRef(0)\n\n  useEffect(() => {\n    if (!enabled) {\n      retryCountRef.current = 0\n      scrollParentRef.current = null\n      setStatus('pending')\n      return\n    }\n\n    if (isWeapp) {\n      // 小程序：基于 contentId 在 Taro 虚拟 DOM 中查找 scroll-view\n      if (!contentId) {\n        setStatus('not-found')\n        return\n      }\n      const found = findScrollParentTaro(contentId)\n      if (found) {\n        retryCountRef.current = 0\n        scrollParentRef.current = found as unknown as HTMLElement\n        setStatus('found')\n      } else {\n        if (retryCountRef.current < MAX_RETRY) {\n          retryCountRef.current += 1\n          const id = setTimeout(() => setRetryTrigger((t) => t + 1), RETRY_DELAY)\n          return () => clearTimeout(id)\n        }\n        scrollParentRef.current = null\n        setStatus('not-found')\n      }\n      return\n    }\n\n    // H5：DOM 遍历\n    const contentEl = contentRef.current\n    if (!contentEl) {\n      if (retryCountRef.current < MAX_RETRY) {\n        retryCountRef.current += 1\n        const id = setTimeout(() => setRetryTrigger((t) => t + 1), RETRY_DELAY)\n        return () => clearTimeout(id)\n      }\n      setStatus('not-found')\n      return\n    }\n\n    retryCountRef.current = 0\n    const found = findScrollParent(contentEl, !isHorizontal)\n    if (found) {\n      if (found !== scrollParentRef.current) {\n        scrollParentRef.current = found\n        setStatus('found')\n      }\n    } else {\n      scrollParentRef.current = null\n      setStatus('not-found')\n    }\n  }, [enabled, contentRef, isHorizontal, contentId, retryTrigger])\n\n  return { scrollParentRef, status }\n}\n"],"names":[],"mappings":";;;;AAOA,MAAM,SAAS,GAAG,EAAE;AACpB,MAAM,WAAW,GAAG,EAAE;AAItB;;;;;;;;;AASG;AACa,SAAA,uBAAuB,CACrC,UAAyC,EACzC,OAAyE,EAAA;IAEzE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,KAAK,EAAE,SAAS,EAAE,GAAG,OAAO;AAC5D,IAAA,MAAM,eAAe,GAAG,MAAM,CAAqB,IAAI,CAAC;IACxD,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,QAAQ,CAA6B,SAAS,CAAC;IAC3E,MAAM,CAAC,YAAY,EAAE,eAAe,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC;AACnD,IAAA,MAAM,aAAa,GAAG,MAAM,CAAC,CAAC,CAAC;IAE/B,SAAS,CAAC,MAAK;QACb,IAAI,CAAC,OAAO,EAAE;AACZ,YAAA,aAAa,CAAC,OAAO,GAAG,CAAC;AACzB,YAAA,eAAe,CAAC,OAAO,GAAG,IAAI;YAC9B,SAAS,CAAC,SAAS,CAAC;YACpB;;QAGF,IAAI,OAAO,EAAE;;YAEX,IAAI,CAAC,SAAS,EAAE;gBACd,SAAS,CAAC,WAAW,CAAC;gBACtB;;AAEF,YAAA,MAAM,KAAK,GAAG,oBAAoB,CAAC,SAAS,CAAC;YAC7C,IAAI,KAAK,EAAE;AACT,gBAAA,aAAa,CAAC,OAAO,GAAG,CAAC;AACzB,gBAAA,eAAe,CAAC,OAAO,GAAG,KAA+B;gBACzD,SAAS,CAAC,OAAO,CAAC;;iBACb;AACL,gBAAA,IAAI,aAAa,CAAC,OAAO,GAAG,SAAS,EAAE;AACrC,oBAAA,aAAa,CAAC,OAAO,IAAI,CAAC;oBAC1B,MAAM,EAAE,GAAG,UAAU,CAAC,MAAM,eAAe,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,WAAW,CAAC;AACvE,oBAAA,OAAO,MAAM,YAAY,CAAC,EAAE,CAAC;;AAE/B,gBAAA,eAAe,CAAC,OAAO,GAAG,IAAI;gBAC9B,SAAS,CAAC,WAAW,CAAC;;YAExB;;;AAIF,QAAA,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO;QACpC,IAAI,CAAC,SAAS,EAAE;AACd,YAAA,IAAI,aAAa,CAAC,OAAO,GAAG,SAAS,EAAE;AACrC,gBAAA,aAAa,CAAC,OAAO,IAAI,CAAC;gBAC1B,MAAM,EAAE,GAAG,UAAU,CAAC,MAAM,eAAe,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,WAAW,CAAC;AACvE,gBAAA,OAAO,MAAM,YAAY,CAAC,EAAE,CAAC;;YAE/B,SAAS,CAAC,WAAW,CAAC;YACtB;;AAGF,QAAA,aAAa,CAAC,OAAO,GAAG,CAAC;QACzB,MAAM,KAAK,GAAG,gBAAgB,CAAC,SAAS,EAAE,CAAC,YAAY,CAAC;QACxD,IAAI,KAAK,EAAE;AACT,YAAA,IAAI,KAAK,KAAK,eAAe,CAAC,OAAO,EAAE;AACrC,gBAAA,eAAe,CAAC,OAAO,GAAG,KAAK;gBAC/B,SAAS,CAAC,OAAO,CAAC;;;aAEf;AACL,YAAA,eAAe,CAAC,OAAO,GAAG,IAAI;YAC9B,SAAS,CAAC,WAAW,CAAC;;AAE1B,KAAC,EAAE,CAAC,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,SAAS,EAAE,YAAY,CAAC,CAAC;AAEhE,IAAA,OAAO,EAAE,eAAe,EAAE,MAAM,EAAE;AACpC;;;;"}

package/dist/components/list/index.d.ts

@@ -1,7 +1,9 @@
 import React from 'react';
 import ListItem from './ListItem';
+import NoMore from './NoMore';
 import StickyHeader from './StickyHeader';
 import StickySection from './StickySection';
+/** 与官方 List.d.ts / ScrollView / harmony 对齐，不增减已有语义；扩展项仅用于高级能力 */
 export interface ListProps {
     showScrollbar?: boolean;
     scrollTop?: number;
@@ -10,27 +12,82 @@ export interface ListProps {
     onScroll?: (e: {
         scrollTop: number;
         scrollLeft: number;
+        detail: {
+            scrollTop: number;
+            scrollLeft: number;
+        };
     }) => void;
     onScrollToUpper?: () => void;
     onScrollToLower?: () => void;
     upperThreshold?: number;
     lowerThreshold?: number;
-    cacheCount?: number;
+    /** 与 ScrollView cacheExtent 对齐（视口外渲染距离），可选 */
+    cacheExtent?: number;
+    /** 与 ScrollView enableBackToTop 对齐 */
+    enableBackToTop?: boolean;
+    /** 与 ScrollView onScrollStart 对齐 */
+    onScrollStart?: () => void;
+    /** 与 ScrollView onScrollEnd 对齐 */
+    onScrollEnd?: () => void;
+    scrollIntoView?: string;
+    /** 透传给最外层 ScrollView 的 className，便于自定义样式 */
+    className?: string;
     stickyHeader?: boolean;
     space?: number;
+    cacheCount?: number;
     itemData?: any[];
     itemSize?: number | ((index: number, data?: any[]) => number);
     height?: number | string;
     width?: number | string;
     style?: React.CSSProperties;
     children?: React.ReactNode;
-    headerHeight?: number;
-    headerWidth?: number;
-    itemHeight?: number;
-    itemWidth?: number;
+    /** Header 沿滚动方向尺寸；未传时回退到 itemSize */
+    headerSize?: number;
+    useResizeObserver?: boolean;
+    onItemSizeChange?: (index: number, size: number) => void;
+    showNoMore?: boolean;
+    noMoreText?: string;
+    noMoreStyle?: React.CSSProperties;
+    renderNoMore?: () => React.ReactNode;
+    onScrollIndex?: (start: number, end: number) => void;
+    /** 是否开启下拉刷新；与 Refresher 子组件二选一或同时存在（Refresher 子覆盖同名字段） */
+    refresherEnabled?: boolean;
+    refresherThreshold?: number;
+    refresherDefaultStyle?: 'black' | 'white' | 'none';
+    refresherBackground?: string;
+    refresherTriggered?: boolean;
+    onRefresherPulling?: (e?: {
+        detail?: {
+            deltaY?: number;
+        };
+    }) => void;
+    onRefresherRefresh?: () => void | Promise<void>;
+    onRefresherRestore?: () => void;
+    onRefresherAbort?: () => void;
+    onRefresherWillRefresh?: () => void;
+    onRefresherStatusChange?: (e?: {
+        detail?: {
+            status?: number;
+            dy?: number;
+        };
+    }) => void;
+    /** 是否嵌套模式，与 plato 对齐；true=使用父级滚动，需配合 scrollElement 或 Context；不传或 false=default */
+    nestedScroll?: boolean;
+    /** 自定义滚动容器 ref，nestedScroll 模式下从 props 或 Context 获取 */
+    scrollElement?: React.RefObject<HTMLElement | null>;
+    /** 暴露滚动容器 ref，供内层 List/WaterFlow（nestedScroll）嵌套时传入 scrollElement */
+    scrollRef?: React.MutableRefObject<HTMLElement | null>;
+}
+export interface ListHandle {
+    scroll: (options?: {
+        top?: number;
+        left?: number;
+    }) => void;
 }
 export declare function accumulate(arr: number[]): number[];
 export declare function isShaking(diffList: number[]): boolean;
-declare const List: React.FC<ListProps>;
-export { List, ListItem, StickyHeader, StickySection };
+/** 向后兼容：ListScrollElementContext 已统一为 ScrollElementContext，无 Context 时兜底为 fallback */
+export { ScrollElementContextOrFallback as ListScrollElementContext } from '../../utils/scrollElementContext';
+declare const List: React.ForwardRefExoticComponent<ListProps & React.RefAttributes<ListHandle>>;
+export { List, ListItem, NoMore, StickyHeader, StickySection };
 export default List;