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

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

@@ -0,0 +1,146 @@
+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
+     */
+    const observeMiniProgram = useCallback((_element, index) => {
+        if (!enabled)
+            return;
+        // 避免重复观察
+        if (intersectionObserversRef.current.has(index))
+            return;
+        try {
+            // 创建 IntersectionObserver
+            const observer = Taro.createIntersectionObserver(Taro.getCurrentInstance().page, {
+                observeAll: true
+            });
+            // 相对于 List 容器
+            observer.relativeTo(`#${listId}`);
+            // 观察元素进入可见区域
+            // SelectorQuery 是只读查询，不会触发 setData，滚动期间执行安全
+            // sizeCacheVersion 的延迟 bump 由 weappSizeCacheVersionBump 在 onResize 链路中负责
+            observer.observe(`[data-index="${index}"]`, (res) => {
+                if (res.intersectionRatio > 0) {
+                    Taro.createSelectorQuery()
+                        .select(`[data-index="${index}"]`)
+                        .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
+        }
+    }, [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   */\n  const observeMiniProgram = useCallback((_element: any, index: number) => {\n    if (!enabled) return\n\n    // 避免重复观察\n    if (intersectionObserversRef.current.has(index)) return\n\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      // 观察元素进入可见区域\n      // SelectorQuery 是只读查询，不会触发 setData，滚动期间执行安全\n      // sizeCacheVersion 的延迟 bump 由 weappSizeCacheVersionBump 在 onResize 链路中负责\n      observer.observe(`[data-index=\"${index}\"]`, (res) => {\n        if (res.intersectionRatio > 0) {\n          Taro.createSelectorQuery()\n            .select(`[data-index=\"${index}\"]`)\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  }, [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,18 @@
+interface UseScrollCorrectionOptions {
+    /** 是否启用修正 */
+    enabled: boolean;
+    /** 可见区域起始索引 */
+    visibleStartIndex: 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,72 @@
+import { useRef, useCallback } from 'react';
+
+function useScrollCorrection(options) {
+    const { enabled, visibleStartIndex, 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;
+            }
+            // 批量计算修正量（仅修正可见区域之前的变化）
+            const totalCorrection = queueRef.current
+                .filter(item => item.index < visibleStartIndex)
+                .reduce((sum, item) => sum + item.diff, 0);
+            // 应用修正
+            if (Math.abs(totalCorrection) > 1) {
+                setScrollOffset(prev => prev + totalCorrection);
+            }
+            // 清空队列
+            queueRef.current = [];
+        }, 100);
+    }, [enabled, visibleStartIndex, 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 { 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  /** 可见区域起始索引 */\n  visibleStartIndex: 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, visibleStartIndex, 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      // 批量计算修正量（仅修正可见区域之前的变化）\n      const totalCorrection = queueRef.current\n        .filter(item => item.index < visibleStartIndex)\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, visibleStartIndex, 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,iBAAiB,EAAE,eAAe,EAAE,GAAG,OAAO;;AAG/D,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,eAAe,GAAG,QAAQ,CAAC;iBAC9B,MAAM,CAAC,IAAI,IAAI,IAAI,CAAC,KAAK,GAAG,iBAAiB;AAC7C,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,iBAAiB,EAAE,eAAe,CAAC,CAAC;AAEjD;;;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/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;
@@ -15,9 +17,20 @@ export interface ListProps {
     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;
@@ -28,9 +41,45 @@ export interface ListProps {
     headerWidth?: number;
     itemHeight?: number;
     itemWidth?: number;
+    useResizeObserver?: boolean;
+    estimatedItemSize?: number;
+    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;
+}
+export interface ListHandle {
+    scroll: (options?: {
+        top?: number;
+        left?: number;
+        behavior?: 'auto' | 'smooth';
+    }) => 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 };
+declare const List: React.ForwardRefExoticComponent<ListProps & React.RefAttributes<ListHandle>>;
+export { List, ListItem, NoMore, StickyHeader, StickySection };
 export default List;