@tarojs/components-advanced 4.1.12-beta.5 → 4.1.12-beta.51

package/dist/components/list/index.js

@@ -2,17 +2,22 @@ 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 { useRefresher, DEFAULT_REFRESHER_HEIGHT } from './hooks/useRefresher.js';
+import { useListNestedScroll } from './hooks/useListNestedScroll.js';
+import { useListScrollElementAttach } from './hooks/useListScrollElementAttach.js';
+import { useListScrollElementAttachWeapp } from './hooks/useListScrollElementAttachWeapp.js';
+import { useRefresher } 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, isH5, supportsNativeRefresher } from './utils.js';
+import { isWeapp, createSelectorQueryForRef, 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++) {
@@ -20,19 +25,15 @@ 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;
 }
 // 小程序端：判断 item 是否应该执行 SelectorQuery 测量（仅检查是否已测量过）
@@ -42,12 +43,53 @@ function shouldMeasureWeappItem(index, measuredSet) {
 }
 // 小程序端暂不外抛 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;
-    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, } = props;
+    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);
     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）
@@ -78,6 +120,22 @@ const InnerList = (props, ref) => {
         ro.observe(el);
         return () => ro.disconnect();
     }, [isHorizontal]);
+    // WeChat 小程序：没有原生 ResizeObserver，用 SelectorQuery 一次性测量容器高度
+    React.useEffect(() => {
+        if (!isWeapp)
+            return;
+        Taro.nextTick(() => {
+            createSelectorQueryForRef(containerRef)
+                .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);
@@ -89,6 +147,10 @@ const InnerList = (props, ref) => {
     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，避免「传滞后值拉回」和「从有到无归顶」。
@@ -109,7 +171,10 @@ const InnerList = (props, ref) => {
             if (needForce) {
                 const intermediate = newOffset > 0 ? newOffset - 0.01 : 0.01;
                 setScrollViewOffset(intermediate);
+                programmaticScrollRef.current = true;
                 requestAnimationFrame(() => {
+                    // 第二帧也需要标记为程序性滚动，否则 else 分支不会传 scrollTop
+                    programmaticScrollRef.current = true;
                     setScrollViewOffset(newOffset);
                 });
             }
@@ -140,39 +205,52 @@ const InnerList = (props, ref) => {
                 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 opts = options !== null && options !== void 0 ? options : {};
-            const isHorizontal = scrollX === true;
-            const top = typeof opts.top === 'number' ? opts.top : undefined;
-            const left = typeof opts.left === 'number' ? opts.left : undefined;
-            let targetOffset = 0;
-            if (isHorizontal) {
-                if (typeof left === 'number') {
-                    targetOffset = left;
+            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 if (typeof top === 'number') {
-                    targetOffset = top;
+                else {
+                    el.scrollTo({ top: scrollTarget });
                 }
+                updateRenderOffset(targetOffset, false, 'scrollElement');
             }
-            else {
-                if (typeof top === 'number') {
-                    targetOffset = top;
-                }
-                else if (typeof left === 'number') {
-                    targetOffset = left;
-                }
+            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');
+                });
             }
-            if (!Number.isFinite(targetOffset)) {
-                targetOffset = 0;
+            else {
+                updateRenderOffset(targetOffset, true, 'imperative');
             }
-            updateRenderOffset(targetOffset, true, 'imperative');
         },
-    }), [scrollX, updateRenderOffset]);
+    }), [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);
@@ -254,7 +332,9 @@ const InnerList = (props, ref) => {
         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);
+    const { scrollViewRefresherProps, scrollViewRefresherHandlers, h5RefresherProps, addImperativeTouchListeners, renderRefresherContent, slotHeight: h5RefresherSlotHeight, } = 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, !!(isH5 && refresherConfig && !supportsNativeRefresher && refresherConfig.refresherEnabled !== false));
     const refresherTeardownRef = React.useRef(null);
     const addImperativeTouchListenersRef = React.useRef(addImperativeTouchListeners);
     addImperativeTouchListenersRef.current = addImperativeTouchListeners;
@@ -262,16 +342,16 @@ const InnerList = (props, ref) => {
         if (refresherTeardownRef.current)
             refresherTeardownRef.current();
     }, []);
-    // H5 下拉刷新顶栏高度（默认 50px，来自 useRefresher）
-    const refresherHeightForH5 = (isH5 && refresherConfig && !supportsNativeRefresher && refresherConfig.refresherEnabled !== false) ? DEFAULT_REFRESHER_HEIGHT : 0;
-    // 解析分组结构，只支持 StickySection 和 ListItem 作为直接子组件
-    // 过滤掉 Refresher 和 NoMore 组件
+    // H5 下拉刷新顶栏高度：自定义内容由 useRefresher 内 ResizeObserver 测量，否则默认 50
+    const refresherHeightForH5 = (isH5 && refresherConfig && !supportsNativeRefresher && refresherConfig.refresherEnabled !== false)
+        ? h5RefresherSlotHeight
+        : 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 = [];
@@ -284,10 +364,8 @@ const InnerList = (props, ref) => {
                 result.push({ header, items, key: child.key || String(idx) });
             }
             else if (React.isValidElement(child) && child.type === ListItem) {
-                // 普通 ListItem
                 defaultItems.push(child);
             }
-            // 忽略 Refresher 和 NoMore 组件（已在上面提取配置）
         });
         if (defaultItems.length > 0) {
             result.push({ header: null, items: defaultItems, key: 'default' });
@@ -295,8 +373,7 @@ const InnerList = (props, ref) => {
         return result;
     }, [children]);
     // 动态尺寸管理
-    const defaultEstimatedSize = isHorizontal ? DEFAULT_ITEM_WIDTH : DEFAULT_ITEM_HEIGHT;
-    const estimatedSize = (_a = props.estimatedItemSize) !== null && _a !== void 0 ? _a : defaultEstimatedSize;
+    const estimatedSize = resolveItemSizeByIndex(0, defaultItemSize);
     // 计算总 item 数量（跨所有 section）
     const totalItemCount = React.useMemo(() => {
         return sections.reduce((sum, section) => sum + section.items.length, 0);
@@ -310,17 +387,17 @@ const InnerList = (props, ref) => {
     // 动态尺寸缓存更新版本：setItemSize 后递增，用于驱动 sectionOffsets/totalLength 与 item 定位重算
     const [sizeCacheVersion, setSizeCacheVersion] = React.useState(0);
     const sizeCacheRafRef = React.useRef(null);
-    // 小程序端：测量触发 re-render 时，reflow 帧传 eff 并同步 scrollViewOffset，避免下一帧传 0 导致跳变
-    const measureScrollProtectRef = React.useRef(false);
+    // （measureScrollProtectRef 已移除：scrollTop + 内容变更同帧 setData 会与 scrollAnchoring
+    //  冲突导致归顶；改由 scrollAnchoring=true 独立处理内容重排，无需显式传 scrollTop 保护）
     // 动态尺寸缓存
     const sizeCache = useItemSizeCache({
         isHorizontal,
-        estimatedItemSize: estimatedSize,
+        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;
@@ -334,23 +411,46 @@ const InnerList = (props, ref) => {
             updateRenderOffset(newOffset, true, 'scrollCorrection'); // 程序性修正需同步到 ScrollView
         }
     });
-    // 小程序 + 动高（virtual-list 风格）：测量变化后同帧重排，不做程序性 scrollTop 回拉
+    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;
+        }
         if (sizeCacheRafRef.current != null)
             return;
         sizeCacheRafRef.current = requestAnimationFrame(() => {
             sizeCacheRafRef.current = null;
-            measureScrollProtectRef.current = true;
+            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,
+        listViewportRef: containerRef,
         onResize: (index, size) => {
             var _a;
             const oldSize = sizeCache.getItemSize(index);
@@ -378,85 +478,63 @@ const InnerList = (props, ref) => {
             }
         }
     });
-    // 工具：获取 header 默认/估算尺寸
-    const getDefaultHeaderSize = () => {
-        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 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 (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;
+        else if (sizeCacheRafRef.current == null) {
+            sizeCacheRafRef.current = requestAnimationFrame(() => {
+                sizeCacheRafRef.current = null;
+                setSizeCacheVersion((v) => v + 1);
+            });
         }
-    };
-    // 工具：获取 header 尺寸（支持动态测量）
+    }, [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, props.headerHeight, props.headerWidth, props.itemHeight, props.itemWidth, props.itemSize, props.itemData, isHorizontal]);
-    // 工具：获取 item 尺寸，支持函数/props/默认值/动态测量
+    }, [props.useResizeObserver, getDefaultHeaderSize]);
     const getItemSize = React.useCallback((index) => {
-        // 优先级1：如果启用动态测量，从缓存读取
         if (props.useResizeObserver === true) {
             return sizeCache.getItemSize(index);
         }
-        // 优先级2：固定尺寸或函数计算
-        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;
-        }
-        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;
-        }
-    }, [props.useResizeObserver, props.itemWidth, props.itemHeight, props.itemSize, props.itemData, isHorizontal, sizeCache]);
+        return resolveItemSizeByIndex(index, defaultItemSize);
+    }, [props.useResizeObserver, sizeCache, resolveItemSizeByIndex, defaultItemSize]);
     // 分组累积高度/宽度，sizeCacheVersion 变化时重算
     const sectionOffsets = React.useMemo(() => {
         const offsets = [0];
-        let globalItemIndex = 0; // 累加全局索引
+        let globalItemIndex = 0;
         sections.forEach((section, sectionIdx) => {
             const headerSize = getHeaderSize(sectionIdx);
-            // 使用全局索引计算每个 item 的尺寸
             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);
-            // 累加当前 section 的 item 数量
             globalItemIndex += section.items.length;
         });
         return offsets;
-    }, [sections, space, isHorizontal, props.headerHeight, props.headerWidth, props.itemHeight, props.itemWidth, props.itemSize, props.itemData, getItemSize, getHeaderSize, sizeCacheVersion]);
+    }, [sections, space, getItemSize, getHeaderSize, sizeCacheVersion]);
     // 外层虚拟滚动：可见分组
     const [startSection, endSection] = React.useMemo(() => {
         let start = 0;
@@ -505,11 +583,9 @@ const InnerList = (props, ref) => {
             return [0, 0];
         return [firstVisible, lastVisible];
     }, [renderOffset, containerLength, sections, sectionOffsets, getHeaderSize, getItemSize, space]);
-    // 触发 onScrollIndex 回调（带防重复）
     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 };
@@ -518,6 +594,7 @@ const InnerList = (props, ref) => {
         }
     }, [visibleStartItem, visibleEndItem, props.onScrollIndex]);
     const handleScroll = React.useCallback((e) => {
+        var _a, _b, _c, _d;
         let newOffset;
         if (e.detail) {
             newOffset = isHorizontal ? e.detail.scrollLeft : e.detail.scrollTop;
@@ -526,28 +603,51 @@ const InnerList = (props, ref) => {
             newOffset = isHorizontal ? e.scrollLeft : e.scrollTop;
         }
         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);
         const shaking = isScrollingRef.current && isShaking(scrollDiffListRef.current);
-        if (shaking)
+        if (shaking) {
             return;
+        }
         if (programmaticCooldownRef.current) {
             lastScrollTopRef.current = effectiveOffset;
             setRenderOffset(effectiveOffset);
-            onScroll === null || onScroll === void 0 ? void 0 : onScroll({
-                scrollTop: isHorizontal ? 0 : newOffset,
-                scrollLeft: isHorizontal ? newOffset : 0
-            });
+            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');
-        onScroll === null || onScroll === void 0 ? void 0 : onScroll({
-            scrollTop: isHorizontal ? 0 : newOffset,
-            scrollLeft: isHorizontal ? newOffset : 0
-        });
-    }, [isHorizontal, onScroll, updateRenderOffset, scrollCorrection, props.useResizeObserver]);
+        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) {
@@ -559,11 +659,23 @@ const InnerList = (props, ref) => {
                 isScrollingRef.current = false;
                 isUserScrollingRef.current = false;
                 setIsUserScrolling(false);
-                // recycle-view 策略：不把用户滑动位置同步到 scrollViewOffset
+                // 滚动结束后触发期间被延迟的 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') {
@@ -640,20 +752,51 @@ const InnerList = (props, ref) => {
                     currentGlobalIndex += section.items.length;
                 }
             }
-            updateRenderOffset(targetOffset, true, 'scrollIntoView');
+            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]);
+    }, [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(Object.assign({ scrollY: !scrollX && scrollY, scrollX, style: containerStyle, className, enhanced: true, showScrollbar,
+    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, onScrollToUpper,
-        onScrollToLower,
-        onScrollStart, onScrollEnd: handleNativeScrollEnd, enableBackToTop }, (isWeapp ? { scrollAnchoring: true } : {})), (typeof cacheExtent === 'number' ? { cacheExtent } : {})), { 'data-testid': 'taro-list-container' }), scrollViewRefresherProps), scrollViewRefresherHandlers);
+        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)
@@ -667,7 +810,7 @@ const InnerList = (props, ref) => {
             return;
         let teardown = null;
         const tryAttach = () => {
-            const el = containerRef.current;
+            const el = useScrollElementMode ? effectiveScrollElement === null || effectiveScrollElement === void 0 ? void 0 : effectiveScrollElement.current : containerRef.current;
             if (el && !refresherTeardownRef.current) {
                 teardown = attach(el);
                 refresherTeardownRef.current = teardown;
@@ -682,32 +825,25 @@ const InnerList = (props, ref) => {
             }
             refresherTeardownRef.current = null;
         };
-    }, []);
+    }, [useScrollElementMode, effectiveScrollElement]);
     scrollViewOffsetRef.current = scrollViewOffset;
-    // scrollTop：weapp 传 scrollViewOffset（reflow 帧传 eff 防跳变）；H5 仅非用户滑动时传
+    // scrollTop 传递策略（对齐 virtual-list enhanced=true 的做法）：
+    //   - 程序性滚动帧（programmaticScrollRef=true）：传 scrollViewOffset（目标位置）
+    //   - 其余所有帧（用户滚动 / 测量重排 / 空闲）：完全不传，依赖微信原生 + scrollAnchoring
+    //     scrollAnchoring=true 负责在内容重排时自动维持视口位置，避免与显式 scrollTop
+    //     同帧冲突（冲突会导致 scrollAnchoring 失去锚点后归顶）
     if (isWeapp) {
-        if (measureScrollProtectRef.current) {
-            measureScrollProtectRef.current = false;
-            const eff = lastScrollTopRef.current;
-            setScrollViewOffset(eff);
-            if (isHorizontal) {
-                scrollViewProps.scrollLeft = eff;
-            }
-            else {
-                scrollViewProps.scrollTop = eff;
-            }
-            programmaticScrollRef.current = false;
-        }
-        else {
-            const sv = scrollViewOffset;
+        if (programmaticScrollRef.current) {
+            // 程序性滚动（imperative / scrollCorrection / scrollIntoView 等）：传目标位置
             if (isHorizontal) {
-                scrollViewProps.scrollLeft = sv;
+                scrollViewProps.scrollLeft = scrollViewOffset;
             }
             else {
-                scrollViewProps.scrollTop = sv;
+                scrollViewProps.scrollTop = scrollViewOffset;
             }
             programmaticScrollRef.current = false;
         }
+        // else：用户滚动 / 空闲帧不传 scrollTop，让微信原生 + scrollAnchoring 完全接管
     }
     else {
         // H5：非用户滑动时传
@@ -741,6 +877,19 @@ const InnerList = (props, ref) => {
     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);
     // 吸顶/吸左 header
     const stickyHeaderNode = React.useMemo(() => {
         if (!stickyHeader)
@@ -766,7 +915,7 @@ const InnerList = (props, ref) => {
             }
         }
         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 = [];
@@ -822,7 +971,7 @@ const InnerList = (props, ref) => {
                             Taro.nextTick(() => {
                                 if (!headerRefsRef.current.has(sectionIndex))
                                     return;
-                                Taro.createSelectorQuery()
+                                createSelectorQueryForRef({ current: el })
                                     .select(`#${listId}-list-header-inner-${sectionIndex}`)
                                     .boundingClientRect((rect) => {
                                     if (rect) {
@@ -968,7 +1117,7 @@ const InnerList = (props, ref) => {
                                 Taro.nextTick(() => {
                                     if (!itemRefsRef.current.has(capturedIndex))
                                         return;
-                                    Taro.createSelectorQuery()
+                                    createSelectorQueryForRef({ current: el })
                                         // 页面上可能同时存在多个 List，inner id 必须带 listId 前缀避免跨列表误命中
                                         .select(`#${listId}-list-item-inner-${capturedIndex}`)
                                         .boundingClientRect((rect) => {
@@ -1018,10 +1167,39 @@ const InnerList = (props, ref) => {
                         innerProps.id = `${listId}-list-item-inner-${currentGlobalIndex}`;
                     }
                     innerProps['data-index'] = String(currentGlobalIndex);
-                    nodes.push(React.createElement(View, outerItemProps, React.createElement(View, innerProps, section.items[i])));
+                    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 {
-                    nodes.push(React.createElement(View, outerItemProps, section.items[i]));
+                    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;
@@ -1038,16 +1216,17 @@ const InnerList = (props, ref) => {
         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, "data-testid": "list-nomore", children: noMoreConfig.children || noMoreConfig.text || '没有更多了' }));
+        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
-        ? { width: totalLength, position: 'relative', height: '100%' }
-        : { height: totalLength, position: 'relative', width: '100%' };
+        ? 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%' };
@@ -1068,9 +1247,23 @@ const InnerList = (props, ref) => {
                             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, NoMore, 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