@tarojs/components-advanced 4.1.12-beta.7 → 4.1.12-beta.9

package/dist/components/index.js

@@ -1,7 +1,8 @@
-export { List, ListScrollElementContext, accumulate, isShaking } from './list/index.js';
+export { List, accumulate, isShaking } from './list/index.js';
 export { VirtualList } from './virtual-list/index.js';
 export { VirtualWaterfall } from './virtual-waterfall/index.js';
 import './water-flow/index.js';
+export { ScrollElementContext as ListScrollElementContext } from '@tarojs/components-react';
 export { ListItem } from './list/ListItem.js';
 export { NoMore } from './list/NoMore.js';
 export { StickyHeader } from './list/StickyHeader.js';

package/dist/components/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;"}
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;"}

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

@@ -0,0 +1,13 @@
+import type { RefObject } from 'react';
+export interface UseListNestedScrollResult {
+    effectiveScrollElement: RefObject<HTMLElement | null> | null;
+    effectiveStartOffset: number;
+    useScrollElementMode: boolean;
+    needAutoFind: boolean;
+    autoFindStatus: 'pending' | 'found' | 'not-found';
+    contentWrapperRef: RefObject<HTMLDivElement | null>;
+}
+/**
+ * 合并嵌套滚动相关逻辑：Context、自动查找、startOffset 测量、scrollElement 解析
+ */
+export declare function useListNestedScroll(listType: 'default' | 'nested', scrollElement?: RefObject<HTMLElement | null>, startOffsetProp?: number, isHorizontal?: boolean): UseListNestedScrollResult;

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

@@ -0,0 +1,46 @@
+import { ScrollElementContext } from '@tarojs/components-react';
+import { useRef, useContext } from 'react';
+import { isH5 } from '../utils.js';
+import { useMeasureStartOffset } from './useMeasureStartOffset.js';
+import { useScrollParentAutoFind } from './useScrollParentAutoFind.js';
+
+const EMPTY_SCROLL_REF = { current: null };
+/**
+ * 合并嵌套滚动相关逻辑：Context、自动查找、startOffset 测量、scrollElement 解析
+ */
+function useListNestedScroll(listType, scrollElement, startOffsetProp, isHorizontal = false) {
+    var _a, _b, _c;
+    const contentWrapperRef = useRef(null);
+    const scrollElementCtx = useContext(ScrollElementContext);
+    const ctxStart = scrollElementCtx === null || scrollElementCtx === void 0 ? void 0 : scrollElementCtx.startOffset;
+    const hasExplicitCtxStartOffset = ctxStart != null && ctxStart > 0;
+    const needAutoFind = listType === 'nested' &&
+        !scrollElement &&
+        !(scrollElementCtx === null || scrollElementCtx === void 0 ? void 0 : scrollElementCtx.scrollRef) &&
+        isH5;
+    const { scrollParentRef: autoFoundRef, status: autoFindStatus } = useScrollParentAutoFind(contentWrapperRef, { enabled: !!needAutoFind, isHorizontal });
+    const effectiveScrollElement = (_a = scrollElement !== null && scrollElement !== void 0 ? scrollElement : scrollElementCtx === null || scrollElementCtx === void 0 ? void 0 : scrollElementCtx.scrollRef) !== null && _a !== void 0 ? _a : (needAutoFind && autoFindStatus === 'found' ? autoFoundRef : null);
+    const needMeasure = listType === 'nested' &&
+        effectiveScrollElement &&
+        isH5 &&
+        startOffsetProp == null &&
+        !hasExplicitCtxStartOffset;
+    const measuredStartOffset = useMeasureStartOffset(effectiveScrollElement !== null && effectiveScrollElement !== void 0 ? effectiveScrollElement : EMPTY_SCROLL_REF, contentWrapperRef, { enabled: !!needMeasure, isHorizontal });
+    const effectiveStartOffset = (_c = (_b = startOffsetProp !== null && startOffsetProp !== void 0 ? startOffsetProp : (ctxStart != null && ctxStart > 0 ? ctxStart : null)) !== null && _b !== void 0 ? _b : measuredStartOffset) !== null && _c !== void 0 ? _c : 0;
+    const useScrollElementMode = listType === 'nested' && !!(effectiveScrollElement && isH5);
+    if (listType === 'nested' && !effectiveScrollElement && isH5 && autoFindStatus === 'not-found') {
+        // eslint-disable-next-line no-console
+        console.warn('[List] nestedScroll 模式但无 scrollElement（props/Context/自动查找），回退为 default');
+    }
+    return {
+        effectiveScrollElement,
+        effectiveStartOffset,
+        useScrollElementMode,
+        needAutoFind,
+        autoFindStatus,
+        contentWrapperRef,
+    };
+}
+
+export { useListNestedScroll };
+//# sourceMappingURL=useListNestedScroll.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useListNestedScroll.js","sources":["../../../../src/components/list/hooks/useListNestedScroll.ts"],"sourcesContent":["import { type ScrollElementContextValue, ScrollElementContext } from '@tarojs/components-react'\nimport { useContext, useRef } from 'react'\n\nimport { isH5 } from '../utils'\nimport { useMeasureStartOffset } from './useMeasureStartOffset'\nimport { useScrollParentAutoFind } from './useScrollParentAutoFind'\n\nimport type { RefObject } from 'react'\n\nconst EMPTY_SCROLL_REF = { current: null as HTMLElement | null }\n\nexport interface UseListNestedScrollResult {\n  effectiveScrollElement: RefObject<HTMLElement | null> | null\n  effectiveStartOffset: number\n  useScrollElementMode: boolean\n  needAutoFind: boolean\n  autoFindStatus: 'pending' | 'found' | 'not-found'\n  contentWrapperRef: RefObject<HTMLDivElement | null>\n}\n\n/**\n * 合并嵌套滚动相关逻辑：Context、自动查找、startOffset 测量、scrollElement 解析\n */\nexport function useListNestedScroll(\n  listType: 'default' | 'nested',\n  scrollElement?: RefObject<HTMLElement | null>,\n  startOffsetProp?: number,\n  isHorizontal: boolean = false\n): UseListNestedScrollResult {\n  const contentWrapperRef = useRef<HTMLDivElement>(null)\n  const scrollElementCtx = useContext(ScrollElementContext) as ScrollElementContextValue | null\n  const ctxStart = scrollElementCtx?.startOffset\n  const hasExplicitCtxStartOffset = ctxStart != null && ctxStart > 0\n\n  const needAutoFind =\n    listType === 'nested' &&\n    !scrollElement &&\n    !scrollElementCtx?.scrollRef &&\n    isH5\n  const { scrollParentRef: autoFoundRef, status: autoFindStatus } = useScrollParentAutoFind(\n    contentWrapperRef,\n    { enabled: !!needAutoFind, isHorizontal }\n  )\n\n  const effectiveScrollElement =\n    scrollElement ??\n    scrollElementCtx?.scrollRef ??\n    (needAutoFind && autoFindStatus === 'found' ? autoFoundRef : null)\n\n  const needMeasure =\n    listType === 'nested' &&\n    effectiveScrollElement &&\n    isH5 &&\n    startOffsetProp == null &&\n    !hasExplicitCtxStartOffset\n  const measuredStartOffset = useMeasureStartOffset(\n    effectiveScrollElement ?? EMPTY_SCROLL_REF,\n    contentWrapperRef,\n    { enabled: !!needMeasure, isHorizontal }\n  )\n\n  const effectiveStartOffset =\n    startOffsetProp ??\n    (ctxStart != null && ctxStart > 0 ? ctxStart : null) ??\n    measuredStartOffset ??\n    0\n\n  const useScrollElementMode = listType === 'nested' && !!(effectiveScrollElement && isH5)\n\n  if (listType === 'nested' && !effectiveScrollElement && isH5 && autoFindStatus === 'not-found') {\n    // eslint-disable-next-line no-console\n    console.warn('[List] nestedScroll 模式但无 scrollElement（props/Context/自动查找），回退为 default')\n  }\n\n  return {\n    effectiveScrollElement,\n    effectiveStartOffset,\n    useScrollElementMode,\n    needAutoFind,\n    autoFindStatus,\n    contentWrapperRef,\n  }\n}\n"],"names":[],"mappings":";;;;;;AASA,MAAM,gBAAgB,GAAG,EAAE,OAAO,EAAE,IAA0B,EAAE;AAWhE;;AAEG;AACG,SAAU,mBAAmB,CACjC,QAA8B,EAC9B,aAA6C,EAC7C,eAAwB,EACxB,YAAA,GAAwB,KAAK,EAAA;;AAE7B,IAAA,MAAM,iBAAiB,GAAG,MAAM,CAAiB,IAAI,CAAC;AACtD,IAAA,MAAM,gBAAgB,GAAG,UAAU,CAAC,oBAAoB,CAAqC;IAC7F,MAAM,QAAQ,GAAG,gBAAgB,KAAA,IAAA,IAAhB,gBAAgB,KAAhB,KAAA,CAAA,GAAA,KAAA,CAAA,GAAA,gBAAgB,CAAE,WAAW;IAC9C,MAAM,yBAAyB,GAAG,QAAQ,IAAI,IAAI,IAAI,QAAQ,GAAG,CAAC;AAElE,IAAA,MAAM,YAAY,GAChB,QAAQ,KAAK,QAAQ;AACrB,QAAA,CAAC,aAAa;QACd,EAAC,gBAAgB,KAAhB,IAAA,IAAA,gBAAgB,uBAAhB,gBAAgB,CAAE,SAAS,CAAA;AAC5B,QAAA,IAAI;IACN,MAAM,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,EAAE,cAAc,EAAE,GAAG,uBAAuB,CACvF,iBAAiB,EACjB,EAAE,OAAO,EAAE,CAAC,CAAC,YAAY,EAAE,YAAY,EAAE,CAC1C;AAED,IAAA,MAAM,sBAAsB,GAC1B,CAAA,EAAA,GAAA,aAAa,aAAb,aAAa,KAAA,KAAA,CAAA,GAAb,aAAa,GACb,gBAAgB,KAAA,IAAA,IAAhB,gBAAgB,KAAA,KAAA,CAAA,GAAA,KAAA,CAAA,GAAhB,gBAAgB,CAAE,SAAS,MAC3B,IAAA,IAAA,EAAA,KAAA,KAAA,CAAA,GAAA,EAAA,IAAC,YAAY,IAAI,cAAc,KAAK,OAAO,GAAG,YAAY,GAAG,IAAI,CAAC;AAEpE,IAAA,MAAM,WAAW,GACf,QAAQ,KAAK,QAAQ;QACrB,sBAAsB;QACtB,IAAI;AACJ,QAAA,eAAe,IAAI,IAAI;AACvB,QAAA,CAAC,yBAAyB;IAC5B,MAAM,mBAAmB,GAAG,qBAAqB,CAC/C,sBAAsB,aAAtB,sBAAsB,KAAA,KAAA,CAAA,GAAtB,sBAAsB,GAAI,gBAAgB,EAC1C,iBAAiB,EACjB,EAAE,OAAO,EAAE,CAAC,CAAC,WAAW,EAAE,YAAY,EAAE,CACzC;AAED,IAAA,MAAM,oBAAoB,GACxB,CAAA,EAAA,GAAA,CAAA,EAAA,GAAA,eAAe,KAAA,IAAA,IAAf,eAAe,KAAA,KAAA,CAAA,GAAf,eAAe,IACd,QAAQ,IAAI,IAAI,IAAI,QAAQ,GAAG,CAAC,GAAG,QAAQ,GAAG,IAAI,CAAC,MAAA,IAAA,IAAA,EAAA,KAAA,KAAA,CAAA,GAAA,EAAA,GACpD,mBAAmB,MAAA,IAAA,IAAA,EAAA,KAAA,KAAA,CAAA,GAAA,EAAA,GACnB,CAAC;AAEH,IAAA,MAAM,oBAAoB,GAAG,QAAQ,KAAK,QAAQ,IAAI,CAAC,EAAE,sBAAsB,IAAI,IAAI,CAAC;AAExF,IAAA,IAAI,QAAQ,KAAK,QAAQ,IAAI,CAAC,sBAAsB,IAAI,IAAI,IAAI,cAAc,KAAK,WAAW,EAAE;;AAE9F,QAAA,OAAO,CAAC,IAAI,CAAC,wEAAwE,CAAC;;IAGxF,OAAO;QACL,sBAAsB;QACtB,oBAAoB;QACpB,oBAAoB;QACpB,YAAY;QACZ,cAAc;QACd,iBAAiB;KAClB;AACH;;;;"}

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

@@ -0,0 +1,21 @@
+import type { RefObject } from 'react';
+export interface ListScrollElementAttachRefs {
+    scrollCorrection: {
+        markUserScrolling: () => void;
+    };
+    onScroll: ((e: {
+        scrollTop: number;
+        scrollLeft: number;
+    }) => void) | undefined;
+    onScrollToUpper: (() => void) | undefined;
+    onScrollToLower: (() => void) | undefined;
+    threshold: {
+        upper: number;
+        lower: number;
+    };
+    listContentLength: number;
+}
+/**
+ * scrollElement 模式下：监听外部滚动驱动 renderOffset，并从 scrollElement 获取 containerLength
+ */
+export declare function useListScrollElementAttach(enabled: boolean, effectiveScrollElement: RefObject<HTMLElement | null> | null, effectiveStartOffset: number, isHorizontal: boolean, setContainerLength: (v: number) => void, updateRenderOffset: (offset: number, sync?: boolean, source?: string) => void, scrollRefProp: React.MutableRefObject<HTMLElement | null> | undefined, refsRef: RefObject<ListScrollElementAttachRefs>): void;

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

@@ -0,0 +1,86 @@
+import { useRef, useEffect } from 'react';
+
+/**
+ * scrollElement 模式下：监听外部滚动驱动 renderOffset，并从 scrollElement 获取 containerLength
+ */
+function useListScrollElementAttach(enabled, effectiveScrollElement, effectiveStartOffset, isHorizontal, setContainerLength, updateRenderOffset, scrollRefProp, refsRef) {
+    const effectiveStartOffsetRef = useRef(effectiveStartOffset);
+    effectiveStartOffsetRef.current = effectiveStartOffset;
+    useEffect(() => {
+        if (!enabled || !effectiveScrollElement)
+            return;
+        const el = effectiveScrollElement.current;
+        if (!el || typeof ResizeObserver === 'undefined')
+            return;
+        const update = () => {
+            const measured = isHorizontal ? el.clientWidth : el.clientHeight;
+            if (measured > 0)
+                setContainerLength(measured);
+            if (scrollRefProp)
+                scrollRefProp.current = el;
+        };
+        update();
+        const ro = new ResizeObserver(update);
+        ro.observe(el);
+        return () => ro.disconnect();
+    }, [enabled, effectiveScrollElement, isHorizontal, scrollRefProp, setContainerLength]);
+    useEffect(() => {
+        if (!enabled || !effectiveScrollElement)
+            return;
+        let cancelled = false;
+        let teardown = null;
+        const maxRetries = 20;
+        const tryAttach = (retryCount = 0) => {
+            if (cancelled)
+                return;
+            const target = effectiveScrollElement.current;
+            if (!target) {
+                if (retryCount < maxRetries) {
+                    requestAnimationFrame(() => tryAttach(retryCount + 1));
+                }
+                return;
+            }
+            const refs = refsRef.current;
+            if (!refs)
+                return;
+            let inUpperZone = true;
+            let inLowerZone = false;
+            const handler = () => {
+                var _a, _b, _c;
+                const r = refsRef.current;
+                if (!r)
+                    return;
+                const scrollPos = isHorizontal ? target.scrollLeft : target.scrollTop;
+                const adjustedPos = scrollPos - effectiveStartOffsetRef.current;
+                const effectiveAdjusted = Math.max(0, adjustedPos);
+                const clientSize = isHorizontal ? target.clientWidth : target.clientHeight;
+                r.scrollCorrection.markUserScrolling();
+                updateRenderOffset(effectiveAdjusted, false, 'scrollElement');
+                (_a = r.onScroll) === null || _a === void 0 ? void 0 : _a.call(r, { scrollTop: isHorizontal ? 0 : scrollPos, scrollLeft: isHorizontal ? scrollPos : 0 });
+                const { upper, lower } = r.threshold;
+                const innerContentLen = r.listContentLength;
+                const nowInUpper = effectiveAdjusted <= upper;
+                const nowInLower = innerContentLen > 0 && effectiveAdjusted + clientSize >= innerContentLen - lower;
+                if (nowInUpper && !inUpperZone)
+                    (_b = r.onScrollToUpper) === null || _b === void 0 ? void 0 : _b.call(r);
+                if (nowInLower && !inLowerZone)
+                    (_c = r.onScrollToLower) === null || _c === void 0 ? void 0 : _c.call(r);
+                inUpperZone = nowInUpper;
+                inLowerZone = nowInLower;
+            };
+            const initialScroll = isHorizontal ? target.scrollLeft : target.scrollTop;
+            const initialAdjusted = Math.max(0, initialScroll - effectiveStartOffsetRef.current);
+            updateRenderOffset(initialAdjusted, false, 'scrollElement');
+            target.addEventListener('scroll', handler, { passive: true });
+            teardown = () => target.removeEventListener('scroll', handler);
+        };
+        tryAttach();
+        return () => {
+            cancelled = true;
+            teardown === null || teardown === void 0 ? void 0 : teardown();
+        };
+    }, [enabled, effectiveScrollElement, isHorizontal, effectiveStartOffset, updateRenderOffset, refsRef]);
+}
+
+export { useListScrollElementAttach };
+//# sourceMappingURL=useListScrollElementAttach.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useListScrollElementAttach.js","sources":["../../../../src/components/list/hooks/useListScrollElementAttach.ts"],"sourcesContent":["import { useEffect, useRef } from 'react'\n\nimport type { RefObject } from 'react'\n\nexport interface ListScrollElementAttachRefs {\n  scrollCorrection: { markUserScrolling: () => void }\n  onScroll: ((e: { scrollTop: number, scrollLeft: number }) => void) | undefined\n  onScrollToUpper: (() => void) | undefined\n  onScrollToLower: (() => void) | undefined\n  threshold: { upper: number, lower: number }\n  listContentLength: number\n}\n\n/**\n * scrollElement 模式下：监听外部滚动驱动 renderOffset，并从 scrollElement 获取 containerLength\n */\nexport function useListScrollElementAttach(\n  enabled: boolean,\n  effectiveScrollElement: RefObject<HTMLElement | null> | null,\n  effectiveStartOffset: number,\n  isHorizontal: boolean,\n  setContainerLength: (v: number) => void,\n  updateRenderOffset: (offset: number, sync?: boolean, source?: string) => void,\n  scrollRefProp: React.MutableRefObject<HTMLElement | null> | undefined,\n  refsRef: RefObject<ListScrollElementAttachRefs>\n) {\n  const effectiveStartOffsetRef = useRef(effectiveStartOffset)\n  effectiveStartOffsetRef.current = effectiveStartOffset\n\n  useEffect(() => {\n    if (!enabled || !effectiveScrollElement) return\n    const el = effectiveScrollElement.current\n    if (!el || typeof ResizeObserver === 'undefined') return\n\n    const update = () => {\n      const measured = isHorizontal ? el.clientWidth : el.clientHeight\n      if (measured > 0) setContainerLength(measured)\n      if (scrollRefProp) scrollRefProp.current = el\n    }\n    update()\n    const ro = new ResizeObserver(update)\n    ro.observe(el)\n    return () => ro.disconnect()\n  }, [enabled, effectiveScrollElement, isHorizontal, scrollRefProp, setContainerLength])\n\n  useEffect(() => {\n    if (!enabled || !effectiveScrollElement) return\n\n    let cancelled = false\n    let teardown: (() => void) | null = null\n    const maxRetries = 20\n\n    const tryAttach = (retryCount = 0) => {\n      if (cancelled) return\n      const target = effectiveScrollElement.current\n      if (!target) {\n        if (retryCount < maxRetries) {\n          requestAnimationFrame(() => tryAttach(retryCount + 1))\n        }\n        return\n      }\n\n      const refs = refsRef.current\n      if (!refs) return\n\n      let inUpperZone = true\n      let inLowerZone = false\n\n      const handler = () => {\n        const r = refsRef.current\n        if (!r) return\n        const scrollPos = isHorizontal ? target.scrollLeft : target.scrollTop\n        const adjustedPos = scrollPos - effectiveStartOffsetRef.current\n        const effectiveAdjusted = Math.max(0, adjustedPos)\n        const clientSize = isHorizontal ? target.clientWidth : target.clientHeight\n        r.scrollCorrection.markUserScrolling()\n        updateRenderOffset(effectiveAdjusted, false, 'scrollElement')\n        r.onScroll?.({ scrollTop: isHorizontal ? 0 : scrollPos, scrollLeft: isHorizontal ? scrollPos : 0 })\n\n        const { upper, lower } = r.threshold\n        const innerContentLen = r.listContentLength\n        const nowInUpper = effectiveAdjusted <= upper\n        const nowInLower = innerContentLen > 0 && effectiveAdjusted + clientSize >= innerContentLen - lower\n        if (nowInUpper && !inUpperZone) r.onScrollToUpper?.()\n        if (nowInLower && !inLowerZone) r.onScrollToLower?.()\n        inUpperZone = nowInUpper\n        inLowerZone = nowInLower\n      }\n\n      const initialScroll = isHorizontal ? target.scrollLeft : target.scrollTop\n      const initialAdjusted = Math.max(0, initialScroll - effectiveStartOffsetRef.current)\n      updateRenderOffset(initialAdjusted, false, 'scrollElement')\n\n      target.addEventListener('scroll', handler, { passive: true })\n      teardown = () => target.removeEventListener('scroll', handler)\n    }\n\n    tryAttach()\n    return () => {\n      cancelled = true\n      teardown?.()\n    }\n  }, [enabled, effectiveScrollElement, isHorizontal, effectiveStartOffset, updateRenderOffset, refsRef])\n}\n"],"names":[],"mappings":"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"}

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

@@ -1,8 +1,10 @@
 import type { RefObject } from 'react';
 /**
  * 测量 scrollElement 内 content 节点之前所有兄弟的高度/宽度之和，作为 startOffset。
- * 用于 scrollElement 模式下无 Context 时自动计算上方内容高度（与下方 DOM stacking 对称）。
- * 用「累加前兄弟尺寸」替代 offsetTop/offsetLeft，避免 offsetParent 包含外部区域导致偏大。
+ * 用于 scrollElement 模式下无 Context/props 时自动计算上方内容高度。
+ * - 直接子节点：累加前兄弟尺寸（更稳定）
+ * - 非直接子节点：getBoundingClientRect 回退，并 warning 建议传 startOffset
+ * - ref 未就绪时自动重试，确保绑定到最外层滚动容器后能正确测量
  */
 export declare function useMeasureStartOffset(scrollElRef: RefObject<HTMLElement | null>, contentRef: RefObject<HTMLElement | null>, options: {
     enabled: boolean;

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

@@ -1,41 +1,82 @@
-import { useState, useEffect } from 'react';
+import { useState, useRef, useEffect } from 'react';
 
+const WARNED_NESTED = new WeakSet();
+const MAX_RETRY = 20;
+const RETRY_DELAY = 50;
 /**
  * 测量 scrollElement 内 content 节点之前所有兄弟的高度/宽度之和，作为 startOffset。
- * 用于 scrollElement 模式下无 Context 时自动计算上方内容高度（与下方 DOM stacking 对称）。
- * 用「累加前兄弟尺寸」替代 offsetTop/offsetLeft，避免 offsetParent 包含外部区域导致偏大。
+ * 用于 scrollElement 模式下无 Context/props 时自动计算上方内容高度。
+ * - 直接子节点：累加前兄弟尺寸（更稳定）
+ * - 非直接子节点：getBoundingClientRect 回退，并 warning 建议传 startOffset
+ * - ref 未就绪时自动重试，确保绑定到最外层滚动容器后能正确测量
  */
 function useMeasureStartOffset(scrollElRef, contentRef, options) {
     const { enabled, isHorizontal = false } = options;
     const [measuredStartOffset, setMeasuredStartOffset] = useState(0);
+    const [retryTrigger, setRetryTrigger] = useState(0);
+    const retryCountRef = useRef(0);
     useEffect(() => {
-        if (!enabled)
+        if (!enabled) {
+            retryCountRef.current = 0;
             return;
+        }
         const scrollEl = scrollElRef.current;
         const contentEl = contentRef.current;
-        if (!scrollEl || !contentEl)
+        // ref 未就绪时重试（如 ScrollView 与 WaterFlow 异步挂载）
+        if (!scrollEl || !contentEl) {
+            if (retryCountRef.current < MAX_RETRY) {
+                retryCountRef.current += 1;
+                const id = setTimeout(() => setRetryTrigger((t) => t + 1), RETRY_DELAY);
+                return () => clearTimeout(id);
+            }
             return;
+        }
+        retryCountRef.current = 0;
         const measure = () => {
             const el = contentRef.current;
-            if (!el || el.parentElement !== scrollEl)
+            const scroll = scrollElRef.current;
+            if (!el || !scroll)
                 return;
-            let offset = 0;
-            let prev = el.previousElementSibling;
-            while (prev) {
-                offset += isHorizontal ? prev.offsetWidth : prev.offsetHeight;
-                prev = prev.previousElementSibling;
+            if (el.parentElement === scroll) {
+                // 直接子节点：累加前兄弟尺寸
+                let offset = 0;
+                let prev = el.previousElementSibling;
+                while (prev) {
+                    offset += isHorizontal ? prev.offsetWidth : prev.offsetHeight;
+                    prev = prev.previousElementSibling;
+                }
+                setMeasuredStartOffset((prevVal) => (Math.abs(prevVal - offset) < 1 ? prevVal : offset));
+                return;
+            }
+            // 非直接子节点：getBoundingClientRect 回退
+            const scrollRect = scroll.getBoundingClientRect();
+            const contentRect = el.getBoundingClientRect();
+            const offset = isHorizontal
+                ? contentRect.left - scrollRect.left + scroll.scrollLeft
+                : contentRect.top - scrollRect.top + scroll.scrollTop;
+            const value = Math.max(0, offset);
+            setMeasuredStartOffset((prevVal) => (Math.abs(prevVal - value) < 1 ? prevVal : value));
+            if (!WARNED_NESTED.has(el)) {
+                WARNED_NESTED.add(el);
+                // eslint-disable-next-line no-console
+                console.warn('[useMeasureStartOffset] content 不是 scrollElement 的直接子节点，使用 getBoundingClientRect 测量。' +
+                    '建议通过 props 或 Context 传入 startOffset 以获得更稳定的布局。');
             }
-            setMeasuredStartOffset((prevVal) => (Math.abs(prevVal - offset) < 1 ? prevVal : offset));
         };
         measure();
+        scrollEl.addEventListener('scroll', measure, { passive: true });
         const ro = typeof ResizeObserver !== 'undefined' ? new ResizeObserver(measure) : null;
         if (ro) {
             ro.observe(scrollEl);
-            // 同时观察 scrollEl 的直系子节点：图片加载、展开/收起等会改变兄弟高度，但 scrollEl 自身 clientHeight 不变，需观察子节点
             Array.from(scrollEl.children).forEach((child) => ro.observe(child));
-            return () => ro.disconnect();
+            // 非直接子节点：content 自身或其祖先变化时也需重测
+            ro.observe(contentEl);
         }
-    }, [enabled, scrollElRef, contentRef, isHorizontal]);
+        return () => {
+            scrollEl.removeEventListener('scroll', measure);
+            ro === null || ro === void 0 ? void 0 : ro.disconnect();
+        };
+    }, [enabled, scrollElRef, contentRef, isHorizontal, retryTrigger]);
     return measuredStartOffset;
 }
 

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

@@ -1 +1 @@
-{"version":3,"file":"useMeasureStartOffset.js","sources":["../../../../src/components/list/hooks/useMeasureStartOffset.ts"],"sourcesContent":["import { useEffect, useState } from 'react'\n\nimport type { RefObject } from 'react'\n\n/**\n * 测量 scrollElement 内 content 节点之前所有兄弟的高度/宽度之和，作为 startOffset。\n * 用于 scrollElement 模式下无 Context 时自动计算上方内容高度（与下方 DOM stacking 对称）。\n * 用「累加前兄弟尺寸」替代 offsetTop/offsetLeft，避免 offsetParent 包含外部区域导致偏大。\n */\nexport function useMeasureStartOffset(\n  scrollElRef: RefObject<HTMLElement | null>,\n  contentRef: RefObject<HTMLElement | null>,\n  options: { enabled: boolean, isHorizontal?: boolean }\n): number {\n  const { enabled, isHorizontal = false } = options\n  const [measuredStartOffset, setMeasuredStartOffset] = useState(0)\n\n  useEffect(() => {\n    if (!enabled) return\n    const scrollEl = scrollElRef.current\n    const contentEl = contentRef.current\n    if (!scrollEl || !contentEl) return\n\n    const measure = () => {\n      const el = contentRef.current\n      if (!el || el.parentElement !== scrollEl) return\n      let offset = 0\n      let prev: Element | null = el.previousElementSibling\n      while (prev) {\n        offset += isHorizontal ? (prev as HTMLElement).offsetWidth : (prev as HTMLElement).offsetHeight\n        prev = prev.previousElementSibling\n      }\n      setMeasuredStartOffset((prevVal) => (Math.abs(prevVal - offset) < 1 ? prevVal : offset))\n    }\n    measure()\n    const ro = typeof ResizeObserver !== 'undefined' ? new ResizeObserver(measure) : null\n    if (ro) {\n      ro.observe(scrollEl)\n      // 同时观察 scrollEl 的直系子节点：图片加载、展开/收起等会改变兄弟高度，但 scrollEl 自身 clientHeight 不变，需观察子节点\n      Array.from(scrollEl.children).forEach((child) => ro.observe(child))\n      return () => ro.disconnect()\n    }\n  }, [enabled, scrollElRef, contentRef, isHorizontal])\n\n  return measuredStartOffset\n}\n"],"names":[],"mappings":";;AAIA;;;;AAIG;SACa,qBAAqB,CACnC,WAA0C,EAC1C,UAAyC,EACzC,OAAqD,EAAA;IAErD,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,KAAK,EAAE,GAAG,OAAO;IACjD,MAAM,CAAC,mBAAmB,EAAE,sBAAsB,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC;IAEjE,SAAS,CAAC,MAAK;AACb,QAAA,IAAI,CAAC,OAAO;YAAE;AACd,QAAA,MAAM,QAAQ,GAAG,WAAW,CAAC,OAAO;AACpC,QAAA,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO;AACpC,QAAA,IAAI,CAAC,QAAQ,IAAI,CAAC,SAAS;YAAE;QAE7B,MAAM,OAAO,GAAG,MAAK;AACnB,YAAA,MAAM,EAAE,GAAG,UAAU,CAAC,OAAO;AAC7B,YAAA,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,aAAa,KAAK,QAAQ;gBAAE;YAC1C,IAAI,MAAM,GAAG,CAAC;AACd,YAAA,IAAI,IAAI,GAAmB,EAAE,CAAC,sBAAsB;YACpD,OAAO,IAAI,EAAE;AACX,gBAAA,MAAM,IAAI,YAAY,GAAI,IAAoB,CAAC,WAAW,GAAI,IAAoB,CAAC,YAAY;AAC/F,gBAAA,IAAI,GAAG,IAAI,CAAC,sBAAsB;;YAEpC,sBAAsB,CAAC,CAAC,OAAO,MAAM,IAAI,CAAC,GAAG,CAAC,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,OAAO,GAAG,MAAM,CAAC,CAAC;AAC1F,SAAC;AACD,QAAA,OAAO,EAAE;AACT,QAAA,MAAM,EAAE,GAAG,OAAO,cAAc,KAAK,WAAW,GAAG,IAAI,cAAc,CAAC,OAAO,CAAC,GAAG,IAAI;QACrF,IAAI,EAAE,EAAE;AACN,YAAA,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC;;YAEpB,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,KAAK,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AACnE,YAAA,OAAO,MAAM,EAAE,CAAC,UAAU,EAAE;;KAE/B,EAAE,CAAC,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,YAAY,CAAC,CAAC;AAEpD,IAAA,OAAO,mBAAmB;AAC5B;;;;"}
+{"version":3,"file":"useMeasureStartOffset.js","sources":["../../../../src/components/list/hooks/useMeasureStartOffset.ts"],"sourcesContent":["import { useEffect, useRef, useState } from 'react'\n\nimport type { RefObject } from 'react'\n\nconst WARNED_NESTED = new WeakSet<Element>()\nconst MAX_RETRY = 20\nconst RETRY_DELAY = 50\n\n/**\n * 测量 scrollElement 内 content 节点之前所有兄弟的高度/宽度之和，作为 startOffset。\n * 用于 scrollElement 模式下无 Context/props 时自动计算上方内容高度。\n * - 直接子节点：累加前兄弟尺寸（更稳定）\n * - 非直接子节点：getBoundingClientRect 回退，并 warning 建议传 startOffset\n * - ref 未就绪时自动重试，确保绑定到最外层滚动容器后能正确测量\n */\nexport function useMeasureStartOffset(\n  scrollElRef: RefObject<HTMLElement | null>,\n  contentRef: RefObject<HTMLElement | null>,\n  options: { enabled: boolean, isHorizontal?: boolean }\n): number {\n  const { enabled, isHorizontal = false } = options\n  const [measuredStartOffset, setMeasuredStartOffset] = useState(0)\n  const [retryTrigger, setRetryTrigger] = useState(0)\n  const retryCountRef = useRef(0)\n\n  useEffect(() => {\n    if (!enabled) {\n      retryCountRef.current = 0\n      return\n    }\n    const scrollEl = scrollElRef.current\n    const contentEl = contentRef.current\n\n    // ref 未就绪时重试（如 ScrollView 与 WaterFlow 异步挂载）\n    if (!scrollEl || !contentEl) {\n      if (retryCountRef.current < MAX_RETRY) {\n        retryCountRef.current += 1\n        const id = setTimeout(() => setRetryTrigger((t) => t + 1), RETRY_DELAY)\n        return () => clearTimeout(id)\n      }\n      return\n    }\n    retryCountRef.current = 0\n\n    const measure = () => {\n      const el = contentRef.current\n      const scroll = scrollElRef.current\n      if (!el || !scroll) return\n\n      if (el.parentElement === scroll) {\n        // 直接子节点：累加前兄弟尺寸\n        let offset = 0\n        let prev: Element | null = el.previousElementSibling\n        while (prev) {\n          offset += isHorizontal ? (prev as HTMLElement).offsetWidth : (prev as HTMLElement).offsetHeight\n          prev = prev.previousElementSibling\n        }\n        setMeasuredStartOffset((prevVal) => (Math.abs(prevVal - offset) < 1 ? prevVal : offset))\n        return\n      }\n\n      // 非直接子节点：getBoundingClientRect 回退\n      const scrollRect = scroll.getBoundingClientRect()\n      const contentRect = el.getBoundingClientRect()\n      const offset = isHorizontal\n        ? contentRect.left - scrollRect.left + scroll.scrollLeft\n        : contentRect.top - scrollRect.top + scroll.scrollTop\n      const value = Math.max(0, offset)\n      setMeasuredStartOffset((prevVal) => (Math.abs(prevVal - value) < 1 ? prevVal : value))\n\n      if (!WARNED_NESTED.has(el)) {\n        WARNED_NESTED.add(el)\n        // eslint-disable-next-line no-console\n        console.warn(\n          '[useMeasureStartOffset] content 不是 scrollElement 的直接子节点，使用 getBoundingClientRect 测量。' +\n            '建议通过 props 或 Context 传入 startOffset 以获得更稳定的布局。'\n        )\n      }\n    }\n\n    measure()\n    scrollEl.addEventListener('scroll', measure, { passive: true })\n    const ro = typeof ResizeObserver !== 'undefined' ? new ResizeObserver(measure) : null\n    if (ro) {\n      ro.observe(scrollEl)\n      Array.from(scrollEl.children).forEach((child) => ro.observe(child))\n      // 非直接子节点：content 自身或其祖先变化时也需重测\n      ro.observe(contentEl)\n    }\n    return () => {\n      scrollEl.removeEventListener('scroll', measure)\n      ro?.disconnect()\n    }\n  }, [enabled, scrollElRef, contentRef, isHorizontal, retryTrigger])\n\n  return measuredStartOffset\n}\n"],"names":[],"mappings":"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"}

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

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

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

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

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

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

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

@@ -1,3 +1,4 @@
+/// <reference types="@tarojs/components-react" />
 import React from 'react';
 import ListItem from './ListItem';
 import NoMore from './NoMore';
@@ -70,11 +71,11 @@ export interface ListProps {
             dy?: number;
         };
     }) => void;
-    /** 滚动模式：default=自有 ScrollView；nested=使用父级滚动（需配合 scrollElement 或 Context） */
-    type?: 'default' | 'nested';
-    /** 自定义滚动容器 ref，type=nested 时从 props 或 Context 获取 */
+    /** 是否嵌套模式，与 plato 对齐；true=使用父级滚动，需配合 scrollElement 或 Context；不传或 false=default */
+    nestedScroll?: boolean;
+    /** 自定义滚动容器 ref，nestedScroll 模式下从 props 或 Context 获取 */
     scrollElement?: React.RefObject<HTMLElement | null>;
-    /** 任务 2.3：暴露滚动容器 ref，供内层 List/WaterFlow（type=nested）使用 */
+    /** 任务 2.3：暴露滚动容器 ref，供内层 List/WaterFlow（nestedScroll）使用 */
     scrollRef?: React.MutableRefObject<HTMLElement | null>;
 }
 export interface ListHandle {
@@ -85,14 +86,8 @@ export interface ListHandle {
 }
 export declare function accumulate(arr: number[]): number[];
 export declare function isShaking(diffList: number[]): boolean;
-/** 任务 4.1/4.2：List 内嵌 WaterFlow/List 时，向子组件提供 scrollRef、containerHeight、startOffset、reportNestedHeightChange */
-export declare const ListScrollElementContext: React.Context<{
-    scrollRef: React.MutableRefObject<HTMLElement | null>;
-    containerHeight: number;
-    startOffset: number;
-    /** 任务 4.2：内层 WaterFlow 报告 scrollHeight 时调用，List 会加上 header 估算后更新 sizeCache */
-    reportNestedHeightChange?: (scrollHeight: number) => void;
-}>;
+/** 向后兼容：ListScrollElementContext 已统一为 ScrollElementContext */
+export { ScrollElementContext as ListScrollElementContext } from '@tarojs/components-react';
 declare const List: React.ForwardRefExoticComponent<ListProps & React.RefAttributes<ListHandle>>;
 export { List, ListItem, NoMore, StickyHeader, StickySection };
 export default List;