@tarojs/components-advanced 4.1.12-beta.3 → 4.1.12-beta.33

package/dist/components/list/index.js

@@ -1,11 +1,23 @@
-import { jsx, jsxs } from 'react/jsx-runtime';
+import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 import { View, ScrollView } from '@tarojs/components';
+import Taro from '@tarojs/taro';
 import React from 'react';
+import '../../utils/index.js';
+import { ScrollElementContextOrFallback } from '../../utils/scrollElementContext.js';
+import { useItemSizeCache } from './hooks/useItemSizeCache.js';
+import { useListNestedScroll } from './hooks/useListNestedScroll.js';
+import { useListScrollElementAttach } from './hooks/useListScrollElementAttach.js';
+import { useListScrollElementAttachWeapp } from './hooks/useListScrollElementAttachWeapp.js';
+import { useRefresher, DEFAULT_REFRESHER_HEIGHT } from './hooks/useRefresher.js';
+import { useResizeObserver } from './hooks/useResizeObserver.js';
+import { useScrollCorrection } from './hooks/useScrollCorrection.js';
 import { ListItem } from './ListItem.js';
+import { NoMore } from './NoMore.js';
 import { StickyHeader } from './StickyHeader.js';
 import { StickySection } from './StickySection.js';
+import { isWeapp, createSelectorQueryScoped, isH5, supportsNativeRefresher } from './utils.js';
+import { getScrollViewContextNode } from '../../utils/dom.js';
 
-// 工具：累加数组
 function accumulate(arr) {
     const result = [0];
     for (let i = 0; i < arr.length; i++) {
@@ -13,46 +25,331 @@ function accumulate(arr) {
     }
     return result;
 }
-// 检测抖动
 function isShaking(diffList) {
     if (diffList.length < 3)
         return false;
-    // 检查是否有连续的正负交替
     const signs = diffList.map(diff => Math.sign(diff));
     let alternations = 0;
     for (let i = 1; i < signs.length; i++) {
-        if (signs[i] !== 0 && signs[i] !== signs[i - 1]) {
+        if (signs[i] !== 0 && signs[i] !== signs[i - 1])
             alternations++;
-        }
     }
-    // 如果交替次数过多，认为是抖动
     return alternations >= 2;
 }
-const List = (props) => {
-    const isH5 = process.env.TARO_ENV === 'h5';
-    const { stickyHeader = false, space = 0, height = 400, width = '100%', showScrollbar = true, scrollTop: controlledScrollTop, scrollX = false, scrollY = true, onScroll, onScrollToUpper, onScrollToLower, upperThreshold = 0, lowerThreshold = 0, cacheCount = 2, style, children, } = props;
+// 小程序端：判断 item 是否应该执行 SelectorQuery 测量（仅检查是否已测量过）
+// SelectorQuery 是只读查询，不会触发 setData，滚动期间执行是安全的
+function shouldMeasureWeappItem(index, measuredSet) {
+    return !measuredSet.has(index);
+}
+// 小程序端暂不外抛 onItemSizeChange，避免父层重渲染导致 List remount 引发回顶或空白
+function weappDeferItemSizeChange(_index, _size, _onItemSizeChange) { }
+/** 从 scroll 选项解析目标偏移量 */
+function resolveScrollTargetOffset(options, isHorizontal) {
+    const opts = options !== null && options !== void 0 ? options : {};
+    const top = typeof opts.top === 'number' ? opts.top : undefined;
+    const left = typeof opts.left === 'number' ? opts.left : undefined;
+    let result = 0;
+    if (isHorizontal) {
+        if (typeof left === 'number')
+            result = left;
+        else if (typeof top === 'number')
+            result = top;
+    }
+    else {
+        if (typeof top === 'number')
+            result = top;
+        else if (typeof left === 'number')
+            result = left;
+    }
+    return Number.isFinite(result) ? result : 0;
+}
+// eslint-disable-next-line complexity -- List 多端/多模式逻辑集中，已抽离 useListNestedScroll、useListScrollElementAttach、resolveScrollTargetOffset 等
+const InnerList = (props, ref) => {
+    var _a, _b;
+    const { stickyHeader = false, space = 0, height = 400, width = '100%', showScrollbar = true, scrollTop: controlledScrollTop, scrollX = false, scrollY = true, onScroll, onScrollToUpper, onScrollToLower, onScrollStart, onScrollEnd, upperThreshold = 50, lowerThreshold = 50, cacheCount = 2, cacheExtent, enableBackToTop, className, style, children, nestedScroll, scrollElement, scrollRef: scrollRefProp, } = props;
     const isHorizontal = scrollX === true;
+    const listType = nestedScroll === true ? 'nested' : 'default';
+    const { effectiveScrollElement, effectiveStartOffset, effectiveStartOffsetRef, useScrollElementMode, needAutoFind, autoFindStatus, contentWrapperRef, contentId, } = useListNestedScroll(listType, scrollElement, undefined, isHorizontal, props.selectorQueryScope);
     const DEFAULT_ITEM_WIDTH = 120;
     const DEFAULT_ITEM_HEIGHT = 40;
+    const defaultItemSize = isHorizontal ? DEFAULT_ITEM_WIDTH : DEFAULT_ITEM_HEIGHT;
+    const normalizeSize = React.useCallback((value) => {
+        if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0)
+            return null;
+        return value;
+    }, []);
+    const resolveItemSizeByIndex = React.useCallback((index, fallback) => {
+        const { itemSize, itemData } = props;
+        const numberSize = normalizeSize(itemSize);
+        if (numberSize != null)
+            return numberSize;
+        if (typeof itemSize === 'function') {
+            const functionSize = normalizeSize(itemSize(index, itemData));
+            if (functionSize != null)
+                return functionSize;
+        }
+        return fallback;
+    }, [props.itemSize, props.itemData, normalizeSize]);
     // 滚动状态管理
     const containerRef = React.useRef(null);
+    // 生成唯一 List ID（用于小程序 ResizeObserver）
+    const listId = React.useMemo(() => `list-${Math.random().toString(36).slice(2, 11)}`, []);
     // 渲染偏移量 - 用于计算应该渲染哪些元素
     const [renderOffset, setRenderOffset] = React.useState(controlledScrollTop !== null && controlledScrollTop !== void 0 ? controlledScrollTop : 0);
-    // 滚动视图偏移量 - 只在滚动结束或明确请求时更新到ScrollView
+    // 程序性滚动用的目标偏移；用户滑动期间不更新，避免与原生滚动冲突
     const [scrollViewOffset, setScrollViewOffset] = React.useState(controlledScrollTop !== null && controlledScrollTop !== void 0 ? controlledScrollTop : 0);
-    const [containerLength] = React.useState(typeof (isHorizontal ? width : height) === 'number' ? (isHorizontal ? width : height) : 400);
+    // 用户正在滑动时不再向 ScrollView 传 scrollTop，让滚动完全由原生接管
+    const [isUserScrolling, setIsUserScrolling] = React.useState(false);
+    // isUserScrolling 的 ref 镜像，供异步上下文读取最新值
+    const isUserScrollingRef = React.useRef(false);
+    const initialContainerLength = typeof (isHorizontal ? width : height) === 'number' ? (isHorizontal ? width : height) : 400;
+    const [containerLength, setContainerLength] = React.useState(initialContainerLength);
+    // 用容器实际尺寸更新视口长度，避免 props 与 CSS 不一致导致底部空白
+    React.useEffect(() => {
+        const el = containerRef.current;
+        if (!el || typeof ResizeObserver === 'undefined')
+            return;
+        const ro = new ResizeObserver((entries) => {
+            for (const entry of entries) {
+                const { contentRect } = entry;
+                const measured = isHorizontal ? contentRect.width : contentRect.height;
+                if (measured > 0)
+                    setContainerLength(measured);
+            }
+        });
+        ro.observe(el);
+        return () => ro.disconnect();
+    }, [isHorizontal]);
+    // WeChat 小程序：没有原生 ResizeObserver，用 SelectorQuery 一次性测量容器高度
+    React.useEffect(() => {
+        if (!isWeapp)
+            return;
+        Taro.nextTick(() => {
+            createSelectorQueryScoped(props.selectorQueryScope)
+                .select(`#${listId}`)
+                .boundingClientRect((rect) => {
+                const measured = isHorizontal ? rect === null || rect === void 0 ? void 0 : rect.width : rect === null || rect === void 0 ? void 0 : rect.height;
+                if (typeof measured === 'number' && measured > 0) {
+                    setContainerLength(measured);
+                }
+            })
+                .exec();
+        });
+    }, [isWeapp, isHorizontal, listId]);
     // 滚动追踪相关refs
     const isScrollingRef = React.useRef(false);
     const lastScrollTopRef = React.useRef(controlledScrollTop !== null && controlledScrollTop !== void 0 ? controlledScrollTop : 0);
     const scrollDiffListRef = React.useRef([0, 0, 0]);
     const scrollTimeoutRef = React.useRef(null);
-    // 解析分组结构，只支持 StickySection 和 ListItem 作为直接子组件
+    // H5：仅程序性滚动时写回 DOM scrollTop，用户滑动结束后不写回避免卡顿
+    const programmaticScrollRef = React.useRef(false);
+    // 小程序端程序性滚动冷却期：handleScroll 只更新 renderOffset，避免 scrollIntoView 后被原生回调拉回
+    const programmaticCooldownRef = React.useRef(false);
+    const programmaticCooldownTimerRef = React.useRef(null);
+    const scrollViewOffsetRef = React.useRef(0);
+    // 用户滚动期间挂起的 reflow 标记（用于滚动结束后补触发）
+    const pendingWeappReflowRef = React.useRef(false);
+    // ref 持有最新版 scheduleWeappDynamicReflow，供 updateRenderOffset 内的 setTimeout 闭包安全访问
+    const scheduleWeappDynamicReflowRef = React.useRef(null);
+    // 处理渲染偏移量更新。
+    // syncToScrollView=true：程序性滚动，立即同步 scrollViewOffset。
+    // syncToScrollView=false：用户滑动，仅更新 renderOffset。weapp 采用 recycle-view 策略：不把用户滑动位置同步到 scrollViewOffset，避免「传滞后值拉回」和「从有到无归顶」。
+    const updateRenderOffset = React.useCallback((newOffset, syncToScrollView, source) => {
+        lastScrollTopRef.current = newOffset;
+        isScrollingRef.current = true;
+        if (scrollTimeoutRef.current) {
+            clearTimeout(scrollTimeoutRef.current);
+        }
+        setRenderOffset(newOffset); // 始终更新虚拟列表用到的偏移
+        if (syncToScrollView) {
+            isUserScrollingRef.current = false;
+            setIsUserScrolling(false);
+            // 小程序：target===sv 时 ScrollView 认为无变化不滚动→白屏；imperative/scrollIntoView 时先传中间值再 RAF 传 target 强制触发
+            // target=0 用 +0.01；target>0 用 -0.01（统一 +0.01 到底部会被 clamp 成同值无效）
+            const same = isWeapp && Math.abs(scrollViewOffsetRef.current - newOffset) < 1;
+            const needForce = same && (source === 'imperative' || source === 'scrollIntoView');
+            if (needForce) {
+                const intermediate = newOffset > 0 ? newOffset - 0.01 : 0.01;
+                setScrollViewOffset(intermediate);
+                programmaticScrollRef.current = true;
+                requestAnimationFrame(() => {
+                    // 第二帧也需要标记为程序性滚动，否则 else 分支不会传 scrollTop
+                    programmaticScrollRef.current = true;
+                    setScrollViewOffset(newOffset);
+                });
+            }
+            else {
+                setScrollViewOffset(newOffset);
+            }
+            programmaticScrollRef.current = true;
+            if (isWeapp) {
+                programmaticCooldownRef.current = true;
+                if (programmaticCooldownTimerRef.current) {
+                    clearTimeout(programmaticCooldownTimerRef.current);
+                }
+                programmaticCooldownTimerRef.current = setTimeout(() => {
+                    programmaticCooldownRef.current = false;
+                }, 500);
+            }
+        }
+        else {
+            isUserScrollingRef.current = true;
+            setIsUserScrolling(true);
+        }
+        scrollTimeoutRef.current = setTimeout(() => {
+            isScrollingRef.current = false;
+            if (!syncToScrollView) {
+                isUserScrollingRef.current = false;
+                setIsUserScrolling(false);
+                // weapp recycle-view 策略：用户滑动结束后不同步 scrollViewOffset，保持 pass 的值不变，避免 从有到无 归顶
+                if (!isWeapp) {
+                    setScrollViewOffset(lastScrollTopRef.current);
+                }
+                // 滚动结束后触发期间被延迟的 reflow（item 首次测量触发）
+                if (isWeapp && pendingWeappReflowRef.current) {
+                    scheduleWeappDynamicReflowRef.current();
+                }
+            }
+        }, isWeapp ? 200 : 150);
+    }, []);
+    // 暴露给外部的实例方法：通过 ref.scroll({ top / left }) 进行程序性滚动
+    React.useImperativeHandle(ref, () => ({
+        scroll(options) {
+            const targetOffset = resolveScrollTargetOffset(options, isHorizontal);
+            const el = effectiveScrollElement === null || effectiveScrollElement === void 0 ? void 0 : effectiveScrollElement.current;
+            if (el && isH5) {
+                const scrollTarget = targetOffset + effectiveStartOffset;
+                if (isHorizontal) {
+                    el.scrollTo({ left: scrollTarget });
+                }
+                else {
+                    el.scrollTo({ top: scrollTarget });
+                }
+                updateRenderOffset(targetOffset, false, 'scrollElement');
+            }
+            else if (el && isWeapp && useScrollElementMode) {
+                // 小程序 scrollElement 模式：需通过 getScrollViewContextNode + node.scrollTo 真正滚动外部 scroll-view
+                // updateRenderOffset 必须在 scrollTo 之后调用，否则 getScrollViewContextNode 异步期间会先更新 renderOffset 导致闪一下
+                const startOff = effectiveStartOffsetRef.current;
+                const scrollTarget = targetOffset + startOff;
+                const scrollViewId = el.id || `_ls_${listId}`;
+                if (!el.id)
+                    el.id = scrollViewId;
+                getScrollViewContextNode(`#${scrollViewId}`).then((node) => {
+                    var _a, _b;
+                    if (isHorizontal) {
+                        (_a = node === null || node === void 0 ? void 0 : node.scrollTo) === null || _a === void 0 ? void 0 : _a.call(node, { left: scrollTarget, animated: false });
+                    }
+                    else {
+                        (_b = node === null || node === void 0 ? void 0 : node.scrollTo) === null || _b === void 0 ? void 0 : _b.call(node, { top: scrollTarget, animated: false });
+                    }
+                    updateRenderOffset(targetOffset, true, 'imperative');
+                });
+            }
+            else {
+                updateRenderOffset(targetOffset, true, 'imperative');
+            }
+        },
+    }), [scrollX, effectiveScrollElement, effectiveStartOffset, effectiveStartOffsetRef, isH5, isWeapp, isHorizontal, listId, useScrollElementMode, updateRenderOffset]);
+    // 提取 Refresher 配置（List 属性为 base，Refresher 子组件覆盖）
+    const refresherConfig = React.useMemo(() => {
+        const listRefresherEnabled = props.refresherEnabled !== false && (props.refresherEnabled === true || props.onRefresherRefresh != null);
+        const baseFromList = listRefresherEnabled
+            ? {
+                refresherEnabled: props.refresherEnabled,
+                refresherThreshold: props.refresherThreshold,
+                refresherDefaultStyle: props.refresherDefaultStyle,
+                refresherBackground: props.refresherBackground,
+                refresherTriggered: props.refresherTriggered,
+                onRefresherPulling: props.onRefresherPulling,
+                onRefresherRefresh: props.onRefresherRefresh,
+                onRefresherRestore: props.onRefresherRestore,
+                onRefresherAbort: props.onRefresherAbort,
+                onRefresherWillRefresh: props.onRefresherWillRefresh,
+                onRefresherStatusChange: props.onRefresherStatusChange,
+            }
+            : null;
+        const isRefresherComponent = (child) => {
+            const type = child.type;
+            return (type === null || type === void 0 ? void 0 : type.displayName) === 'Refresher' || (type === null || type === void 0 ? void 0 : type.name) === 'Refresher';
+        };
+        let refresherChildProps = null;
+        let refresherCount = 0;
+        React.Children.forEach(children, (child) => {
+            if (React.isValidElement(child) && isRefresherComponent(child)) {
+                refresherCount++;
+                if (refresherCount > 1) {
+                    return;
+                }
+                refresherChildProps = child.props;
+            }
+        });
+        if (refresherChildProps != null) {
+            const base = baseFromList !== null && baseFromList !== void 0 ? baseFromList : {};
+            // Refresher 子组件的配置覆盖 List 的配置
+            return Object.assign(Object.assign({}, base), refresherChildProps);
+        }
+        return baseFromList;
+    }, [
+        children,
+        props.refresherEnabled,
+        props.refresherThreshold,
+        props.refresherDefaultStyle,
+        props.refresherBackground,
+        props.refresherTriggered,
+        props.onRefresherPulling,
+        props.onRefresherRefresh,
+        props.onRefresherRestore,
+        props.onRefresherAbort,
+        props.onRefresherWillRefresh,
+        props.onRefresherStatusChange,
+    ]);
+    // 提取 NoMore 配置
+    const noMoreConfig = React.useMemo(() => {
+        var _a;
+        let config = null;
+        let noMoreCount = 0;
+        // 从子组件中提取 NoMore
+        React.Children.forEach(children, (child) => {
+            if (React.isValidElement(child) && child.type === NoMore) {
+                noMoreCount++;
+                if (noMoreCount > 1) {
+                    return;
+                }
+                const childProps = child.props;
+                config = Object.assign(Object.assign({}, childProps), { visible: childProps.visible !== false });
+            }
+        });
+        // Props 方式转换为配置（优先级低于子组件）
+        if (props.showNoMore && !config) {
+            config = {
+                visible: true,
+                text: props.noMoreText,
+                style: props.noMoreStyle,
+                children: (_a = props.renderNoMore) === null || _a === void 0 ? void 0 : _a.call(props)
+            };
+        }
+        return config;
+    }, [children, props.showNoMore, props.noMoreText, props.noMoreStyle, props.renderNoMore]);
+    // Refresher 平台适配：H5 用 addImperativeTouchListeners
+    const { scrollViewRefresherProps, scrollViewRefresherHandlers, h5RefresherProps, addImperativeTouchListeners, renderRefresherContent, } = useRefresher(refresherConfig, isH5 && refresherConfig && !supportsNativeRefresher ? 0 : renderOffset, useScrollElementMode
+        ? (ev) => { var _a, _b; return (_b = (ev.target != null && ((_a = contentWrapperRef.current) === null || _a === void 0 ? void 0 : _a.contains(ev.target)))) !== null && _b !== void 0 ? _b : false; }
+        : undefined);
+    const refresherTeardownRef = React.useRef(null);
+    const addImperativeTouchListenersRef = React.useRef(addImperativeTouchListeners);
+    addImperativeTouchListenersRef.current = addImperativeTouchListeners;
+    React.useEffect(() => () => {
+        if (refresherTeardownRef.current)
+            refresherTeardownRef.current();
+    }, []);
+    // H5 下拉刷新顶栏高度（默认 50px，来自 useRefresher）
+    const refresherHeightForH5 = (isH5 && refresherConfig && !supportsNativeRefresher && refresherConfig.refresherEnabled !== false) ? DEFAULT_REFRESHER_HEIGHT : 0;
+    // 解析分组结构：StickySection、ListItem 为直接子组件，过滤 Refresher/NoMore
     const sections = React.useMemo(() => {
         const result = [];
         const defaultItems = [];
         React.Children.forEach(children, (child, idx) => {
             if (React.isValidElement(child) && child.type === StickySection) {
-                // 分组模式
                 const sectionProps = child.props;
                 let header = null;
                 const items = [];
@@ -65,7 +362,6 @@ const List = (props) => {
                 result.push({ header, items, key: child.key || String(idx) });
             }
             else if (React.isValidElement(child) && child.type === ListItem) {
-                // 普通 ListItem
                 defaultItems.push(child);
             }
         });
@@ -74,65 +370,169 @@ const List = (props) => {
         }
         return result;
     }, [children]);
-    // 工具：获取 header 尺寸，确保所有 header 相关逻辑一致
-    const getHeaderSize = () => {
-        if (isHorizontal) {
-            if (typeof props.headerWidth === 'number')
-                return props.headerWidth;
-            if (typeof props.itemWidth === 'number')
-                return props.itemWidth;
-            if (typeof props.itemSize === 'number')
-                return props.itemSize;
-            if (typeof props.itemSize === 'function')
-                return props.itemSize(0, props.itemData) || DEFAULT_ITEM_WIDTH;
-            return DEFAULT_ITEM_WIDTH;
+    // 动态尺寸管理
+    const estimatedSize = resolveItemSizeByIndex(0, defaultItemSize);
+    // 计算总 item 数量（跨所有 section）
+    const totalItemCount = React.useMemo(() => {
+        return sections.reduce((sum, section) => sum + section.items.length, 0);
+    }, [sections]);
+    // 存储元素引用（用于 ResizeObserver）
+    const itemRefsRef = React.useRef(new Map());
+    // 存储 header 元素引用（用于 ResizeObserver）
+    const headerRefsRef = React.useRef(new Map());
+    // 小程序端：已完成 SelectorQuery 测量的 item 索引集，避免 refCallback 重复触发测量导致无限循环
+    const weappMeasuredItemsRef = React.useRef(new Set());
+    // 动态尺寸缓存更新版本：setItemSize 后递增，用于驱动 sectionOffsets/totalLength 与 item 定位重算
+    const [sizeCacheVersion, setSizeCacheVersion] = React.useState(0);
+    const sizeCacheRafRef = React.useRef(null);
+    // （measureScrollProtectRef 已移除：scrollTop + 内容变更同帧 setData 会与 scrollAnchoring
+    //  冲突导致归顶；改由 scrollAnchoring=true 独立处理内容重排，无需显式传 scrollTop 保护）
+    // 动态尺寸缓存
+    const sizeCache = useItemSizeCache({
+        isHorizontal,
+        estimatedSize,
+        itemCount: totalItemCount
+    });
+    // header 动态尺寸缓存（sectionIndex -> size）
+    const headerSizeCacheRef = React.useRef(new Map());
+    // 滚动修正的可见起始索引
+    const visibleStartIndexRef = React.useRef(0);
+    // ScrollTop 修正（仅 H5）：动高时尺寸变化自动修正 scrollTop
+    const scrollCorrectionEnabled = !isWeapp && props.useResizeObserver === true;
+    const scrollCorrection = useScrollCorrection({
+        enabled: scrollCorrectionEnabled,
+        visibleStartIndexRef,
+        setScrollOffset: (offsetOrUpdater) => {
+            const newOffset = typeof offsetOrUpdater === 'function'
+                ? offsetOrUpdater(renderOffset)
+                : offsetOrUpdater;
+            updateRenderOffset(newOffset, true, 'scrollCorrection'); // 程序性修正需同步到 ScrollView
         }
-        else {
-            if (typeof props.headerHeight === 'number')
-                return props.headerHeight;
-            if (typeof props.itemHeight === 'number')
-                return props.itemHeight;
-            if (typeof props.itemSize === 'number')
-                return props.itemSize;
-            if (typeof props.itemSize === 'function')
-                return props.itemSize(0, props.itemData) || DEFAULT_ITEM_HEIGHT;
-            return DEFAULT_ITEM_HEIGHT;
+    });
+    const scrollCorrectionRef = React.useRef(scrollCorrection);
+    scrollCorrectionRef.current = scrollCorrection;
+    const onScrollRef = React.useRef(onScroll);
+    onScrollRef.current = onScroll;
+    const onScrollToUpperRef = React.useRef(onScrollToUpper);
+    onScrollToUpperRef.current = onScrollToUpper;
+    const onScrollToLowerRef = React.useRef(onScrollToLower);
+    onScrollToLowerRef.current = onScrollToLower;
+    const thresholdRef = React.useRef({ upper: upperThreshold, lower: lowerThreshold });
+    thresholdRef.current = { upper: upperThreshold, lower: lowerThreshold };
+    const listContentLengthRef = React.useRef(0);
+    const inUpperZoneRef = React.useRef(true);
+    const inLowerZoneRef = React.useRef(false);
+    // 小程序 + 动高（virtual-list 风格）：测量变化后同帧重排，不做程序性 scrollTop 回拉。
+    // 若用户正在滚动（惯性未结束），推迟到滚动停止后再触发，防止内容重排 + setData 同帧
+    // 导致 WeChat scrollAnchoring 失效或传滞后位置造成归顶。
+    const scheduleWeappDynamicReflow = React.useCallback(() => {
+        if (!isWeapp || props.useResizeObserver !== true)
+            return;
+        // 滚动中：仅标记为待处理，等 onScrollEnd / 200ms 超时触发
+        if (isUserScrollingRef.current) {
+            pendingWeappReflowRef.current = true;
+            return;
         }
-    };
-    // 工具：获取 item 尺寸，支持函数/props/默认值
-    const getItemSize = (index) => {
-        if (isHorizontal) {
-            if (typeof props.itemWidth === 'number')
-                return props.itemWidth;
-            if (typeof props.itemSize === 'number')
-                return props.itemSize;
-            if (typeof props.itemSize === 'function')
-                return props.itemSize(index, props.itemData) || DEFAULT_ITEM_WIDTH;
-            return DEFAULT_ITEM_WIDTH;
+        if (sizeCacheRafRef.current != null)
+            return;
+        sizeCacheRafRef.current = requestAnimationFrame(() => {
+            sizeCacheRafRef.current = null;
+            pendingWeappReflowRef.current = false;
+            setSizeCacheVersion((v) => v + 1);
+        });
+    }, [isWeapp, props.useResizeObserver]);
+    // 每次渲染时更新 ref，保证 setTimeout 闭包内拿到最新版本
+    scheduleWeappDynamicReflowRef.current = scheduleWeappDynamicReflow;
+    // ResizeObserver（当启用动态测量时）
+    const resizeObserver = useResizeObserver({
+        enabled: props.useResizeObserver === true,
+        isHorizontal,
+        listId,
+        selectorQueryScope: props.selectorQueryScope,
+        onResize: (index, size) => {
+            var _a;
+            const oldSize = sizeCache.getItemSize(index);
+            sizeCache.setItemSize(index, size);
+            if (Math.abs(oldSize - size) >= 1) {
+                if (isWeapp && props.useResizeObserver === true) {
+                    scheduleWeappDynamicReflow();
+                }
+                else if (sizeCacheRafRef.current == null) {
+                    sizeCacheRafRef.current = requestAnimationFrame(() => {
+                        sizeCacheRafRef.current = null;
+                        setSizeCacheVersion((v) => v + 1);
+                    });
+                }
+            }
+            // 触发 ScrollTop 修正
+            scrollCorrection.recordSizeChange(index, oldSize, size);
+            // 小程序：延迟 onItemSizeChange，避免父组件重渲染导致 List remount
+            // H5：直接回调
+            if (isWeapp) {
+                weappDeferItemSizeChange(index, size, props.onItemSizeChange);
+            }
+            else {
+                (_a = props.onItemSizeChange) === null || _a === void 0 ? void 0 : _a.call(props, index, size);
+            }
         }
-        else {
-            if (typeof props.itemHeight === 'number')
-                return props.itemHeight;
-            if (typeof props.itemSize === 'number')
-                return props.itemSize;
-            if (typeof props.itemSize === 'function')
-                return props.itemSize(index, props.itemData) || DEFAULT_ITEM_HEIGHT;
-            return DEFAULT_ITEM_HEIGHT;
+    });
+    // 嵌套滚动：内层高度变化上报
+    const handleReportNestedHeightChange = React.useCallback((height, index) => {
+        if (height <= 0)
+            return;
+        const estimatedHeader = estimatedSize * 0.5;
+        const fullHeight = height + estimatedHeader;
+        const oldSize = sizeCache.getItemSize(index);
+        if (Math.abs(oldSize - fullHeight) < 1)
+            return;
+        sizeCache.setItemSize(index, fullHeight);
+        scrollCorrection.recordSizeChange(index, oldSize, fullHeight);
+        if (isWeapp && props.useResizeObserver === true) {
+            scheduleWeappDynamicReflow();
         }
-    };
-    // 计算分组累积高度/宽度
+        else if (sizeCacheRafRef.current == null) {
+            sizeCacheRafRef.current = requestAnimationFrame(() => {
+                sizeCacheRafRef.current = null;
+                setSizeCacheVersion((v) => v + 1);
+            });
+        }
+    }, [sizeCache, scrollCorrection, estimatedSize, isWeapp, props.useResizeObserver, scheduleWeappDynamicReflow]);
+    const getDefaultHeaderSize = React.useCallback(() => {
+        const headerSize = normalizeSize(props.headerSize);
+        if (headerSize != null)
+            return headerSize;
+        return resolveItemSizeByIndex(0, defaultItemSize);
+    }, [props.headerSize, resolveItemSizeByIndex, defaultItemSize, normalizeSize]);
+    // 获取 header 尺寸（支持动态测量）
+    const getHeaderSize = React.useCallback((sectionIndex) => {
+        if (props.useResizeObserver === true) {
+            const cached = headerSizeCacheRef.current.get(sectionIndex);
+            if (cached != null && cached > 0)
+                return cached;
+        }
+        return getDefaultHeaderSize();
+    }, [props.useResizeObserver, getDefaultHeaderSize]);
+    const getItemSize = React.useCallback((index) => {
+        if (props.useResizeObserver === true) {
+            return sizeCache.getItemSize(index);
+        }
+        return resolveItemSizeByIndex(index, defaultItemSize);
+    }, [props.useResizeObserver, sizeCache, resolveItemSizeByIndex, defaultItemSize]);
+    // 分组累积高度/宽度，sizeCacheVersion 变化时重算
     const sectionOffsets = React.useMemo(() => {
         const offsets = [0];
-        sections.forEach((section) => {
-            const headerSize = getHeaderSize();
-            const itemSizes = section.items.map((_, i) => getItemSize(i));
+        let globalItemIndex = 0;
+        sections.forEach((section, sectionIdx) => {
+            const headerSize = getHeaderSize(sectionIdx);
+            const itemSizes = section.items.map((_, localIdx) => getItemSize(globalItemIndex + localIdx));
             const groupSize = (section.header ? headerSize : 0) +
                 itemSizes.reduce((a, b) => a + b, 0) +
                 Math.max(0, section.items.length) * space;
             offsets.push(offsets[offsets.length - 1] + groupSize);
+            globalItemIndex += section.items.length;
         });
         return offsets;
-    }, [sections, space, isHorizontal, props.headerHeight, props.headerWidth, props.itemHeight, props.itemWidth, props.itemSize, props.itemData]);
+    }, [sections, space, getItemSize, getHeaderSize, sizeCacheVersion]);
     // 外层虚拟滚动：可见分组
     const [startSection, endSection] = React.useMemo(() => {
         let start = 0;
@@ -151,119 +551,343 @@ const List = (props) => {
         }
         return [start, end];
     }, [renderOffset, containerLength, sectionOffsets, sections.length, cacheCount]);
-    // 触顶/触底事件
-    React.useEffect(() => {
-        if (onScrollToUpper && renderOffset <= (upperThreshold > 0 ? sectionOffsets[upperThreshold] : 0)) {
-            onScrollToUpper();
-        }
-        if (onScrollToLower && renderOffset + containerLength >= sectionOffsets[sectionOffsets.length - 1] - (lowerThreshold > 0 ? sectionOffsets[sectionOffsets.length - 1] - sectionOffsets[sections.length - lowerThreshold] : 0)) {
-            onScrollToLower();
-        }
-    }, [renderOffset, containerLength, sectionOffsets, sections.length, upperThreshold, lowerThreshold, onScrollToUpper, onScrollToLower]);
-    // 处理渲染偏移量更新
-    const updateRenderOffset = React.useCallback((newOffset) => {
-        lastScrollTopRef.current = newOffset;
-        isScrollingRef.current = true;
-        if (scrollTimeoutRef.current) {
-            clearTimeout(scrollTimeoutRef.current);
-        }
-        setRenderOffset(newOffset); // 立即更新渲染偏移量
-        // 平台适配：微信小程序使用延时，其他平台立即更新
-        const isWeapp = process.env.TARO_ENV === 'weapp';
-        if (isWeapp) {
-            // 微信小程序：使用延时避免抖动
-            scrollTimeoutRef.current = setTimeout(() => {
-                isScrollingRef.current = false;
-                setScrollViewOffset(newOffset); // 滚动结束后，同步滚动视图偏移量
-            }, 200);
+    // 视口内可见 item 的全局索引范围（供 onScrollIndex）
+    const [visibleStartItem, visibleEndItem] = React.useMemo(() => {
+        const viewportTop = renderOffset;
+        const viewportBottom = renderOffset + containerLength;
+        let firstVisible = -1;
+        let lastVisible = -1;
+        let globalIndex = 0;
+        for (let s = 0; s < sections.length; s++) {
+            const section = sections[s];
+            const headerSize = getHeaderSize(s);
+            const sectionStart = sectionOffsets[s] + (section.header ? headerSize : 0);
+            let itemTop = sectionStart;
+            for (let i = 0; i < section.items.length; i++) {
+                const itemSize = getItemSize(globalIndex);
+                const itemBottom = itemTop + itemSize;
+                // 判断 item 本身（不含 space）是否与视口相交
+                if (itemBottom > viewportTop && itemTop < viewportBottom) {
+                    if (firstVisible < 0)
+                        firstVisible = globalIndex;
+                    lastVisible = globalIndex;
+                }
+                // 下一个 item 的起始位置 = 当前 item 结束 + space
+                itemTop = itemBottom + space;
+                globalIndex++;
+            }
         }
-        else {
-            // 其他平台：立即更新以获得更好的响应性
-            setScrollViewOffset(newOffset); // 立即更新滚动视图偏移量
-            scrollTimeoutRef.current = setTimeout(() => {
-                isScrollingRef.current = false;
-            }, 200);
+        if (firstVisible < 0 || lastVisible < 0)
+            return [0, 0];
+        return [firstVisible, lastVisible];
+    }, [renderOffset, containerLength, sections, sectionOffsets, getHeaderSize, getItemSize, space]);
+    const lastVisibleRangeRef = React.useRef({ start: -1, end: -1 });
+    React.useEffect(() => {
+        if (props.onScrollIndex) {
+            if (lastVisibleRangeRef.current.start !== visibleStartItem ||
+                lastVisibleRangeRef.current.end !== visibleEndItem) {
+                lastVisibleRangeRef.current = { start: visibleStartItem, end: visibleEndItem };
+                props.onScrollIndex(visibleStartItem, visibleEndItem);
+            }
         }
-    }, []);
-    // 智能滚动处理函数
+    }, [visibleStartItem, visibleEndItem, props.onScrollIndex]);
     const handleScroll = React.useCallback((e) => {
-        // 兼容Stencil版本和React版本的事件结构
+        var _a, _b, _c, _d;
         let newOffset;
         if (e.detail) {
-            // React版本的事件结构
             newOffset = isHorizontal ? e.detail.scrollLeft : e.detail.scrollTop;
         }
         else {
-            // Stencil版本的事件结构
             newOffset = isHorizontal ? e.scrollLeft : e.scrollTop;
         }
-        const diff = newOffset - lastScrollTopRef.current;
+        const effectiveOffset = newOffset;
+        const currentThreshold = thresholdRef.current;
+        const { upper, lower } = currentThreshold;
+        // WeChat 小程序节点不具备 clientHeight/clientWidth，需显式回退到 containerLength state
+        const rawContainerSize = containerRef.current
+            ? (isHorizontal ? containerRef.current.clientWidth : containerRef.current.clientHeight)
+            : null;
+        const currentContainerLength = (typeof rawContainerSize === 'number' && rawContainerSize > 0)
+            ? rawContainerSize
+            : containerLength;
+        const nowInUpper = effectiveOffset <= upper;
+        const currentContentLength = listContentLengthRef.current;
+        const nowInLower = currentContentLength > 0 && effectiveOffset + currentContainerLength >= currentContentLength - lower;
+        const diff = effectiveOffset - lastScrollTopRef.current;
         scrollDiffListRef.current.shift();
         scrollDiffListRef.current.push(diff);
-        // 只保留抖动检测，移除方向检测
-        if (isScrollingRef.current && isShaking(scrollDiffListRef.current)) {
+        const shaking = isScrollingRef.current && isShaking(scrollDiffListRef.current);
+        if (shaking) {
             return;
         }
-        updateRenderOffset(newOffset); // 直接更新渲染偏移量
-        onScroll === null || onScroll === void 0 ? void 0 : onScroll({
-            scrollTop: isHorizontal ? 0 : newOffset,
-            scrollLeft: isHorizontal ? newOffset : 0
-        });
-    }, [isHorizontal, onScroll, updateRenderOffset, containerLength]);
-    // 初始化后的延迟同步 - 确保ScrollView正确设置初始位置
+        if (programmaticCooldownRef.current) {
+            lastScrollTopRef.current = effectiveOffset;
+            setRenderOffset(effectiveOffset);
+            const scrollTop = isHorizontal ? 0 : newOffset;
+            const scrollLeft = isHorizontal ? newOffset : 0;
+            onScroll === null || onScroll === void 0 ? void 0 : onScroll({ scrollTop, scrollLeft, detail: { scrollTop, scrollLeft } });
+            if (nowInUpper && !inUpperZoneRef.current)
+                (_a = onScrollToUpperRef.current) === null || _a === void 0 ? void 0 : _a.call(onScrollToUpperRef);
+            if (nowInLower && !inLowerZoneRef.current)
+                (_b = onScrollToLowerRef.current) === null || _b === void 0 ? void 0 : _b.call(onScrollToLowerRef);
+            inUpperZoneRef.current = nowInUpper;
+            inLowerZoneRef.current = nowInLower;
+            return;
+        }
+        scrollCorrection.markUserScrolling();
+        updateRenderOffset(effectiveOffset, false, 'onScroll');
+        const scrollTop = isHorizontal ? 0 : newOffset;
+        const scrollLeft = isHorizontal ? newOffset : 0;
+        onScroll === null || onScroll === void 0 ? void 0 : onScroll({ scrollTop, scrollLeft, detail: { scrollTop, scrollLeft } });
+        if (nowInUpper && !inUpperZoneRef.current)
+            (_c = onScrollToUpperRef.current) === null || _c === void 0 ? void 0 : _c.call(onScrollToUpperRef);
+        if (nowInLower && !inLowerZoneRef.current)
+            (_d = onScrollToLowerRef.current) === null || _d === void 0 ? void 0 : _d.call(onScrollToLowerRef);
+        inUpperZoneRef.current = nowInUpper;
+        inLowerZoneRef.current = nowInLower;
+    }, [isHorizontal, onScroll, updateRenderOffset, scrollCorrection, props.useResizeObserver, containerLength]);
+    // 小程序：onScrollEnd 优先结束 isUserScrolling，timeout 兜底
+    const handleNativeScrollEnd = React.useCallback(() => {
+        if (isWeapp) {
+            if (scrollTimeoutRef.current) {
+                clearTimeout(scrollTimeoutRef.current);
+                scrollTimeoutRef.current = null;
+            }
+            if (isUserScrollingRef.current) {
+                isScrollingRef.current = false;
+                isUserScrollingRef.current = false;
+                setIsUserScrolling(false);
+                // 滚动结束后触发期间被延迟的 reflow（item 首次测量触发）
+                if (pendingWeappReflowRef.current) {
+                    scheduleWeappDynamicReflowRef.current();
+                }
+            }
+        }
+        onScrollEnd === null || onScrollEnd === void 0 ? void 0 : onScrollEnd();
+    }, [isWeapp, onScrollEnd]);
+    // 暴露 scrollRef 给父组件，供内层 List/WaterFlow 传入 scrollElement
+    React.useLayoutEffect(() => {
+        if (!scrollRefProp)
+            return;
+        const el = useScrollElementMode ? effectiveScrollElement === null || effectiveScrollElement === void 0 ? void 0 : effectiveScrollElement.current : containerRef.current;
+        if (el) {
+            scrollRefProp.current = el;
+        }
+    }, [scrollRefProp, useScrollElementMode, effectiveScrollElement]);
+    // controlledScrollTop 变化时同步到 ScrollView
     React.useEffect(() => {
         if (typeof controlledScrollTop === 'number') {
-            setScrollViewOffset(controlledScrollTop);
+            const sv = scrollViewOffsetRef.current;
+            const same = isWeapp && Math.abs(sv - controlledScrollTop) < 1;
+            if (same) {
+                const intermediate = controlledScrollTop > 0 ? controlledScrollTop - 0.01 : 0.01;
+                setRenderOffset(intermediate);
+                setScrollViewOffset(intermediate);
+                requestAnimationFrame(() => {
+                    setRenderOffset(controlledScrollTop);
+                    setScrollViewOffset(controlledScrollTop);
+                });
+            }
+            else {
+                setRenderOffset(controlledScrollTop);
+                setScrollViewOffset(controlledScrollTop);
+            }
             lastScrollTopRef.current = controlledScrollTop;
+            programmaticScrollRef.current = true;
         }
     }, [controlledScrollTop]);
-    // 清理定时器
+    // 清理定时器、ResizeObserver 与尺寸缓存 RAF（仅在卸载时执行）
     React.useEffect(() => {
         return () => {
             if (scrollTimeoutRef.current) {
                 clearTimeout(scrollTimeoutRef.current);
             }
+            // 小程序端冷却期定时器清理
+            if (isWeapp && programmaticCooldownTimerRef.current) {
+                clearTimeout(programmaticCooldownTimerRef.current);
+            }
+            if (sizeCacheRafRef.current != null) {
+                cancelAnimationFrame(sizeCacheRafRef.current);
+                sizeCacheRafRef.current = null;
+            }
+            resizeObserver.disconnect();
+            scrollCorrection.clearQueue();
         };
     }, []);
-    // 容器样式
-    const containerStyle = Object.assign({ position: 'relative', boxSizing: 'border-box', height: isHorizontal ? width : height, width: isHorizontal ? height : width }, style);
-    // 修改ScrollView组件的props，添加data-testid属性
-    // ScrollView 属性
-    const scrollViewProps = {
-        scrollY: !scrollX && scrollY,
-        scrollX: scrollX,
-        style: containerStyle,
-        enhanced: true,
-        showScrollbar: showScrollbar,
-        onScroll: handleScroll,
-        onScrollToUpper,
-        onScrollToLower,
-        'data-testid': 'taro-list-container'
-    };
-    // 设置ScrollView的滚动位置 - 同时兼容React版本和Stencil版本
-    if (isHorizontal) {
-        scrollViewProps.scrollLeft = scrollViewOffset; // React版本
-        scrollViewProps.mpScrollLeft = scrollViewOffset; // Stencil版本
-    }
-    else {
-        scrollViewProps.scrollTop = scrollViewOffset; // React版本
-        scrollViewProps.mpScrollTop = scrollViewOffset; // Stencil版本
-    }
-    // H5上额外使用DOM直接操作确保滚动位置正确
-    if (isH5) {
-        React.useEffect(() => {
-            if (containerRef.current && typeof scrollViewOffset === 'number') {
-                if (isHorizontal) {
-                    containerRef.current.scrollLeft = scrollViewOffset;
+    // scrollIntoView：仅当 scrollIntoView 变化时执行一次跳动，统一转换为 scrollTop 路径（updateRenderOffset）。
+    const lastScrollIntoViewRef = React.useRef(null);
+    React.useEffect(() => {
+        const targetId = props.scrollIntoView;
+        if (!targetId) {
+            lastScrollIntoViewRef.current = null;
+            return;
+        }
+        if (lastScrollIntoViewRef.current === targetId)
+            return;
+        lastScrollIntoViewRef.current = targetId;
+        let targetIndex = -1;
+        if (targetId.startsWith('list-item-')) {
+            targetIndex = parseInt(targetId.replace('list-item-', ''), 10);
+        }
+        if (targetIndex >= 0 && targetIndex < totalItemCount) {
+            let targetOffset = 0;
+            let currentGlobalIndex = 0;
+            for (let s = 0; s < sections.length; s++) {
+                const section = sections[s];
+                const headerSize = section.header ? getHeaderSize(s) : 0;
+                if (currentGlobalIndex + section.items.length > targetIndex) {
+                    targetOffset += headerSize;
+                    for (let i = 0; i < targetIndex - currentGlobalIndex; i++) {
+                        targetOffset += getItemSize(currentGlobalIndex + i) + space;
+                    }
+                    break;
                 }
                 else {
-                    containerRef.current.scrollTop = scrollViewOffset;
+                    targetOffset += headerSize;
+                    for (let i = 0; i < section.items.length; i++) {
+                        targetOffset += getItemSize(currentGlobalIndex + i) + space;
+                    }
+                    currentGlobalIndex += section.items.length;
+                }
+            }
+            const el = effectiveScrollElement === null || effectiveScrollElement === void 0 ? void 0 : effectiveScrollElement.current;
+            if (useScrollElementMode && el) {
+                const scrollTarget = targetOffset + (isWeapp ? effectiveStartOffsetRef.current : effectiveStartOffset);
+                if (isH5) {
+                    if (isHorizontal) {
+                        el.scrollTo({ left: scrollTarget });
+                    }
+                    else {
+                        el.scrollTo({ top: scrollTarget });
+                    }
+                    updateRenderOffset(targetOffset, true, 'scrollIntoView');
+                }
+                else if (isWeapp) {
+                    const scrollViewId = el.id || `_ls_${listId}`;
+                    if (!el.id)
+                        el.id = scrollViewId;
+                    getScrollViewContextNode(`#${scrollViewId}`).then((node) => {
+                        var _a, _b;
+                        if (isHorizontal) {
+                            (_a = node === null || node === void 0 ? void 0 : node.scrollTo) === null || _a === void 0 ? void 0 : _a.call(node, { left: scrollTarget, animated: false });
+                        }
+                        else {
+                            (_b = node === null || node === void 0 ? void 0 : node.scrollTo) === null || _b === void 0 ? void 0 : _b.call(node, { top: scrollTarget, animated: false });
+                        }
+                        updateRenderOffset(targetOffset, true, 'scrollIntoView');
+                    });
                 }
+                else {
+                    updateRenderOffset(targetOffset, true, 'scrollIntoView');
+                }
+            }
+            else {
+                updateRenderOffset(targetOffset, true, 'scrollIntoView');
+            }
+        }
+    }, [props.scrollIntoView, totalItemCount, sections, getHeaderSize, getItemSize, space, updateRenderOffset, useScrollElementMode, effectiveScrollElement, effectiveStartOffset, effectiveStartOffsetRef, isH5, isWeapp, isHorizontal, listId]);
+    // 容器样式；H5 刷新中禁止滚动
+    const containerStyle = Object.assign(Object.assign({ position: 'relative', boxSizing: 'border-box', height,
+        width }, style), (isH5 && refresherConfig && !supportsNativeRefresher && h5RefresherProps.isRefreshing
+        ? { overflow: 'hidden' }
+        : {}));
+    // ScrollView 属性
+    const scrollViewProps = Object.assign(Object.assign(Object.assign(Object.assign({ scrollY: !scrollX && scrollY, scrollX, style: containerStyle, className, enhanced: true, showScrollbar,
+        upperThreshold,
+        lowerThreshold, scrollWithAnimation: false, onScroll: handleScroll, onScrollStart, onScrollEnd: handleNativeScrollEnd, enableBackToTop }, (isWeapp ? { scrollAnchoring: true } : {})), (typeof cacheExtent === 'number' ? { cacheExtent } : {})), scrollViewRefresherProps), scrollViewRefresherHandlers);
+    // H5 对齐小程序：refresherTriggered=true 时顶部立即显示加载指示器，滚到顶部并锁定滚动直至设为 false
+    React.useEffect(() => {
+        if (!isH5 || !refresherConfig || supportsNativeRefresher || !h5RefresherProps.isRefreshing)
+            return;
+        updateRenderOffset(0, true, 'refresher');
+    }, [h5RefresherProps.isRefreshing, isH5, refresherConfig, supportsNativeRefresher, updateRenderOffset]);
+    // H5 下拉刷新：ref 存 addImperativeTouchListeners，避免 config 变化导致 effect 循环
+    React.useLayoutEffect(() => {
+        const attach = addImperativeTouchListenersRef.current;
+        if (!attach)
+            return;
+        let teardown = null;
+        const tryAttach = () => {
+            const el = useScrollElementMode ? effectiveScrollElement === null || effectiveScrollElement === void 0 ? void 0 : effectiveScrollElement.current : containerRef.current;
+            if (el && !refresherTeardownRef.current) {
+                teardown = attach(el);
+                refresherTeardownRef.current = teardown;
+            }
+        };
+        tryAttach();
+        const rafId = requestAnimationFrame(tryAttach);
+        return () => {
+            cancelAnimationFrame(rafId);
+            if (teardown) {
+                teardown();
+            }
+            refresherTeardownRef.current = null;
+        };
+    }, [useScrollElementMode, effectiveScrollElement]);
+    scrollViewOffsetRef.current = scrollViewOffset;
+    // scrollTop 传递策略（对齐 virtual-list enhanced=true 的做法）：
+    //   - 程序性滚动帧（programmaticScrollRef=true）：传 scrollViewOffset（目标位置）
+    //   - 其余所有帧（用户滚动 / 测量重排 / 空闲）：完全不传，依赖微信原生 + scrollAnchoring
+    //     scrollAnchoring=true 负责在内容重排时自动维持视口位置，避免与显式 scrollTop
+    //     同帧冲突（冲突会导致 scrollAnchoring 失去锚点后归顶）
+    if (isWeapp) {
+        if (programmaticScrollRef.current) {
+            // 程序性滚动（imperative / scrollCorrection / scrollIntoView 等）：传目标位置
+            if (isHorizontal) {
+                scrollViewProps.scrollLeft = scrollViewOffset;
             }
-        }, [scrollViewOffset, isHorizontal]);
+            else {
+                scrollViewProps.scrollTop = scrollViewOffset;
+            }
+            programmaticScrollRef.current = false;
+        }
+        // else：用户滚动 / 空闲帧不传 scrollTop，让微信原生 + scrollAnchoring 完全接管
     }
-    // 总高度/宽度
-    const totalLength = sectionOffsets[sectionOffsets.length - 1];
+    else {
+        // H5：非用户滑动时传
+        if (!isUserScrolling) {
+            if (isHorizontal) {
+                scrollViewProps.scrollLeft = scrollViewOffset;
+            }
+            else {
+                scrollViewProps.scrollTop = scrollViewOffset;
+            }
+        }
+    }
+    // H5：程序性滚动时写回 DOM scrollTop
+    React.useEffect(() => {
+        if (!isH5)
+            return;
+        if (isUserScrolling || !containerRef.current || typeof scrollViewOffset !== 'number')
+            return;
+        if (!programmaticScrollRef.current)
+            return;
+        const scrollValue = scrollViewOffset;
+        if (isHorizontal) {
+            containerRef.current.scrollLeft = scrollValue;
+        }
+        else {
+            containerRef.current.scrollTop = scrollValue;
+        }
+        programmaticScrollRef.current = false;
+    }, [isH5, scrollViewOffset, isHorizontal, isUserScrolling]);
+    // 总高度/宽度（含 NoMore）
+    const noMoreHeight = (noMoreConfig === null || noMoreConfig === void 0 ? void 0 : noMoreConfig.visible) ? (noMoreConfig.height || 60) : 0;
+    const listContentLength = sectionOffsets[sectionOffsets.length - 1] + noMoreHeight;
+    const totalLength = listContentLength;
+    // scrollElement 模式下 onScrollToLower 需用内层内容高度判断，供 scroll handler 读取
+    listContentLengthRef.current = listContentLength;
+    const scrollAttachRefsRef = React.useRef(null);
+    scrollAttachRefsRef.current = {
+        scrollCorrection: scrollCorrectionRef.current,
+        onScroll: onScrollRef.current,
+        onScrollToUpper: onScrollToUpperRef.current,
+        onScrollToLower: onScrollToLowerRef.current,
+        threshold: thresholdRef.current,
+        listContentLength: listContentLengthRef.current,
+    };
+    useListScrollElementAttach(useScrollElementMode && isH5, effectiveScrollElement, effectiveStartOffset, isHorizontal, setContainerLength, updateRenderOffset, scrollRefProp, scrollAttachRefsRef);
+    useListScrollElementAttachWeapp(useScrollElementMode && isWeapp, effectiveScrollElement, effectiveStartOffsetRef, effectiveStartOffset, isHorizontal, setContainerLength, updateRenderOffset, scrollRefProp, scrollAttachRefsRef, initialContainerLength, props.selectorQueryScope);
     // 吸顶/吸左 header
     const stickyHeaderNode = React.useMemo(() => {
         if (!stickyHeader)
@@ -272,33 +896,127 @@ const List = (props) => {
             if (sectionOffsets[i] <= renderOffset && renderOffset < sectionOffsets[i + 1]) {
                 const section = sections[i];
                 if (section.header) {
-                    const headerSize = getHeaderSize();
-                    // 内联样式替代className
-                    const stickyHeaderStyle = Object.assign({ position: 'sticky', top: 0, left: 0, zIndex: 100, background: '#fff', boxSizing: 'border-box', minHeight: '20px', overflow: 'hidden', lineHeight: 1 }, (isHorizontal ? { width: headerSize } : { height: headerSize }));
+                    // 吸顶 header 不设固定 height/width，由内容撑开，避免「外部 60px 容器 + 实际内容 40+px」导致 header 内空白
+                    const stickyHeaderStyle = {
+                        position: 'sticky',
+                        top: 0,
+                        left: 0,
+                        zIndex: 100,
+                        background: '#fff',
+                        boxSizing: 'border-box',
+                        minHeight: 20,
+                        overflow: 'hidden',
+                        lineHeight: 1
+                    };
                     return (jsx(View, { style: stickyHeaderStyle, children: section.header }));
                 }
             }
         }
         return null;
-    }, [stickyHeader, renderOffset, sectionOffsets, sections, isHorizontal, props.headerHeight, props.headerWidth, props.itemHeight, props.itemWidth, props.itemSize, props.itemData]);
+    }, [stickyHeader, renderOffset, sectionOffsets, sections]);
     // 渲染分组+item双层虚拟滚动
     const renderSections = () => {
         const nodes = [];
         let offset = sectionOffsets[startSection];
+        let globalItemIndex = 0; // 全局 item 索引（跨 section）
+        // 计算起始 section 之前的所有 item 数量
+        for (let s = 0; s < startSection; s++) {
+            globalItemIndex += sections[s].items.length;
+        }
         for (let s = startSection; s <= endSection; s++) {
             const section = sections[s];
-            const headerSize = getHeaderSize();
-            const itemSizes = section.items.map((_, i) => getItemSize(i));
+            const headerSize = getHeaderSize(s);
+            const itemSizes = section.items.map((_, i) => getItemSize(globalItemIndex + i));
             // header
             if (section.header) {
-                // 内联样式替代className
+                const sectionIndex = s;
+                // 动态测量时外层定位容器不设固定高度，由内层撑开
                 const sectionHeaderStyle = Object.assign({ position: 'absolute', zIndex: 2, boxSizing: 'border-box', width: '100%', minHeight: '20px', overflow: 'hidden', lineHeight: 1 }, (isHorizontal
-                    ? { top: 0, height: '100%', left: offset, width: headerSize }
-                    : { top: offset, height: headerSize }));
-                nodes.push(React.createElement(View, {
-                    key: section.key + '-header',
-                    style: sectionHeaderStyle,
-                }, section.header));
+                    ? { top: 0, height: '100%', left: offset, width: props.useResizeObserver ? undefined : headerSize }
+                    : { top: offset, height: props.useResizeObserver ? undefined : headerSize }));
+                // header ref 回调（用于 ResizeObserver 测量）
+                const headerRefCallback = props.useResizeObserver ? (el) => {
+                    if (el) {
+                        headerRefsRef.current.set(sectionIndex, el);
+                        resizeObserver.observe(el, -sectionIndex - 1); // 用负数索引区分 header 和 item
+                        const measureAndUpdateHeader = (measured) => {
+                            var _a;
+                            if (measured > 0) {
+                                const oldSize = (_a = headerSizeCacheRef.current.get(sectionIndex)) !== null && _a !== void 0 ? _a : getDefaultHeaderSize();
+                                if (Math.abs(oldSize - measured) >= 1) {
+                                    headerSizeCacheRef.current.set(sectionIndex, measured);
+                                    if (isWeapp && props.useResizeObserver === true) {
+                                        scheduleWeappDynamicReflow();
+                                    }
+                                    else if (sizeCacheRafRef.current == null) {
+                                        sizeCacheRafRef.current = requestAnimationFrame(() => {
+                                            sizeCacheRafRef.current = null;
+                                            setSizeCacheVersion((v) => v + 1);
+                                        });
+                                    }
+                                }
+                            }
+                        };
+                        if (isH5) {
+                            requestAnimationFrame(() => {
+                                if (!headerRefsRef.current.has(sectionIndex))
+                                    return;
+                                const rect = el.getBoundingClientRect();
+                                measureAndUpdateHeader(isHorizontal ? rect.width : rect.height);
+                            });
+                        }
+                        else if (isWeapp) {
+                            Taro.nextTick(() => {
+                                if (!headerRefsRef.current.has(sectionIndex))
+                                    return;
+                                createSelectorQueryScoped(props.selectorQueryScope)
+                                    .select(`#${listId}-list-header-inner-${sectionIndex}`)
+                                    .boundingClientRect((rect) => {
+                                    if (rect) {
+                                        measureAndUpdateHeader(isHorizontal ? rect.width : rect.height);
+                                    }
+                                })
+                                    .exec();
+                            });
+                        }
+                    }
+                    else {
+                        const oldEl = headerRefsRef.current.get(sectionIndex);
+                        if (oldEl) {
+                            resizeObserver.unobserve(oldEl);
+                            headerRefsRef.current.delete(sectionIndex);
+                        }
+                    }
+                } : undefined;
+                // 动态尺寸时：外层定位，内层撑开以便测量
+                const headerContentStyle = props.useResizeObserver
+                    ? (isHorizontal
+                        // weapp 下 max-content 兼容性不稳定，改用 inline-flex 收缩包裹以测得真实宽度
+                        ? (isWeapp
+                            ? { boxSizing: 'border-box', display: 'inline-flex', height: '100%' }
+                            : { boxSizing: 'border-box', width: 'max-content', height: '100%' })
+                        : { boxSizing: 'border-box', width: '100%' })
+                    : {};
+                if (props.useResizeObserver) {
+                    const headerInnerProps = {
+                        ref: headerRefCallback,
+                        style: headerContentStyle,
+                        'data-index': String(-sectionIndex - 1), // 用于 unobserve 获取 index；与 observe(el, -sectionIndex-1) 对应
+                    };
+                    if (isWeapp) {
+                        headerInnerProps.id = `${listId}-list-header-inner-${sectionIndex}`;
+                    }
+                    nodes.push(React.createElement(View, {
+                        key: section.key + '-header',
+                        style: sectionHeaderStyle,
+                    }, React.createElement(View, headerInnerProps, section.header)));
+                }
+                else {
+                    nodes.push(React.createElement(View, {
+                        key: section.key + '-header',
+                        style: sectionHeaderStyle,
+                    }, section.header));
+                }
                 offset += headerSize;
             }
             // item offsets
@@ -318,9 +1036,17 @@ const List = (props) => {
                     break;
                 }
             }
+            // 更新可见起始索引（用于 ScrollCorrection）
+            if (s === startSection && startItem === 0) {
+                visibleStartIndexRef.current = globalItemIndex;
+            }
+            else if (s === startSection) {
+                visibleStartIndexRef.current = globalItemIndex + startItem;
+            }
             // 渲染可见item
             for (let i = startItem; i <= endItem; i++) {
-                // 内联样式替代className
+                const currentGlobalIndex = globalItemIndex + i;
+                const itemId = `list-item-${currentGlobalIndex}`;
                 const sectionItemStyle = Object.assign({ position: 'absolute', zIndex: 1, boxSizing: 'border-box', width: '100%', minHeight: '20px', overflow: 'hidden', lineHeight: 1 }, (isHorizontal
                     ? {
                         top: 0,
@@ -334,17 +1060,208 @@ const List = (props) => {
                         height: itemSizes[i],
                         marginBottom: space
                     }));
-                nodes.push(React.createElement(View, {
+                // ResizeObserver：绑定内层内容容器测量真实尺寸，尺寸变化时才 bump 版本
+                const refCallback = (el) => {
+                    if (el) {
+                        const capturedIndex = currentGlobalIndex;
+                        itemRefsRef.current.set(capturedIndex, el);
+                        resizeObserver.observe(el, capturedIndex);
+                        // H5：使用 getBoundingClientRect 进行 fallback 测量
+                        // 小程序：使用 SelectorQuery 进行 fallback 测量（小程序没有 getBoundingClientRect）
+                        const measureAndUpdate = (measured) => {
+                            var _a;
+                            if (measured > 0) {
+                                const oldSize = sizeCache.getItemSize(capturedIndex);
+                                if (Math.abs(oldSize - measured) < 1)
+                                    return;
+                                sizeCache.setItemSize(capturedIndex, measured);
+                                scrollCorrection.recordSizeChange(capturedIndex, oldSize, measured);
+                                if (isWeapp && props.useResizeObserver === true) {
+                                    scheduleWeappDynamicReflow();
+                                }
+                                else if (sizeCacheRafRef.current == null) {
+                                    sizeCacheRafRef.current = requestAnimationFrame(() => {
+                                        sizeCacheRafRef.current = null;
+                                        setSizeCacheVersion((v) => v + 1);
+                                    });
+                                }
+                                // 小程序：延迟 onItemSizeChange，避免父组件重渲染导致 List remount
+                                if (isWeapp) {
+                                    weappDeferItemSizeChange(capturedIndex, measured, props.onItemSizeChange);
+                                }
+                                else {
+                                    (_a = props.onItemSizeChange) === null || _a === void 0 ? void 0 : _a.call(props, capturedIndex, measured);
+                                }
+                            }
+                        };
+                        if (isH5) {
+                            requestAnimationFrame(() => {
+                                if (!itemRefsRef.current.has(capturedIndex))
+                                    return;
+                                const rect = el.getBoundingClientRect();
+                                measureAndUpdate(isHorizontal ? rect.width : rect.height);
+                            });
+                        }
+                        else if (isWeapp) {
+                            // 小程序端：使用 SelectorQuery 测量内层内容容器的实际尺寸
+                            // 注意：必须选 inner 容器（无固定高度，由内容撑开），不能选 outer（有虚拟列表设置的固定高度）
+                            // 已测量过的 item 跳过，避免 refCallback 重复触发导致无限循环
+                            // 滚动期间跳过 SelectorQuery（不加入 weappMeasuredItemsRef），避免异步查询干扰 scroll-view
+                            // SelectorQuery 是只读查询，滚动期间执行安全
+                            if (shouldMeasureWeappItem(capturedIndex, weappMeasuredItemsRef.current)) {
+                                weappMeasuredItemsRef.current.add(capturedIndex);
+                                // 使用 Taro.nextTick 代替 setTimeout(50)：等待下一帧渲染完成后再测量
+                                // 比固定延时更快（减少"预估→实测"闪烁）且更可靠（保证 DOM 已更新）
+                                Taro.nextTick(() => {
+                                    if (!itemRefsRef.current.has(capturedIndex))
+                                        return;
+                                    createSelectorQueryScoped(props.selectorQueryScope)
+                                        // 页面上可能同时存在多个 List，inner id 必须带 listId 前缀避免跨列表误命中
+                                        .select(`#${listId}-list-item-inner-${capturedIndex}`)
+                                        .boundingClientRect((rect) => {
+                                        if (rect) {
+                                            measureAndUpdate(isHorizontal ? rect.width : rect.height);
+                                        }
+                                    })
+                                        .exec();
+                                });
+                            }
+                        }
+                    }
+                    else {
+                        const oldEl = itemRefsRef.current.get(currentGlobalIndex);
+                        if (oldEl) {
+                            resizeObserver.unobserve(oldEl);
+                            itemRefsRef.current.delete(currentGlobalIndex);
+                        }
+                    }
+                };
+                // 动态尺寸时：外层负责定位，内层由内容撑开以便测量真实尺寸。
+                // 纵向：内层 width:100% 无 height，由内容撑开，测到的是内容高度。
+                // 横向：width:max-content + height:100%：
+                //   - width:max-content 便于测量真实宽度；
+                //   - height:100% 让测量层与外层 slot 条带高度一致，避免「外层条带 180px、内层 wrapper 只有内容高度」导致的内外高度差。
+                const contentWrapperStyle = props.useResizeObserver
+                    ? (isHorizontal
+                        // weapp 下 max-content 兼容性不稳定，改用 inline-flex 收缩包裹以测得真实宽度
+                        ? (isWeapp
+                            ? { boxSizing: 'border-box', display: 'inline-flex', height: '100%' }
+                            : { boxSizing: 'border-box', width: 'max-content', height: '100%' })
+                        : { boxSizing: 'border-box', width: '100%' })
+                    : {};
+                const outerItemProps = {
                     key: section.key + '-item-' + i,
+                    id: itemId,
                     style: sectionItemStyle,
-                }, section.items[i]));
+                };
+                if (props.useResizeObserver) {
+                    const innerProps = {
+                        ref: refCallback,
+                        style: contentWrapperStyle,
+                    };
+                    // 小程序端需要 id 用于 SelectorQuery 测量内容真实尺寸；H5 端不需要（用 getBoundingClientRect）
+                    if (isWeapp) {
+                        // 页面内多 List 并存时避免 id 冲突（例如 demo 同页含多个 List）
+                        innerProps.id = `${listId}-list-item-inner-${currentGlobalIndex}`;
+                    }
+                    innerProps['data-index'] = String(currentGlobalIndex);
+                    const itemNode = React.createElement(View, outerItemProps, React.createElement(View, innerProps, section.items[i]));
+                    // 任务 4.1：当 List 暴露 scrollRef 时，为每个 item 提供 Context，供内层 WaterFlow 使用
+                    const itemWithContext = scrollRefProp && !useScrollElementMode
+                        ? React.createElement(ScrollElementContextOrFallback.Provider, {
+                            key: outerItemProps.key,
+                            value: {
+                                scrollRef: scrollRefProp,
+                                containerHeight: containerLength,
+                                startOffset: offset + itemOffsets[i],
+                                reportNestedHeightChange: props.useResizeObserver
+                                    ? (h) => handleReportNestedHeightChange(h, currentGlobalIndex)
+                                    : undefined,
+                            },
+                        }, itemNode)
+                        : itemNode;
+                    nodes.push(itemWithContext);
+                }
+                else {
+                    const itemNode = React.createElement(View, outerItemProps, section.items[i]);
+                    const itemWithContext = scrollRefProp && !useScrollElementMode
+                        ? React.createElement(ScrollElementContextOrFallback.Provider, {
+                            key: outerItemProps.key,
+                            value: {
+                                scrollRef: scrollRefProp,
+                                containerHeight: containerLength,
+                                startOffset: offset + itemOffsets[i],
+                                reportNestedHeightChange: props.useResizeObserver
+                                    ? (h) => handleReportNestedHeightChange(h, currentGlobalIndex)
+                                    : undefined,
+                            },
+                        }, itemNode)
+                        : itemNode;
+                    nodes.push(itemWithContext);
+                }
             }
+            globalItemIndex += section.items.length;
             offset += itemOffsets[itemOffsets.length - 1];
         }
         return nodes;
     };
-    return (jsx(ScrollView, Object.assign({ ref: containerRef }, scrollViewProps, { children: jsxs(View, { style: isHorizontal ? { width: totalLength, position: 'relative', height: '100%' } : { height: totalLength, position: 'relative', width: '100%' }, children: [stickyHeaderNode, renderSections()] }) })));
+    // 渲染 NoMore 内容
+    const renderNoMoreContent = () => {
+        if (!noMoreConfig || !noMoreConfig.visible)
+            return null;
+        const noMoreHeightValue = noMoreConfig.height || 60;
+        const listContentEnd = sectionOffsets[sectionOffsets.length - 1];
+        const defaultStyle = Object.assign(Object.assign(Object.assign({ position: 'absolute' }, (isHorizontal
+            ? { left: listContentEnd, top: 0, width: noMoreHeightValue, height: '100%' }
+            : { top: listContentEnd, left: 0, width: '100%', height: noMoreHeightValue })), { display: 'flex', alignItems: 'center', justifyContent: 'center', textAlign: 'center', color: '#999', fontSize: '14px', boxSizing: 'border-box' }), noMoreConfig.style);
+        return (jsx(View, { style: defaultStyle, children: noMoreConfig.children || noMoreConfig.text || '没有更多了' }));
+    };
+    // 空列表场景：仅显示 NoMore
+    if (sections.length === 0 && (noMoreConfig === null || noMoreConfig === void 0 ? void 0 : noMoreConfig.visible)) {
+        return (jsx(ScrollView, Object.assign({ ref: containerRef }, scrollViewProps, { children: jsx(View, { style: Object.assign({ minHeight: containerLength, display: 'flex', alignItems: 'center', justifyContent: 'center' }, containerStyle), children: renderNoMoreContent() }) })));
+    }
+    // 可滚区域总尺寸
+    // H5 refresher 用负 translateY 隐藏，有上方混排时可能延伸到 sibling 区域；overflow:hidden 裁剪避免重叠
+    const needsRefresherClip = refresherHeightForH5 > 0;
+    const contentWrapperStyle = isHorizontal
+        ? Object.assign({ width: totalLength, position: 'relative', height: '100%' }, (needsRefresherClip && { overflow: 'hidden' })) : Object.assign({ height: totalLength, position: 'relative', width: '100%' }, (needsRefresherClip && { overflow: 'hidden' }));
+    const listWrapperStyle = isHorizontal
+        ? { width: listContentLength, position: 'relative', height: '100%' }
+        : { height: listContentLength, position: 'relative', width: '100%' };
+    const pullTranslate = refresherHeightForH5 > 0 && h5RefresherProps.pullDistance !== 0
+        ? { transform: `translateY(${h5RefresherProps.pullDistance}px)` }
+        : {};
+    const h5RefresherTranslateY = -refresherHeightForH5 + h5RefresherProps.pullDistance;
+    // 内容区域渲染
+    const renderContentArea = () => {
+        var _a, _b;
+        return (jsx(View, { style: contentWrapperStyle, children: refresherHeightForH5 > 0 ? (jsxs(Fragment, { children: [jsx(View, { style: {
+                            position: 'absolute',
+                            top: 0,
+                            left: 0,
+                            right: 0,
+                            height: refresherHeightForH5,
+                            zIndex: 0,
+                            transform: `translateY(${h5RefresherTranslateY}px)`,
+                        }, children: renderRefresherContent() }), jsxs(View, { style: Object.assign(Object.assign(Object.assign({}, listWrapperStyle), pullTranslate), { zIndex: 1, background: (_b = (_a = style === null || style === void 0 ? void 0 : style.background) !== null && _a !== void 0 ? _a : style === null || style === void 0 ? void 0 : style.backgroundColor) !== null && _b !== void 0 ? _b : '#fff' }), children: [stickyHeaderNode, renderSections(), renderNoMoreContent()] })] })) : (jsxs(Fragment, { children: [!supportsNativeRefresher && renderRefresherContent(), stickyHeaderNode, renderSections(), renderNoMoreContent()] })) }));
+    };
+    // useScrollElementMode 或 needAutoFind&&pending：渲染 View 以便监听外部滚动或 probe 阶段查找滚动父节点
+    const renderView = useScrollElementMode || (!!needAutoFind && autoFindStatus === 'pending');
+    if (renderView) {
+        // 任务 2.4：恢复 refresher DOM 结构（refresher 层 + listWrapperStyle）
+        return (jsx(View, { ref: contentWrapperRef, id: contentId, style: contentWrapperStyle, children: refresherHeightForH5 > 0 ? (jsxs(Fragment, { children: [jsx(View, { style: {
+                            position: 'absolute',
+                            top: 0,
+                            left: 0,
+                            right: 0,
+                            height: refresherHeightForH5,
+                            zIndex: 0,
+                            transform: `translateY(${h5RefresherTranslateY}px)`,
+                        }, children: renderRefresherContent() }), jsxs(View, { style: Object.assign(Object.assign(Object.assign({}, listWrapperStyle), pullTranslate), { zIndex: 1, background: (_b = (_a = style === null || style === void 0 ? void 0 : style.background) !== null && _a !== void 0 ? _a : style === null || style === void 0 ? void 0 : style.backgroundColor) !== null && _b !== void 0 ? _b : '#fff' }), children: [stickyHeaderNode, renderSections(), renderNoMoreContent()] })] })) : (jsxs(Fragment, { children: [stickyHeaderNode, renderSections(), renderNoMoreContent()] })) }));
+    }
+    return (jsxs(ScrollView, Object.assign({ ref: containerRef }, scrollViewProps, { id: listId, children: [supportsNativeRefresher && renderRefresherContent(), renderContentArea()] })));
 };
+const List = React.forwardRef(InnerList);
 
-export { List, ListItem, StickyHeader, StickySection, accumulate, List as default, isShaking };
+export { List, ListItem, ScrollElementContextOrFallback as ListScrollElementContext, NoMore, StickyHeader, StickySection, accumulate, List as default, isShaking };
 //# sourceMappingURL=index.js.map