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

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 { supportsNativeRefresher } from './utils.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++) {
@@ -20,77 +25,86 @@ 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 测量（仅检查是否已测量过）
 // SelectorQuery 是只读查询，不会触发 setData，滚动期间执行是安全的
-// 真正需要延迟的是 sizeCacheVersion bump（由 weappSizeCacheVersionBump 负责）
 function shouldMeasureWeappItem(index, measuredSet) {
     return !measuredSet.has(index);
 }
-// 小程序端（定高路径）：滚动期间延迟 sizeCacheVersion bump，停止后再 flush。
-// 动高路径已改为“测量即重排、原生滚动主导”，不走该事务。
-function weappSizeCacheVersionBump(isUserScrollingRef, pendingBumpRef, measureScrollProtectRef, setSizeCacheVersion) {
-    if (isUserScrollingRef.current) {
-        pendingBumpRef.current = true;
-        return;
-    }
-    measureScrollProtectRef.current = true;
-    setSizeCacheVersion((v) => v + 1);
-}
-// 小程序端：onItemSizeChange 空置（稳定性优先，不向父层外抛）
-function weappDeferItemSizeChange(_isUserScrollingRef, _pendingSizeChangesRef, _index, _size, _onItemSizeChange) {
-    // 回退到稳定策略：小程序端暂不外抛 onItemSizeChange，
-    // 避免父层重渲染/remount 导致回顶或空白。
-}
-// 小程序端（定高路径）：记录滚动期间的测量变化，用于 flush 时计算滚动修正量
-// 使用 Map 去重：同一个 index 多次测量时，保留 originalOldSize（首次）和 latestNewSize（最新）
-function weappRecordMeasurement(pendingMeasurementsRef, index, oldSize, newSize) {
-    const existing = pendingMeasurementsRef.current.get(index);
-    if (existing) {
-        existing.latestNewSize = newSize;
+// 小程序端暂不外抛 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 {
-        pendingMeasurementsRef.current.set(index, { originalOldSize: oldSize, latestNewSize: newSize });
+        if (typeof top === 'number')
+            result = top;
+        else if (typeof left === 'number')
+            result = left;
     }
+    return Number.isFinite(result) ? result : 0;
 }
-// 小程序动高：非 flush 的 measureProtect 帧回传一次当前 offset，避免原生短暂归 0
+// eslint-disable-next-line complexity -- List 多端/多模式逻辑集中，已抽离 useListNestedScroll、useListScrollElementAttach、resolveScrollTargetOffset 等
 const InnerList = (props, ref) => {
-    var _a;
-    const isH5 = process.env.TARO_ENV === 'h5';
-    const isWeapp = process.env.TARO_ENV === 'weapp';
-    const { stickyHeader = false, space = 0, height = 400, width = '100%', showScrollbar = true, scrollTop: controlledScrollTop, scrollX = false, scrollY = true, onScroll, onScrollToUpper, onScrollToLower, onScrollStart, onScrollEnd, upperThreshold = 0, lowerThreshold = 0, 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, 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);
-    // 滚动视图偏移量 - 仅用于程序性滚动（scrollIntoView/修正/初始），用户滑动期间不更新，避免「受控 scrollTop」与原生滚动抢位置导致果冻感
+    // 程序性滚动用的目标偏移；用户滑动期间不更新，避免与原生滚动冲突
     const [scrollViewOffset, setScrollViewOffset] = React.useState(controlledScrollTop !== null && controlledScrollTop !== void 0 ? controlledScrollTop : 0);
     // 用户正在滑动时不再向 ScrollView 传 scrollTop，让滚动完全由原生接管
     const [isUserScrolling, setIsUserScrolling] = React.useState(false);
-    // isUserScrolling 的 ref 镜像，供 RAF 回调等异步上下文中读取最新值（避免闭包捕获过期状态）
+    // 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 实际高度不一致」导致底部空白（虚拟列表视口 [renderOffset, renderOffset+containerLength] 小于实际可见区域）
+    // 用容器实际尺寸更新视口长度，避免 props 与 CSS 不一致导致底部空白
     React.useEffect(() => {
         const el = containerRef.current;
         if (!el || typeof ResizeObserver === 'undefined')
@@ -106,31 +120,41 @@ const InnerList = (props, ref) => {
         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);
-    // 小程序端：记录最近一次 scroll 事件时间，供微动静止检测使用
-    const lastScrollEventAtRef = React.useRef(Date.now());
-    // 小程序端：微动静止检测定时器（仅在存在 pending 测量时启动）
-    const settleCheckTimerRef = React.useRef(null);
-    const settleLastOffsetRef = React.useRef(controlledScrollTop !== null && controlledScrollTop !== void 0 ? controlledScrollTop : 0);
-    const settleStillCountRef = React.useRef(0);
-    // 仅程序性滚动（scrollIntoView/修正/初始）时才把 scrollViewOffset 写回 H5 DOM，避免用户拖动结束后误把旧值写回导致卡顿/跳跃（在桌面 Chrome 模拟器下尤为明显）
+    // H5：仅程序性滚动时写回 DOM scrollTop，用户滑动结束后不写回避免卡顿
     const programmaticScrollRef = React.useRef(false);
-    // 小程序端：记录最近一次程序性滚动目标，用于过滤回调中的异常“回顶”噪声
-    const programmaticTargetOffsetRef = React.useRef(null);
-    const suppressResetUntilRef = React.useRef(0);
-    // guard 兜底回补节流，避免异常回顶事件频繁触发重复回补
-    const guardHealAtRef = React.useRef(0);
-    // 程序性滚动冷却期：在此期间内 handleScroll 不设置同步定时器，避免 scrollIntoView 后被原生 scroll 回调"拉回"
+    // 小程序端程序性滚动冷却期：handleScroll 只更新 renderOffset，避免 scrollIntoView 后被原生回调拉回
     const programmaticCooldownRef = React.useRef(false);
     const programmaticCooldownTimerRef = React.useRef(null);
-    // 处理渲染偏移量更新。策略：滑动中不同步 scrollViewOffset（避免果冻感），滚动结束后再同步。
-    // syncToScrollView=true：程序性滚动（scrollIntoView/修正/初始），立即同步到 ScrollView。
-    // syncToScrollView=false：用户滑动，仅更新 renderOffset；结束 150/200ms 后再同步 scrollViewOffset。
-    const updateRenderOffset = React.useCallback((newOffset, syncToScrollView) => {
+    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) {
@@ -140,21 +164,31 @@ const InnerList = (props, ref) => {
         if (syncToScrollView) {
             isUserScrollingRef.current = false;
             setIsUserScrolling(false);
-            setScrollViewOffset(newOffset);
+            // 小程序：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;
-            // 小程序端：程序性滚动开启冷却期，在冷却期内忽略 handleScroll 中的同步逻辑，避免被原生 scroll 回调"拉回"
-            // H5 端已稳定，不启用冷却期
             if (isWeapp) {
-                programmaticTargetOffsetRef.current = newOffset;
-                suppressResetUntilRef.current = Date.now() + 700;
                 programmaticCooldownRef.current = true;
                 if (programmaticCooldownTimerRef.current) {
                     clearTimeout(programmaticCooldownTimerRef.current);
                 }
                 programmaticCooldownTimerRef.current = setTimeout(() => {
                     programmaticCooldownRef.current = false;
-                    programmaticTargetOffsetRef.current = null;
-                    suppressResetUntilRef.current = 0;
                 }, 500);
             }
         }
@@ -165,44 +199,59 @@ const InnerList = (props, ref) => {
         scrollTimeoutRef.current = setTimeout(() => {
             isScrollingRef.current = false;
             if (!syncToScrollView) {
-                // 滚动结束后同步：state 与真实滚动位置一致，下次程序性滚动有正确基准
                 isUserScrollingRef.current = false;
-                setScrollViewOffset(lastScrollTopRef.current);
                 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 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);
         },
-    }), [scrollX, updateRenderOffset]);
-    // 提取 Refresher 配置（方案一：List 自身属性为 base，Refresher 子覆盖，对齐 dynamic/harmony）
+    }), [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
@@ -220,7 +269,6 @@ const InnerList = (props, ref) => {
                 onRefresherStatusChange: props.onRefresherStatusChange,
             }
             : null;
-        // 通过 displayName 检测 Refresher 子组件（保持与 Refresher 组件解耦）
         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';
@@ -268,7 +316,8 @@ const InnerList = (props, ref) => {
                 if (noMoreCount > 1) {
                     return;
                 }
-                config = child.props;
+                const childProps = child.props;
+                config = Object.assign(Object.assign({}, childProps), { visible: childProps.visible !== false });
             }
         });
         // Props 方式转换为配置（优先级低于子组件）
@@ -282,8 +331,10 @@ const InnerList = (props, ref) => {
         }
         return config;
     }, [children, props.showNoMore, props.noMoreText, props.noMoreStyle, props.renderNoMore]);
-    // 使用 Refresher hook（平台适配）；H5 用 addImperativeTouchListeners 挂 { passive: false }，避免 preventDefault 报错
-    const { scrollViewRefresherProps, scrollViewRefresherHandlers, h5RefresherProps, addImperativeTouchListeners, renderRefresherContent, } = useRefresher(refresherConfig, isH5 && refresherConfig && !supportsNativeRefresher ? 0 : renderOffset);
+    // Refresher 平台适配：H5 用 addImperativeTouchListeners
+    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;
@@ -291,17 +342,16 @@ const InnerList = (props, ref) => {
         if (refresherTeardownRef.current)
             refresherTeardownRef.current();
     }, []);
-    // H5 下拉刷新时顶部 Refresher 块高度（用于总高、scroll 偏移、内容跟随手指 wrapper）；refresherEnabled=false 时不展示顶栏
-    // 默认 50px（常量来自 useRefresher），有自定义 children 时由 renderRefresherContent 内容撑开
-    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 = [];
@@ -314,19 +364,16 @@ 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' });
         }
         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);
@@ -340,129 +387,83 @@ const InnerList = (props, ref) => {
     // 动态尺寸缓存更新版本：setItemSize 后递增，用于驱动 sectionOffsets/totalLength 与 item 定位重算
     const [sizeCacheVersion, setSizeCacheVersion] = React.useState(0);
     const sizeCacheRafRef = React.useRef(null);
-    // 小程序端：测量触发 re-render 时，保护 scroll-top 不被重置的标记
-    // 仅在 RAF 回调（测量完成后）设为 true，在 render 阶段读取并自消费（设为 false）
-    const measureScrollProtectRef = React.useRef(false);
-    // 小程序端（定高路径）：滚动期间 sizeCacheVersion bump 被延迟，此标记记录有 pending bump 需要 flush
-    const pendingBumpRef = React.useRef(false);
-    // 定高路径：flush 后需要在下一帧恢复滚动位置（存储目标 scrollTop，null 表示无需恢复）
-    const scrollRestoreRef = React.useRef(null);
-    // 定高路径：restore 来源滚动位置（用于判断 restore 是否过期）
-    const scrollRestoreFromRef = React.useRef(null);
-    // 小程序端（定高路径）：flush 恢复窗口标记。
-    const weappFlushRestorePendingRef = React.useRef(false);
-    // 定高路径：滚动期间累积的测量记录，用于 flush 时计算滚动修正量
-    const pendingMeasurementsRef = React.useRef(new Map());
-    // 小程序端：延迟 bump 时不同步调用 onItemSizeChange，避免父组件重渲染导致 List remount 闪回顶部；flush 时统一调用
-    const pendingSizeChangesRef = React.useRef([]);
-    // 小程序端（定高路径）：pending 测量的“微动静止检测”
-    const scheduleWeappSettleFlushCheck = React.useCallback(() => {
-        if (!isWeapp)
-            return;
-        if (settleCheckTimerRef.current)
-            return;
-        const check = () => {
-            settleCheckTimerRef.current = null;
-            const hasPending = pendingBumpRef.current || pendingMeasurementsRef.current.size > 0;
-            if (!hasPending || !isUserScrollingRef.current)
-                return;
-            const nowOffset = lastScrollTopRef.current;
-            const delta = Math.abs(nowOffset - settleLastOffsetRef.current);
-            settleLastOffsetRef.current = nowOffset;
-            if (delta <= 1) {
-                settleStillCountRef.current += 1;
-            }
-            else {
-                settleStillCountRef.current = 0;
-            }
-            const idleFor = Date.now() - lastScrollEventAtRef.current;
-            // 条件：连续两次小位移且最近 scroll 事件已进入静止窗口
-            if (settleStillCountRef.current >= 2 && idleFor >= 140) {
-                if (scrollTimeoutRef.current) {
-                    clearTimeout(scrollTimeoutRef.current);
-                    scrollTimeoutRef.current = null;
-                }
-                isScrollingRef.current = false;
-                isUserScrollingRef.current = false;
-                setIsUserScrolling(false);
-                settleStillCountRef.current = 0;
-                return;
-            }
-            settleCheckTimerRef.current = setTimeout(check, 80);
-        };
-        settleLastOffsetRef.current = lastScrollTopRef.current;
-        settleStillCountRef.current = 0;
-        settleCheckTimerRef.current = setTimeout(check, 80);
-    }, [isWeapp]);
+    // （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 修正
-    // 小程序端禁用 scrollCorrection：
-    // 1. 其 100ms setTimeout 的闭包捕获的 renderOffset/setScrollOffset 可能过期，导致错误的程序性滚动
-    // 2. 小程序采用「延迟更新」策略（滚动中不 bump sizeCacheVersion），不需要实时修正
-    // 3. 其 setScrollOffset 调用 updateRenderOffset(true) 会触发 setData，可能干扰 scroll-view
+    // ScrollTop 修正（仅 H5）：动高时尺寸变化自动修正 scrollTop
     const scrollCorrectionEnabled = !isWeapp && props.useResizeObserver === true;
     const scrollCorrection = useScrollCorrection({
         enabled: scrollCorrectionEnabled,
-        visibleStartIndex: visibleStartIndexRef.current,
+        visibleStartIndexRef,
         setScrollOffset: (offsetOrUpdater) => {
             const newOffset = typeof offsetOrUpdater === 'function'
                 ? offsetOrUpdater(renderOffset)
                 : offsetOrUpdater;
-            updateRenderOffset(newOffset, true); // 程序性修正需同步到 ScrollView
+            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,
+        selectorQueryScope: props.selectorQueryScope,
         onResize: (index, size) => {
             var _a;
             const oldSize = sizeCache.getItemSize(index);
             sizeCache.setItemSize(index, size);
-            // 仅当尺寸实际变化（≥1px）时才批量驱动重渲染，避免重复/微小变化导致卡顿
             if (Math.abs(oldSize - size) >= 1) {
                 if (isWeapp && props.useResizeObserver === true) {
                     scheduleWeappDynamicReflow();
                 }
-                else {
-                    // 记录测量变化（用于 flush 时计算滚动修正）
-                    if (isWeapp) {
-                        weappRecordMeasurement(pendingMeasurementsRef, index, oldSize, size);
-                        scheduleWeappSettleFlushCheck();
-                    }
-                    if (sizeCacheRafRef.current == null) {
-                        sizeCacheRafRef.current = requestAnimationFrame(() => {
-                            sizeCacheRafRef.current = null;
-                            if (isWeapp) {
-                                weappSizeCacheVersionBump(isUserScrollingRef, pendingBumpRef, measureScrollProtectRef, setSizeCacheVersion);
-                            }
-                            else {
-                                setSizeCacheVersion((v) => v + 1);
-                            }
-                        });
-                    }
+                else if (sizeCacheRafRef.current == null) {
+                    sizeCacheRafRef.current = requestAnimationFrame(() => {
+                        sizeCacheRafRef.current = null;
+                        setSizeCacheVersion((v) => v + 1);
+                    });
                 }
             }
             // 触发 ScrollTop 修正
@@ -470,92 +471,70 @@ const InnerList = (props, ref) => {
             // 小程序：延迟 onItemSizeChange，避免父组件重渲染导致 List remount
             // H5：直接回调
             if (isWeapp) {
-                weappDeferItemSizeChange(isUserScrollingRef, pendingSizeChangesRef, index, size, props.onItemSizeChange);
+                weappDeferItemSizeChange(index, size, props.onItemSizeChange);
             }
             else {
                 (_a = props.onItemSizeChange) === null || _a === void 0 ? void 0 : _a.call(props, index, size);
             }
         }
     });
-    // 工具：获取 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]);
-    // 计算分组累积高度/宽度（依赖 sizeCacheVersion，动态测量更新后重算，保证最外层容器高度与 item 定位正确）
+        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;
@@ -574,8 +553,7 @@ const InnerList = (props, ref) => {
         }
         return [start, end];
     }, [renderOffset, containerLength, sectionOffsets, sections.length, cacheCount]);
-    // 计算视口内可见 item 的全局索引范围（用于 onScrollIndex：懒加载、埋点等）
-    // 按视口 [renderOffset, renderOffset + containerLength] 精确计算，而非「可见 section 的整段 item」
+    // 视口内可见 item 的全局索引范围（供 onScrollIndex）
     const [visibleStartItem, visibleEndItem] = React.useMemo(() => {
         const viewportTop = renderOffset;
         const viewportBottom = renderOffset + containerLength;
@@ -605,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 };
@@ -617,18 +593,8 @@ const InnerList = (props, ref) => {
             }
         }
     }, [visibleStartItem, visibleEndItem, props.onScrollIndex]);
-    // 触顶/触底事件
-    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]);
-    // 智能滚动处理函数（H5 下拉刷新时 scrollTop 含 Refresher 区，虚拟列表用列表内偏移）
     const handleScroll = React.useCallback((e) => {
-        var _a, _b;
+        var _a, _b, _c, _d;
         let newOffset;
         if (e.detail) {
             newOffset = isHorizontal ? e.detail.scrollLeft : e.detail.scrollTop;
@@ -636,197 +602,108 @@ const InnerList = (props, ref) => {
         else {
             newOffset = isHorizontal ? e.scrollLeft : e.scrollTop;
         }
-        // H5 顶栏悬浮：只滚列表，scrollTop 即列表偏移，无需 clamp
         const effectiveOffset = newOffset;
-        lastScrollEventAtRef.current = Date.now();
-        // 若新一轮用户滚动已开始，取消尚未执行的旧 restore（避免两个事务互相打架）
-        if (isWeapp && props.useResizeObserver !== true && scrollRestoreRef.current !== null && !programmaticCooldownRef.current) {
-            const restoreFrom = (_a = scrollRestoreFromRef.current) !== null && _a !== void 0 ? _a : lastScrollTopRef.current;
-            if (Math.abs(effectiveOffset - restoreFrom) > 8) {
-                scrollRestoreRef.current = null;
-                scrollRestoreFromRef.current = null;
-            }
-        }
-        // 小程序端：flush 重排后有一帧不传 scroll-top，原生会归 0 并触发 onScroll(0)。effect 内会立刻清掉 scrollRestoreRef，
-        // 若 onScroll(0) 在 effect 之后才触发会被误接受导致「第二次抖动：回顶+空白」。用 weappFlushRestorePendingRef 标记
-        // 从 flush 到 nextTick 内 restore 执行完的整段窗口，此期间忽略 effectiveOffset<=1。
-        if (isWeapp &&
-            props.useResizeObserver !== true &&
-            (scrollRestoreRef.current !== null || weappFlushRestorePendingRef.current) &&
-            effectiveOffset <= 1) {
-            return;
-        }
-        // 小程序端：程序性恢复后的短窗口内，过滤异常“回顶/大幅反向跳变”噪声事件
-        // 动高分支改走 virtual-list 风格，不在这里做程序性回拉。
-        if (isWeapp && props.useResizeObserver !== true && suppressResetUntilRef.current > Date.now()) {
-            const target = (_b = programmaticTargetOffsetRef.current) !== null && _b !== void 0 ? _b : lastScrollTopRef.current;
-            const isResetToTop = effectiveOffset <= 1 && target > 40;
-            if (isResetToTop) {
-                const now = Date.now();
-                // 仅“忽略”会导致原生位置与虚拟渲染位置脱节（空白）。
-                // 这里改为回补一次目标位置，保持两者一致。
-                if (now - guardHealAtRef.current > 120) {
-                    guardHealAtRef.current = now;
-                    updateRenderOffset(target, !isUserScrollingRef.current);
-                }
-                return;
-            }
-        }
+        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;
         }
-        // 小程序端程序性滚动冷却期内：只更新 renderOffset 用于虚拟列表渲染，不触发同步逻辑，避免被"拉回"
-        // 注意：programmaticCooldownRef 只在小程序端会被设为 true，H5 端不受影响
         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 === null || onScroll === void 0 ? void 0 : onScroll({
-            scrollTop: isHorizontal ? 0 : newOffset,
-            scrollLeft: isHorizontal ? newOffset : 0
-        });
-    }, [isHorizontal, onScroll, updateRenderOffset, containerLength, scrollCorrection, props.useResizeObserver]);
-    // 小程序端：优先使用原生 onScrollEnd 作为“滚动停止”信号，尽快触发 flush
-    // timeout 仍保留作为兜底（某些场景 onScrollEnd 可能不稳定）
+        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 (settleCheckTimerRef.current) {
-                clearTimeout(settleCheckTimerRef.current);
-                settleCheckTimerRef.current = null;
-            }
-            const hasPending = props.useResizeObserver === true
-                ? false
-                : (pendingBumpRef.current || pendingMeasurementsRef.current.size > 0);
-            if (isUserScrollingRef.current || hasPending) {
+            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]);
-    // 小程序端：用户停止滚动后 flush
-    // 1. flush 延迟的 sizeCacheVersion bump（滚动期间 setData 更新 children 会导致 scroll-view 重置）
-    // 2. flush 延迟的 onItemSizeChange（避免父组件重渲染导致 List remount）
-    if (isWeapp) {
-        // flush effect：用户停止滚动后执行延迟的 sizeCacheVersion bump
-        // 条件增强：只要存在 pending bump 或 pending 测量记录，都在第一次停住时立即 flush
-        React.useEffect(() => {
-            if (!isUserScrolling) {
-                if (props.useResizeObserver === true) {
-                    // 动高 + weapp 已改为“测量即重排、原生滚动主导”，不再走 flush/restore 事务。
-                    pendingBumpRef.current = false;
-                    if (pendingMeasurementsRef.current.size > 0) {
-                        pendingMeasurementsRef.current.clear();
-                    }
-                    return;
-                }
-                const hasPendingMeasurements = pendingMeasurementsRef.current.size > 0;
-                if (pendingBumpRef.current || hasPendingMeasurements) {
-                    pendingBumpRef.current = false;
-                    // 计算视口上方 item 高度变化的累积 delta
-                    // visibleStartItem = 当前视口第一个可见 item（旧布局，因为 sizeCacheVersion 还没 bump）
-                    let heightDelta = 0;
-                    pendingMeasurementsRef.current.forEach(({ originalOldSize, latestNewSize }, index) => {
-                        if (index < visibleStartItem) {
-                            heightDelta += (latestNewSize - originalOldSize);
-                        }
-                    });
-                    pendingMeasurementsRef.current.clear();
-                    // 修正后的 scrollTop = 旧 scrollTop + 视口上方高度变化量（定高 / 非动高路径）
-                    const restoreFrom = lastScrollTopRef.current;
-                    const correctedScrollTop = restoreFrom + heightDelta;
-                    scrollRestoreFromRef.current = restoreFrom;
-                    scrollRestoreRef.current = correctedScrollTop;
-                    weappFlushRestorePendingRef.current = true;
-                    measureScrollProtectRef.current = true;
-                    setSizeCacheVersion((v) => v + 1);
-                }
-                else {
-                    // 没有 pending bump 但可能有残留的测量记录（scrolling 结束但没有新测量），清理
-                    if (pendingMeasurementsRef.current.size > 0) {
-                        pendingMeasurementsRef.current.clear();
-                    }
-                }
-                // flush 延迟的 onItemSizeChange（暂时禁用，验证 scroll-anchoring）
-                // const pending = pendingSizeChangesRef.current
-                // if (pending.length > 0) {
-                //   pendingSizeChangesRef.current = []
-                //   pending.forEach(({ index, size }) => props.onItemSizeChange?.(index, size))
-                // }
-            }
-        }, [isUserScrolling, props.useResizeObserver]);
-        // scrollRestoreEffect：sizeCacheVersion 变化后，在下一帧单独恢复 scroll 位置
-        // 核心思想：第一次 setData 更新 children（不带 scroll-top），
-        // 第二次 setData 仅恢复 scroll-top（children 不变），避免同批冲突
-        React.useEffect(() => {
-            if (props.useResizeObserver === true)
-                return;
-            if (scrollRestoreRef.current === null) {
-                weappFlushRestorePendingRef.current = false;
-                return;
-            }
-            const targetPos = scrollRestoreRef.current;
-            const sourcePos = scrollRestoreFromRef.current;
-            scrollRestoreRef.current = null;
-            scrollRestoreFromRef.current = null;
-            // 使用 Taro.nextTick 确保在上一次 setData 完成后执行
-            Taro.nextTick(() => {
-                try {
-                    // 若用户已开始下一次滚动，则取消这次过期 restore，避免回拉/回顶/空白
-                    const userContinued = sourcePos != null &&
-                        isUserScrollingRef.current &&
-                        Math.abs(lastScrollTopRef.current - sourcePos) > 8;
-                    if (userContinued) {
-                        return;
-                    }
-                    updateRenderOffset(targetPos, true);
-                }
-                finally {
-                    weappFlushRestorePendingRef.current = false;
-                }
-            });
-        }, [sizeCacheVersion, updateRenderOffset]);
-        // 小程序端：保持稳定优先，暂不回放 onItemSizeChange。
-        React.useEffect(() => {
-            pendingSizeChangesRef.current = [];
-        }, [isUserScrolling, sizeCacheVersion]);
-    }
-    // 初始化后的延迟同步 - 确保 ScrollView 与虚拟列表窗口一致（scrollTop 受控跳转）
+    // 暴露 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') {
+            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;
-            setRenderOffset(controlledScrollTop);
-            setScrollViewOffset(controlledScrollTop);
             programmaticScrollRef.current = true;
         }
     }, [controlledScrollTop]);
     // 清理定时器、ResizeObserver 与尺寸缓存 RAF（仅在卸载时执行）
-    // 注意：不要依赖整个对象（resizeObserver/scrollCorrection），否则每次渲染都会触发 cleanup，
-    // 进而反复清掉 pendingSizeFlushTimer，导致 onItemSizeChange 批量回放永远不执行。
     React.useEffect(() => {
         return () => {
             if (scrollTimeoutRef.current) {
                 clearTimeout(scrollTimeoutRef.current);
             }
-            if (settleCheckTimerRef.current) {
-                clearTimeout(settleCheckTimerRef.current);
-                settleCheckTimerRef.current = null;
-            }
             // 小程序端冷却期定时器清理
             if (isWeapp && programmaticCooldownTimerRef.current) {
                 clearTimeout(programmaticCooldownTimerRef.current);
@@ -838,7 +715,7 @@ const InnerList = (props, ref) => {
             resizeObserver.disconnect();
             scrollCorrection.clearQueue();
         };
-    }, [isWeapp, resizeObserver.disconnect, scrollCorrection.clearQueue]);
+    }, []);
     // scrollIntoView：仅当 scrollIntoView 变化时执行一次跳动，统一转换为 scrollTop 路径（updateRenderOffset）。
     const lastScrollIntoViewRef = React.useRef(null);
     React.useEffect(() => {
@@ -875,34 +752,65 @@ const InnerList = (props, ref) => {
                     currentGlobalIndex += section.items.length;
                 }
             }
-            updateRenderOffset(targetOffset, true);
+            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]);
-    // 容器样式：width/height 即视口宽高；H5 刷新中禁止容器滚动（参考《H5 下拉刷新如何实现》）
+    }, [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 属性：对齐 taro-components-react ScrollView（scrollTop/scrollLeft、upperThreshold/lowerThreshold、scrollWithAnimation）
-    const scrollViewProps = Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ scrollY: !scrollX && scrollY, scrollX, style: containerStyle, className, enhanced: true, showScrollbar,
+    // 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, onScrollToUpper,
-        onScrollToLower,
-        onScrollStart, onScrollEnd: handleNativeScrollEnd, enableBackToTop }, (isWeapp ? { scrollAnchoring: true } : {})), (typeof cacheExtent === 'number' ? { cacheExtent } : {})), { 'data-testid': 'taro-list-container' }), scrollViewRefresherProps), scrollViewRefresherHandlers), (!supportsNativeRefresher && refresherConfig && !addImperativeTouchListeners ? h5RefresherProps.touchHandlers : {}));
+        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);
+        updateRenderOffset(0, true, 'refresher');
     }, [h5RefresherProps.isRefreshing, isH5, refresherConfig, supportsNativeRefresher, updateRenderOffset]);
-    // H5 下拉刷新：只挂载一次 touch 监听，用 ref 存 addImperativeTouchListeners 避免因 config 引用变化导致 effect 循环（attach/detach 刷屏）
+    // H5 下拉刷新：ref 存 addImperativeTouchListeners，避免 config 变化导致 effect 循环
     React.useLayoutEffect(() => {
         const attach = addImperativeTouchListenersRef.current;
         if (!attach)
             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;
@@ -917,28 +825,16 @@ const InnerList = (props, ref) => {
             }
             refresherTeardownRef.current = null;
         };
-    }, []);
-    // scrollTop 传递策略：
-    // - weapp 定高：每帧传 scrollViewOffset（measureProtect 帧除外）
-    // - weapp 动高：不常态传，保持原生滚动主导，仅程序性滚动时传
-    // - H5：仅非用户滑动时传
+    }, [useScrollElementMode, effectiveScrollElement]);
+    scrollViewOffsetRef.current = scrollViewOffset;
+    // scrollTop 传递策略（对齐 virtual-list enhanced=true 的做法）：
+    //   - 程序性滚动帧（programmaticScrollRef=true）：传 scrollViewOffset（目标位置）
+    //   - 其余所有帧（用户滚动 / 测量重排 / 空闲）：完全不传，依赖微信原生 + scrollAnchoring
+    //     scrollAnchoring=true 负责在内容重排时自动维持视口位置，避免与显式 scrollTop
+    //     同帧冲突（冲突会导致 scrollAnchoring 失去锚点后归顶）
     if (isWeapp) {
-        const isWeappDynamicHeight = props.useResizeObserver === true;
-        if (measureScrollProtectRef.current) {
-            measureScrollProtectRef.current = false;
-        }
-        else if (isWeappDynamicHeight) {
-            // 动高：仅程序性滚动时传，其他时刻由原生滚动主导
-            if (programmaticScrollRef.current) {
-                if (isHorizontal)
-                    scrollViewProps.scrollLeft = scrollViewOffset;
-                else
-                    scrollViewProps.scrollTop = scrollViewOffset;
-                programmaticScrollRef.current = false;
-            }
-        }
-        else {
-            // 定高：每帧传，支持受控跳转
+        if (programmaticScrollRef.current) {
+            // 程序性滚动（imperative / scrollCorrection / scrollIntoView 等）：传目标位置
             if (isHorizontal) {
                 scrollViewProps.scrollLeft = scrollViewOffset;
             }
@@ -947,6 +843,7 @@ const InnerList = (props, ref) => {
             }
             programmaticScrollRef.current = false;
         }
+        // else：用户滚动 / 空闲帧不传 scrollTop，让微信原生 + scrollAnchoring 完全接管
     }
     else {
         // H5：非用户滑动时传
@@ -959,27 +856,40 @@ const InnerList = (props, ref) => {
             }
         }
     }
-    // H5：仅程序性滚动时写回 DOM
-    if (isH5) {
-        React.useEffect(() => {
-            if (isUserScrolling || !containerRef.current || typeof scrollViewOffset !== 'number')
-                return;
-            if (!programmaticScrollRef.current)
-                return;
-            const scrollValue = isHorizontal ? scrollViewOffset : scrollViewOffset;
-            if (isHorizontal) {
-                containerRef.current.scrollLeft = scrollValue;
-            }
-            else {
-                containerRef.current.scrollTop = scrollValue;
-            }
-            programmaticScrollRef.current = false;
-        }, [scrollViewOffset, isHorizontal, isUserScrolling]);
-    }
-    // 总高度/宽度（包含 NoMore）；H5 顶栏悬浮不占滚动高度，只滚列表
+    // 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)
@@ -1005,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 = [];
@@ -1043,12 +953,7 @@ const InnerList = (props, ref) => {
                                     else if (sizeCacheRafRef.current == null) {
                                         sizeCacheRafRef.current = requestAnimationFrame(() => {
                                             sizeCacheRafRef.current = null;
-                                            if (isWeapp) {
-                                                weappSizeCacheVersionBump(isUserScrollingRef, pendingBumpRef, measureScrollProtectRef, setSizeCacheVersion);
-                                            }
-                                            else {
-                                                setSizeCacheVersion((v) => v + 1);
-                                            }
+                                            setSizeCacheVersion((v) => v + 1);
                                         });
                                     }
                                 }
@@ -1066,7 +971,7 @@ const InnerList = (props, ref) => {
                             Taro.nextTick(() => {
                                 if (!headerRefsRef.current.has(sectionIndex))
                                     return;
-                                Taro.createSelectorQuery()
+                                createSelectorQueryScoped(props.selectorQueryScope)
                                     .select(`#${listId}-list-header-inner-${sectionIndex}`)
                                     .boundingClientRect((rect) => {
                                     if (rect) {
@@ -1098,6 +1003,7 @@ const InnerList = (props, ref) => {
                     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}`;
@@ -1143,7 +1049,6 @@ const InnerList = (props, ref) => {
             for (let i = startItem; i <= endItem; i++) {
                 const currentGlobalIndex = globalItemIndex + i;
                 const itemId = `list-item-${currentGlobalIndex}`;
-                // 内联样式替代className
                 const sectionItemStyle = Object.assign({ position: 'absolute', zIndex: 1, boxSizing: 'border-box', width: '100%', minHeight: '20px', overflow: 'hidden', lineHeight: 1 }, (isHorizontal
                     ? {
                         top: 0,
@@ -1157,8 +1062,7 @@ const InnerList = (props, ref) => {
                         height: itemSizes[i],
                         marginBottom: space
                     }));
-                // ref 回调（用于 ResizeObserver）：绑定到「内层内容容器」，测量的是内容真实高度
-                // 后加载项：挂载后单帧 RAF 备用测量；仅当尺寸实际变化时才 bump 版本，避免与 ResizeObserver 重复触发导致连续两次重渲染（卡顿）
+                // ResizeObserver：绑定内层内容容器测量真实尺寸，尺寸变化时才 bump 版本
                 const refCallback = (el) => {
                     if (el) {
                         const capturedIndex = currentGlobalIndex;
@@ -1170,7 +1074,6 @@ const InnerList = (props, ref) => {
                             var _a;
                             if (measured > 0) {
                                 const oldSize = sizeCache.getItemSize(capturedIndex);
-                                // 尺寸未变化，跳过
                                 if (Math.abs(oldSize - measured) < 1)
                                     return;
                                 sizeCache.setItemSize(capturedIndex, measured);
@@ -1178,29 +1081,19 @@ const InnerList = (props, ref) => {
                                 if (isWeapp && props.useResizeObserver === true) {
                                     scheduleWeappDynamicReflow();
                                 }
-                                else if (isWeapp) {
-                                    // 记录测量变化（用于 flush 时计算滚动修正）
-                                    weappRecordMeasurement(pendingMeasurementsRef, capturedIndex, oldSize, measured);
-                                    scheduleWeappSettleFlushCheck();
+                                else if (sizeCacheRafRef.current == null) {
+                                    sizeCacheRafRef.current = requestAnimationFrame(() => {
+                                        sizeCacheRafRef.current = null;
+                                        setSizeCacheVersion((v) => v + 1);
+                                    });
                                 }
                                 // 小程序：延迟 onItemSizeChange，避免父组件重渲染导致 List remount
                                 if (isWeapp) {
-                                    weappDeferItemSizeChange(isUserScrollingRef, pendingSizeChangesRef, capturedIndex, measured, props.onItemSizeChange);
+                                    weappDeferItemSizeChange(capturedIndex, measured, props.onItemSizeChange);
                                 }
                                 else {
                                     (_a = props.onItemSizeChange) === null || _a === void 0 ? void 0 : _a.call(props, capturedIndex, measured);
                                 }
-                                if (!(isWeapp && props.useResizeObserver === true) && sizeCacheRafRef.current == null) {
-                                    sizeCacheRafRef.current = requestAnimationFrame(() => {
-                                        sizeCacheRafRef.current = null;
-                                        if (isWeapp) {
-                                            weappSizeCacheVersionBump(isUserScrollingRef, pendingBumpRef, measureScrollProtectRef, setSizeCacheVersion);
-                                        }
-                                        else {
-                                            setSizeCacheVersion((v) => v + 1);
-                                        }
-                                    });
-                                }
                             }
                         };
                         if (isH5) {
@@ -1216,7 +1109,7 @@ const InnerList = (props, ref) => {
                             // 注意：必须选 inner 容器（无固定高度，由内容撑开），不能选 outer（有虚拟列表设置的固定高度）
                             // 已测量过的 item 跳过，避免 refCallback 重复触发导致无限循环
                             // 滚动期间跳过 SelectorQuery（不加入 weappMeasuredItemsRef），避免异步查询干扰 scroll-view
-                            // SelectorQuery 是只读查询，滚动期间执行安全；sizeCacheVersion bump 由 weappSizeCacheVersionBump 延迟到滚动结束
+                            // SelectorQuery 是只读查询，滚动期间执行安全
                             if (shouldMeasureWeappItem(capturedIndex, weappMeasuredItemsRef.current)) {
                                 weappMeasuredItemsRef.current.add(capturedIndex);
                                 // 使用 Taro.nextTick 代替 setTimeout(50)：等待下一帧渲染完成后再测量
@@ -1224,7 +1117,7 @@ const InnerList = (props, ref) => {
                                 Taro.nextTick(() => {
                                     if (!itemRefsRef.current.has(capturedIndex))
                                         return;
-                                    Taro.createSelectorQuery()
+                                    createSelectorQueryScoped(props.selectorQueryScope)
                                         // 页面上可能同时存在多个 List，inner id 必须带 listId 前缀避免跨列表误命中
                                         .select(`#${listId}-list-item-inner-${capturedIndex}`)
                                         .boundingClientRect((rect) => {
@@ -1274,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;
@@ -1294,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 顶栏悬浮时 = 仅列表高度，顶栏不占滚动）
+    // 可滚区域总尺寸
+    // 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%' };
@@ -1311,7 +1234,7 @@ const InnerList = (props, ref) => {
         ? { 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: {
@@ -1324,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