@tarojs/components-advanced 4.2.0 → 4.2.1-beta.1

package/dist/components/water-flow/flow-item.js

@@ -15,9 +15,7 @@ const useFlowItemPositioner = () => {
     const scrollTop$ = useObservedAttr(nodeModel, 'scrollTop');
     return {
         resize: useMemoizedFn(() => {
-            if (!isWeb()) {
-                nodeModel.pub(NodeEvents.Resize);
-            }
+            nodeModel.pub(NodeEvents.Resize);
         }),
         top: top$,
         scrollTop: scrollTop$,
@@ -35,32 +33,41 @@ function FlowItemContainer(_a) {
     const itemStyle = useMemo(() => {
         const baseStyle = {
             width: '100%',
-            minHeight: node.section.defaultSize,
+            position: 'absolute',
+            top: 0,
+            left: 0,
+            transform: `translate3d(0px, ${top$}px, 0px)`,
         };
         if (!layouted$) {
-            return baseStyle;
+            return Object.assign(Object.assign({}, baseStyle), { minHeight: node.section.defaultSize });
         }
-        Reflect.deleteProperty(baseStyle, 'minHeight');
-        return Object.assign(Object.assign({}, baseStyle), { height: height$, transition: 'transform 20ms cubic-bezier(0.075, 0.82, 0.165, 1)', willChange: 'transform', position: 'absolute', top: 0, left: 0, transform: `translate3d(0px, ${top$}px, 0px)` });
+        return Object.assign(Object.assign({}, baseStyle), { height: height$ });
     }, [top$, layouted$, height$]);
+    const setInnerMeasureRef = useMemoizedFn((el) => {
+        const innerRef = refFlowItem;
+        innerRef.current = el !== null && el !== void 0 ? el : undefined;
+        node.attachMeasureElement(el);
+    });
     useEffect(() => {
         let observer;
-        if (isWeb() && typeof ResizeObserver !== 'undefined') {
+        const el = refFlowItem.current;
+        if (isWeb() && typeof ResizeObserver !== 'undefined' && el) {
             observer = new ResizeObserver(() => {
                 node.pub(NodeEvents.Resize);
             });
-            observer.observe(refFlowItem.current);
+            observer.observe(el);
         }
         return () => {
             if (observer) {
                 observer.disconnect();
             }
+            node.attachMeasureElement(null);
         };
     }, [node]);
     useLayoutEffect(() => {
-        node.measure();
+        node.measure().catch(() => { });
     }, [node]);
-    return createElement(View, { style: itemStyle, key: node.id }, createElement(View, { id: node.id, ref: refFlowItem }, createElement(FlowItemContext.Provider, { value: { node } }, children)));
+    return createElement(View, { style: itemStyle, key: node.id }, createElement(View, { id: node.id, ref: setInnerMeasureRef }, createElement(FlowItemContext.Provider, { value: { node } }, children)));
 }
 function FlowItem(props) {
     return props.children;

package/dist/components/water-flow/flow-item.js.map

@@ -1 +1 @@
-{"version":3,"file":"flow-item.js","sources":["../../../src/components/water-flow/flow-item.ts"],"sourcesContent":["import { View } from '@tarojs/components'\nimport {\n  type CSSProperties,\n  type PropsWithChildren,\n  createContext,\n  createElement,\n  useContext,\n  useEffect,\n  useLayoutEffect,\n  useMemo,\n  useRef,\n} from 'react'\n\nimport { Node, NodeEvents } from './node'\nimport { useMemoizedFn } from './use-memoized-fn'\nimport { useObservedAttr } from './use-observed-attr'\nimport { isWeb } from './utils'\n\nimport type { FlowItemContainerProps } from './interface'\n\nconst FlowItemContext = createContext<{ node: Node }>(Object.create(null))\nexport const useFlowItemPositioner = () => {\n  const nodeModel = useContext(FlowItemContext).node\n  const width$ = useObservedAttr(nodeModel, 'width')\n  const height$ = useObservedAttr(nodeModel, 'height')\n  const top$ = useObservedAttr(nodeModel, 'top')\n  const scrollTop$ = useObservedAttr(nodeModel, 'scrollTop')\n\n  return {\n    resize: useMemoizedFn(() => {\n      if (!isWeb()) {\n        nodeModel.pub(NodeEvents.Resize)\n      }\n    }),\n    top: top$,\n    scrollTop: scrollTop$,\n    width: width$,\n    height: height$,\n  }\n}\n\nexport function FlowItemContainer({\n  children,\n  ...props\n}: PropsWithChildren<FlowItemContainerProps>) {\n  const { node } = props\n  const layouted$ = useObservedAttr(node, 'layouted')\n  const top$ = useObservedAttr(node, 'top')\n  const height$ = useObservedAttr(node, 'height')\n  const refFlowItem = useRef<HTMLElement>()\n\n  const itemStyle: CSSProperties = useMemo(() => {\n    const baseStyle: CSSProperties = {\n      width: '100%',\n      minHeight: node.section.defaultSize,\n    }\n    if (!layouted$) {\n      return baseStyle\n    }\n    Reflect.deleteProperty(baseStyle, 'minHeight')\n    return {\n      ...baseStyle,\n      height: height$,\n      transition: 'transform 20ms cubic-bezier(0.075, 0.82, 0.165, 1)',\n      willChange: 'transform',\n      position: 'absolute',\n      top: 0,\n      left: 0,\n      transform: `translate3d(0px, ${top$}px, 0px)`,\n    }\n  }, [top$, layouted$, height$])\n\n  useEffect(() => {\n    let observer: ResizeObserver\n    if (isWeb() && typeof ResizeObserver !== 'undefined') {\n      observer = new ResizeObserver(() => {\n        node.pub(NodeEvents.Resize)\n      })\n      observer.observe(refFlowItem.current!)\n    }\n    return () => {\n      if (observer) {\n        observer.disconnect()\n      }\n    }\n  }, [node])\n\n  useLayoutEffect(() => {\n    node.measure()\n  }, [node])\n\n  return createElement(\n    View,\n    { style: itemStyle, key: node.id },\n    createElement(\n      View,\n      { id: node.id, ref: refFlowItem },\n      createElement(FlowItemContext.Provider, { value: { node } }, children)\n    )\n  )\n}\n\nexport function FlowItem(props: PropsWithChildren) {\n  return props.children\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"flow-item.js","sources":["../../../src/components/water-flow/flow-item.ts"],"sourcesContent":["import { View } from '@tarojs/components'\nimport {\n  type CSSProperties,\n  type PropsWithChildren,\n  createContext,\n  createElement,\n  useContext,\n  useEffect,\n  useLayoutEffect,\n  useMemo,\n  useRef,\n} from 'react'\n\nimport { Node, NodeEvents } from './node'\nimport { useMemoizedFn } from './use-memoized-fn'\nimport { useObservedAttr } from './use-observed-attr'\nimport { isWeb } from './utils'\n\nimport type { FlowItemContainerProps } from './interface'\n\nconst FlowItemContext = createContext<{ node: Node }>(Object.create(null))\nexport const useFlowItemPositioner = () => {\n  const nodeModel = useContext(FlowItemContext).node\n  const width$ = useObservedAttr(nodeModel, 'width')\n  const height$ = useObservedAttr(nodeModel, 'height')\n  const top$ = useObservedAttr(nodeModel, 'top')\n  const scrollTop$ = useObservedAttr(nodeModel, 'scrollTop')\n\n  return {\n    resize: useMemoizedFn(() => {\n      nodeModel.pub(NodeEvents.Resize)\n    }),\n    top: top$,\n    scrollTop: scrollTop$,\n    width: width$,\n    height: height$,\n  }\n}\n\nexport function FlowItemContainer({\n  children,\n  ...props\n}: PropsWithChildren<FlowItemContainerProps>) {\n  const { node } = props\n  const layouted$ = useObservedAttr(node, 'layouted')\n  const top$ = useObservedAttr(node, 'top')\n  const height$ = useObservedAttr(node, 'height')\n  const refFlowItem = useRef<HTMLElement>()\n\n  const itemStyle: CSSProperties = useMemo(() => {\n    const baseStyle: CSSProperties = {\n      width: '100%',\n      position: 'absolute',\n      top: 0,\n      left: 0,\n      transform: `translate3d(0px, ${top$}px, 0px)`,\n    }\n    if (!layouted$) {\n      return {\n        ...baseStyle,\n        minHeight: node.section.defaultSize,\n      }\n    }\n    return {\n      ...baseStyle,\n      height: height$,\n    }\n  }, [top$, layouted$, height$])\n\n  const setInnerMeasureRef = useMemoizedFn((el: HTMLElement | null) => {\n    const innerRef = refFlowItem as React.MutableRefObject<HTMLElement | undefined>\n    innerRef.current = el ?? undefined\n    node.attachMeasureElement(el)\n  })\n\n  useEffect(() => {\n    let observer: ResizeObserver\n    const el = refFlowItem.current\n    if (isWeb() && typeof ResizeObserver !== 'undefined' && el) {\n      observer = new ResizeObserver(() => {\n        node.pub(NodeEvents.Resize)\n      })\n      observer.observe(el)\n    }\n    return () => {\n      if (observer) {\n        observer.disconnect()\n      }\n      node.attachMeasureElement(null)\n    }\n  }, [node])\n\n  useLayoutEffect(() => {\n    node.measure().catch(() => {})\n  }, [node])\n\n  return createElement(\n    View,\n    { style: itemStyle, key: node.id },\n    createElement(\n      View,\n      { id: node.id, ref: setInnerMeasureRef as any },\n      createElement(FlowItemContext.Provider, { value: { node } }, children)\n    )\n  )\n}\n\nexport function FlowItem(props: PropsWithChildren) {\n  return props.children\n}\n"],"names":[],"mappings":"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"}

package/dist/components/water-flow/flow-section.js

@@ -58,7 +58,7 @@ function FlowSection(_a) {
                 return createElement(FlowItemContainer, columnProps, childNode);
             }));
         });
-    }, [children, layouted$, section.columnMap, renderRange$, id]);
+    }, [children, layouted$, section.columnMap, renderRange$]);
     return createElement(View, { style: sectionStyle, className, id: id !== null && id !== void 0 ? id : section.id }, columns);
 }
 

package/dist/components/water-flow/flow-section.js.map

@@ -1 +1 @@
-{"version":3,"file":"flow-section.js","sources":["../../../src/components/water-flow/flow-section.ts"],"sourcesContent":["import { View } from '@tarojs/components'\nimport {\n  type CSSProperties,\n  type PropsWithChildren,\n  Children,\n  createElement,\n  useMemo,\n} from 'react'\n\nimport { FlowItemContainer } from './flow-item'\nimport { Section } from './section'\nimport { useObservedAttr } from './use-observed-attr'\n\nimport type { FlowSectionProps } from './interface'\n\nexport interface _FlowSectionProps extends FlowSectionProps {\n  section: Section\n}\n\nexport function FlowSection({\n  children,\n  ...props\n}: PropsWithChildren<FlowSectionProps>) {\n  const {\n    id,\n    className,\n    style,\n    section,\n    rowGap = 0,\n    columnGap = 0,\n  } = props as _FlowSectionProps\n  const layouted$ = useObservedAttr(section, 'layouted')\n  const height$ = useObservedAttr(section, 'height')\n  const renderRange$ = useObservedAttr(section, 'renderRange')\n  const scrollTop$ = useObservedAttr(section, 'scrollTop')\n\n  const sectionStyle: CSSProperties = useMemo(() => {\n    const baseStyle: CSSProperties = {\n      display: 'flex',\n      flexDirection: 'row',\n      width: '100%',\n      height: height$,\n      gap: columnGap,\n      visibility: layouted$ ? 'visible' : 'hidden',\n      ...style,\n    }\n\n    if (!layouted$) {\n      return baseStyle\n    }\n\n    return {\n      ...baseStyle,\n      position: 'absolute',\n      top: 0,\n      transform: `translate3d(0px, ${scrollTop$}px, 0px)`,\n      left: 0,\n    }\n  }, [height$, style, layouted$, scrollTop$, columnGap])\n\n  const columns = useMemo(() => {\n    const childNodes = Children.toArray(children)\n    const columnStyle: CSSProperties = {\n      position: 'relative',\n      display: 'flex',\n      flexDirection: 'column',\n      gap: rowGap,\n      flex: 1,\n    }\n    /** 已经完成布局计算，使用虚拟滚动 */\n    if (layouted$) {\n      return renderRange$.map(([startIndex, endIndex], colIndex) => {\n        const columnId = `col-${colIndex}`\n        return createElement(\n          View,\n          {\n            style: columnStyle,\n            id: columnId,\n            key: columnId,\n          },\n          section.columnMap[colIndex]\n            .slice(startIndex, endIndex + 1)\n            .map((node) => {\n              const childNode = childNodes[node.childIndex]\n              const columnProps: any = {\n                node,\n                key: node.id,\n              }\n              return createElement(FlowItemContainer, columnProps, childNode)\n            })\n        )\n      })\n    }\n\n    return section.columnMap.map((column, colIndex) => {\n      const columnId = `col-${colIndex}`\n      return createElement(\n        View,\n        { style: columnStyle, id: columnId, key: columnId },\n        column.map((node) => {\n          const childNode = childNodes[node.childIndex]\n          const columnProps: any = {\n            node,\n            key: node.id,\n          }\n          return createElement(FlowItemContainer, columnProps, childNode)\n        })\n      )\n    })\n  }, [children, layouted$, section.columnMap, renderRange$, id])\n\n  return createElement(\n    View,\n    { style: sectionStyle, className, id: id ?? section.id },\n    columns\n  )\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"flow-section.js","sources":["../../../src/components/water-flow/flow-section.ts"],"sourcesContent":["import { View } from '@tarojs/components'\nimport {\n  type CSSProperties,\n  type PropsWithChildren,\n  Children,\n  createElement,\n  useMemo,\n} from 'react'\n\nimport { FlowItemContainer } from './flow-item'\nimport { Section } from './section'\nimport { useObservedAttr } from './use-observed-attr'\n\nimport type { FlowSectionProps } from './interface'\n\nexport interface _FlowSectionProps extends FlowSectionProps {\n  section: Section\n}\n\nexport function FlowSection({\n  children,\n  ...props\n}: PropsWithChildren<FlowSectionProps>) {\n  const {\n    id,\n    className,\n    style,\n    section,\n    rowGap = 0,\n    columnGap = 0,\n  } = props as _FlowSectionProps\n  const layouted$ = useObservedAttr(section, 'layouted')\n  const height$ = useObservedAttr(section, 'height')\n  const renderRange$ = useObservedAttr(section, 'renderRange')\n  const scrollTop$ = useObservedAttr(section, 'scrollTop')\n\n  const sectionStyle: CSSProperties = useMemo(() => {\n    const baseStyle: CSSProperties = {\n      display: 'flex',\n      flexDirection: 'row',\n      width: '100%',\n      height: height$,\n      gap: columnGap,\n      visibility: layouted$ ? 'visible' : 'hidden',\n      ...style,\n    }\n\n    if (!layouted$) {\n      return baseStyle\n    }\n\n    return {\n      ...baseStyle,\n      position: 'absolute',\n      top: 0,\n      transform: `translate3d(0px, ${scrollTop$}px, 0px)`,\n      left: 0,\n    }\n  }, [height$, style, layouted$, scrollTop$, columnGap])\n\n  const columns = useMemo(() => {\n    const childNodes = Children.toArray(children)\n    const columnStyle: CSSProperties = {\n      position: 'relative',\n      display: 'flex',\n      flexDirection: 'column',\n      gap: rowGap,\n      flex: 1,\n    }\n    /** 已经完成布局计算，使用虚拟滚动 */\n    if (layouted$) {\n      return renderRange$.map(([startIndex, endIndex], colIndex) => {\n        const columnId = `col-${colIndex}`\n        return createElement(\n          View,\n          {\n            style: columnStyle,\n            id: columnId,\n            key: columnId,\n          },\n          section.columnMap[colIndex]\n            .slice(startIndex, endIndex + 1)\n            .map((node) => {\n              const childNode = childNodes[node.childIndex]\n              const columnProps: any = {\n                node,\n                key: node.id,\n              }\n              return createElement(FlowItemContainer, columnProps, childNode)\n            })\n        )\n      })\n    }\n\n    return section.columnMap.map((column, colIndex) => {\n      const columnId = `col-${colIndex}`\n      return createElement(\n        View,\n        { style: columnStyle, id: columnId, key: columnId },\n        column.map((node) => {\n          const childNode = childNodes[node.childIndex]\n          const columnProps: any = {\n            node,\n            key: node.id,\n          }\n          return createElement(FlowItemContainer, columnProps, childNode)\n        })\n      )\n    })\n  }, [children, layouted$, section.columnMap, renderRange$])\n\n  return createElement(\n    View,\n    { style: sectionStyle, className, id: id ?? section.id },\n    columns\n  )\n}\n"],"names":[],"mappings":"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"}

package/dist/components/water-flow/index.d.ts

@@ -1,4 +1,4 @@
 export { FlowItem, useFlowItemPositioner } from './flow-item';
 export { FlowSection } from './flow-section';
-export type { FlowSectionProps, WaterFlowProps } from './interface';
+export type { FlowSectionProps, WaterFlowProps, WaterFlowRef } from './interface';
 export { WaterFlow } from './water-flow';

package/dist/components/water-flow/interface.d.ts

@@ -1,12 +1,12 @@
 import { ScrollViewProps } from '@tarojs/components';
 import { Node } from './node';
-import type { CSSProperties } from 'react';
+import type { CSSProperties, RefObject } from 'react';
 export interface BaseProps {
     id?: string;
     className?: string;
     style?: CSSProperties;
 }
-export interface WaterFlowProps extends Omit<ScrollViewProps, 'cacheExtent' | 'upperThreshold' | 'lowerThreshold' | 'style'>, Pick<BaseProps, 'style'> {
+export interface WaterFlowProps extends Omit<ScrollViewProps, 'cacheExtent' | 'upperThreshold' | 'lowerThreshold' | 'style' | 'type'>, Pick<BaseProps, 'style'> {
     /**
      * 距顶部多少个FlowItem时，触发 scrolltoupper 事件
      * @default 0
@@ -22,6 +22,36 @@ export interface WaterFlowProps extends Omit<ScrollViewProps, 'cacheExtent' | 'u
      * @default 50
      */
     cacheCount?: number;
+    /**
+     * 滚动事件。与内部虚拟列表滚动处理链式调用，不会覆盖触底/分页逻辑。
+     * 仅 default 模式（自带 ScrollView）时生效。
+     */
+    onScroll?: ScrollViewProps['onScroll'];
+    /**
+     * 受控竖向滚动位置。仅传入有效 number 时下发给 ScrollView；
+     * undefined/null 表示取消受控（避免 H5 将 null 转为 0 导致归顶）。
+     */
+    scrollTop?: number;
+    /**
+     * 受控横向滚动位置，语义同 scrollTop。
+     */
+    scrollLeft?: number;
+    /** 是否嵌套模式，与 plato 对齐；true=使用父级滚动，需配合 scrollElement 或 Context；不传或 false=default */
+    nestedScroll?: boolean;
+    /** 自定义滚动容器 ref，nestedScroll 模式下从 props 或 Context 获取 */
+    scrollElement?: RefObject<HTMLElement | null>;
+    /** WaterFlow 内容在滚动容器中的起始偏移（上方有其他内容时使用） */
+    startOffset?: number;
+    /** 可视区高度，scrollElement 模式下可选，不传则从 scrollElement.clientHeight 获取 */
+    containerHeight?: number;
+    /** 瀑布流内容高度变化时回调，便于 List 动高联动（避免底部空白） */
+    onScrollHeightChange?: (height: number) => void;
+    /** scrollIntoView 滚动完成后回调，便于父组件清空 scrollIntoView 以支持重复点击同一目标 */
+    onScrollIntoViewComplete?: () => void;
+}
+/** WaterFlow ref 类型，current 指向内容容器，用于 IntersectionObserver root、SelectorQuery.in 等 */
+export interface WaterFlowRef {
+    current: HTMLElement | null;
 }
 export interface FlowSectionProps extends BaseProps {
     /**

package/dist/components/water-flow/node.d.ts

@@ -29,6 +29,8 @@ export declare const NodeEvents: {
 export declare class Node extends StatefulEventBus<NodeState> {
     root: Root;
     section: Section;
+    /** 小程序：测量用内层 View 的 DOM；H5：getBoundingClientRect 用 */
+    private _measureEl;
     id: string;
     /**
      * 原始索引，即一维数组中的索引
@@ -43,6 +45,7 @@ export declare class Node extends StatefulEventBus<NodeState> {
      */
     col: number;
     constructor(root: Root, section: Section, props: NodeProps);
+    attachMeasureElement(el: HTMLElement | null): void;
     private setupSubscriptions;
     /**
      * 测量节点的尺寸信息

package/dist/components/water-flow/node.js

@@ -1,6 +1,8 @@
 import '../../utils/index.js';
 import { SectionEvents } from './section.js';
 import { StatefulEventBus } from './stateful-event-bus.js';
+import { isWeb, isWeapp } from './utils.js';
+import { weappScope } from '../../utils/weapp-scope.js';
 import { getRectSizeSync } from '../../utils/dom.js';
 
 const NodeEvents = {
@@ -18,10 +20,15 @@ class Node extends StatefulEventBus {
         });
         this.root = root;
         this.section = section;
+        /** 小程序：测量用内层 View 的 DOM；H5：getBoundingClientRect 用 */
+        this._measureEl = null;
         const nodeId = `${root.id}-${section.id}-item-${childIndex}`;
         Object.assign(this, { id: nodeId, childIndex, order, col });
         this.setupSubscriptions();
     }
+    attachMeasureElement(el) {
+        this._measureEl = el;
+    }
     setupSubscriptions() {
         this.sub('layouted', () => {
             /**
@@ -56,7 +63,33 @@ class Node extends StatefulEventBus {
      * 测量节点的尺寸信息
      */
     async measure() {
-        const { height, width } = await getRectSizeSync(`#${this.id}`, 100, 3);
+        let width;
+        let height;
+        if (isWeb() && this._measureEl) {
+            const r = this._measureEl.getBoundingClientRect();
+            width = r.width;
+            height = r.height;
+        }
+        else if (isWeapp && this._measureEl) {
+            const scope = weappScope({ current: this._measureEl });
+            const res = await getRectSizeSync(`#${this.id}`, 100, 3, scope);
+            width = res.width;
+            height = res.height;
+        }
+        else {
+            const res = await getRectSizeSync(`#${this.id}`, 100, 3);
+            width = res.width;
+            height = res.height;
+        }
+        if (typeof width !== 'number' ||
+            typeof height !== 'number' ||
+            !Number.isFinite(width) ||
+            !Number.isFinite(height) ||
+            width <= 0 ||
+            height <= 0) {
+            const s = this.getState();
+            return { width: s.width, height: s.height };
+        }
         this.setStateBatch({
             width,
             height,

package/dist/components/water-flow/node.js.map

@@ -1 +1 @@
-{"version":3,"file":"node.js","sources":["../../../src/components/water-flow/node.ts"],"sourcesContent":["import { getRectSizeSync } from '../../utils'\nimport { Root } from './root'\nimport { Section, SectionEvents } from './section'\nimport { StatefulEventBus } from './stateful-event-bus'\n\ninterface NodeProps {\n  /**\n   * 原始索引，即一维数组中的索引\n   */\n  childIndex: number\n  /**\n   * 在列里的顺序\n   */\n  order: number\n  /**\n   * 位于哪一列\n   */\n  col: number\n  height: number\n}\n\ntype NodeState = {\n  top: number\n  width: number\n  height: number\n  layouted: boolean\n  scrollTop: number\n};\n\nexport const NodeEvents = {\n  Resize: Symbol.for('resize'),\n}\n\nexport class Node extends StatefulEventBus<NodeState> {\n  id: string\n  /**\n   * 原始索引，即一维数组中的索引\n   */\n  childIndex: number\n  /**\n   * 在列里的顺序\n   */\n  order: number\n  /**\n   * 位于哪一列\n   */\n  col: number\n  constructor(public root: Root, public section: Section, props: NodeProps) {\n    const { height, childIndex, order, col } = props\n    super({\n      top: 0,\n      width: 0,\n      height,\n      scrollTop: 0,\n      layouted: false,\n    })\n    const nodeId = `${root.id}-${section.id}-item-${childIndex}`\n    Object.assign(this, { id: nodeId, childIndex, order, col })\n    this.setupSubscriptions()\n  }\n\n  private setupSubscriptions() {\n    this.sub('layouted', () => {\n      /**\n       * 如果当前分组所有的节点都完成布局计算，那么向分组推送 `AllNodesLayouted` 事件，section会在这个时机做一些计算\n       */\n      if (\n        [...this.section.nodes.values()].every(\n          (node) => node.getState().layouted\n        )\n      ) {\n        this.section.notify(SectionEvents.AllNodesLayouted)\n      }\n    })\n\n    /**\n     * 如果节点的尺寸发生了变化（这通常出现在节点内容包含网络数据的情况下，比如图片，这时要求用户调用 useFlowItemPositioner 返回的 resize 方法通知数据模型去重新计算布局）\n     *\n     * - 更新当前节点所在列之后的所有节点的位置信息\n     *\n     * - 通知 section 更新布局\n     */\n    this.sub(NodeEvents.Resize, async () => {\n      const { width, height } = this.getState()\n      const newSize = await this.measure()\n      if (newSize.height === height && newSize.width === width) {\n        return\n      }\n      this.updateBehindNodesPosition()\n      this.section.pub(SectionEvents.Resize, {\n        node: this,\n        newSize,\n        originalSize: { width, height },\n      })\n    })\n  }\n\n  /**\n   * 测量节点的尺寸信息\n   */\n  public async measure() {\n    const { height, width } = await getRectSizeSync(`#${this.id}`, 100, 3)\n    this.setStateBatch({\n      width,\n      height,\n      layouted: true,\n    })\n    return { width, height }\n  }\n\n  /**\n   * 更新节点所在列后面的节点的位置\n   */\n  updateBehindNodesPosition() {\n    const currentColumn = this.section.columnMap[this.col]\n    let start = this.order + 1\n\n    if (start > currentColumn.length - 1) {\n      return\n    }\n    for (; start < currentColumn.length; start++) {\n      const node = currentColumn[start]\n      const previousNode = currentColumn[start - 1]\n      const {\n        top: previousNodeTop,\n        height: previousNodeHeight,\n        scrollTop: previousNodeScrollTop,\n      } = previousNode.getState()\n      const rowGap = this.section.rowGap\n      node.setStateBatch({\n        top: previousNodeTop + previousNodeHeight + rowGap,\n        scrollTop: previousNodeScrollTop + previousNodeHeight + rowGap,\n      })\n    }\n  }\n\n  /**\n   * 节点是否可见\n   */\n  get isInRange() {\n    const { scrollBoundaryStart, scrollBoundaryEnd } = this.root\n    const { height: nodeHeight, scrollTop: nodeScrollTop } = this.getState()\n    return (\n      nodeScrollTop < scrollBoundaryEnd &&\n      nodeScrollTop + nodeHeight > scrollBoundaryStart\n    )\n  }\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"node.js","sources":["../../../src/components/water-flow/node.ts"],"sourcesContent":["import { getRectSizeSync, weappScope } from '../../utils'\nimport { Root } from './root'\nimport { Section, SectionEvents } from './section'\nimport { StatefulEventBus } from './stateful-event-bus'\nimport { isWeapp, isWeb } from './utils'\n\ninterface NodeProps {\n  /**\n   * 原始索引，即一维数组中的索引\n   */\n  childIndex: number\n  /**\n   * 在列里的顺序\n   */\n  order: number\n  /**\n   * 位于哪一列\n   */\n  col: number\n  height: number\n}\n\ntype NodeState = {\n  top: number\n  width: number\n  height: number\n  layouted: boolean\n  scrollTop: number\n};\n\nexport const NodeEvents = {\n  Resize: Symbol.for('resize'),\n}\n\nexport class Node extends StatefulEventBus<NodeState> {\n  /** 小程序：测量用内层 View 的 DOM；H5：getBoundingClientRect 用 */\n  private _measureEl: HTMLElement | null = null\n\n  id: string\n  /**\n   * 原始索引，即一维数组中的索引\n   */\n  childIndex: number\n  /**\n   * 在列里的顺序\n   */\n  order: number\n  /**\n   * 位于哪一列\n   */\n  col: number\n  constructor(public root: Root, public section: Section, props: NodeProps) {\n    const { height, childIndex, order, col } = props\n    super({\n      top: 0,\n      width: 0,\n      height,\n      scrollTop: 0,\n      layouted: false,\n    })\n    const nodeId = `${root.id}-${section.id}-item-${childIndex}`\n    Object.assign(this, { id: nodeId, childIndex, order, col })\n    this.setupSubscriptions()\n  }\n\n  attachMeasureElement (el: HTMLElement | null) {\n    this._measureEl = el\n  }\n\n  private setupSubscriptions() {\n    this.sub('layouted', () => {\n      /**\n       * 如果当前分组所有的节点都完成布局计算，那么向分组推送 `AllNodesLayouted` 事件，section会在这个时机做一些计算\n       */\n      if (\n        [...this.section.nodes.values()].every(\n          (node) => node.getState().layouted\n        )\n      ) {\n        this.section.notify(SectionEvents.AllNodesLayouted)\n      }\n    })\n\n    /**\n     * 如果节点的尺寸发生了变化（这通常出现在节点内容包含网络数据的情况下，比如图片，这时要求用户调用 useFlowItemPositioner 返回的 resize 方法通知数据模型去重新计算布局）\n     *\n     * - 更新当前节点所在列之后的所有节点的位置信息\n     *\n     * - 通知 section 更新布局\n     */\n    this.sub(NodeEvents.Resize, async () => {\n      const { width, height } = this.getState()\n      const newSize = await this.measure()\n      if (newSize.height === height && newSize.width === width) {\n        return\n      }\n      this.updateBehindNodesPosition()\n      this.section.pub(SectionEvents.Resize, {\n        node: this,\n        newSize,\n        originalSize: { width, height },\n      })\n    })\n  }\n\n  /**\n   * 测量节点的尺寸信息\n   */\n  public async measure() {\n    let width: number | undefined\n    let height: number | undefined\n    if (isWeb() && this._measureEl) {\n      const r = this._measureEl.getBoundingClientRect()\n      width = r.width\n      height = r.height\n    } else if (isWeapp && this._measureEl) {\n      const scope = weappScope({ current: this._measureEl as any })\n      const res = await getRectSizeSync(`#${this.id}`, 100, 3, scope)\n      width = res.width\n      height = res.height\n    } else {\n      const res = await getRectSizeSync(`#${this.id}`, 100, 3)\n      width = res.width\n      height = res.height\n    }\n    if (\n      typeof width !== 'number' ||\n      typeof height !== 'number' ||\n      !Number.isFinite(width) ||\n      !Number.isFinite(height) ||\n      width <= 0 ||\n      height <= 0\n    ) {\n      const s = this.getState()\n      return { width: s.width, height: s.height }\n    }\n    this.setStateBatch({\n      width,\n      height,\n      layouted: true,\n    })\n    return { width, height }\n  }\n\n  /**\n   * 更新节点所在列后面的节点的位置\n   */\n  updateBehindNodesPosition() {\n    const currentColumn = this.section.columnMap[this.col]\n    let start = this.order + 1\n\n    if (start > currentColumn.length - 1) {\n      return\n    }\n    for (; start < currentColumn.length; start++) {\n      const node = currentColumn[start]\n      const previousNode = currentColumn[start - 1]\n      const {\n        top: previousNodeTop,\n        height: previousNodeHeight,\n        scrollTop: previousNodeScrollTop,\n      } = previousNode.getState()\n      const rowGap = this.section.rowGap\n      node.setStateBatch({\n        top: previousNodeTop + previousNodeHeight + rowGap,\n        scrollTop: previousNodeScrollTop + previousNodeHeight + rowGap,\n      })\n    }\n  }\n\n  /**\n   * 节点是否可见\n   */\n  get isInRange() {\n    const { scrollBoundaryStart, scrollBoundaryEnd } = this.root\n    const { height: nodeHeight, scrollTop: nodeScrollTop } = this.getState()\n    return (\n      nodeScrollTop < scrollBoundaryEnd &&\n      nodeScrollTop + nodeHeight > scrollBoundaryStart\n    )\n  }\n}\n"],"names":[],"mappings":";;;;;;;AA8Ba,MAAA,UAAU,GAAG;AACxB,IAAA,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;;AAGxB,MAAO,IAAK,SAAQ,gBAA2B,CAAA;AAiBnD,IAAA,WAAA,CAAmB,IAAU,EAAS,OAAgB,EAAE,KAAgB,EAAA;QACtE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,KAAK;AAChD,QAAA,KAAK,CAAC;AACJ,YAAA,GAAG,EAAE,CAAC;AACN,YAAA,KAAK,EAAE,CAAC;YACR,MAAM;AACN,YAAA,SAAS,EAAE,CAAC;AACZ,YAAA,QAAQ,EAAE,KAAK;AAChB,SAAA,CAAC;QARe,IAAI,CAAA,IAAA,GAAJ,IAAI;QAAe,IAAO,CAAA,OAAA,GAAP,OAAO;;QAfrC,IAAU,CAAA,UAAA,GAAuB,IAAI;AAwB3C,QAAA,MAAM,MAAM,GAAG,CAAG,EAAA,IAAI,CAAC,EAAE,CAAI,CAAA,EAAA,OAAO,CAAC,EAAE,CAAS,MAAA,EAAA,UAAU,EAAE;AAC5D,QAAA,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;QAC3D,IAAI,CAAC,kBAAkB,EAAE;;AAG3B,IAAA,oBAAoB,CAAE,EAAsB,EAAA;AAC1C,QAAA,IAAI,CAAC,UAAU,GAAG,EAAE;;IAGd,kBAAkB,GAAA;AACxB,QAAA,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,MAAK;AACxB;;AAEG;YACH,IACE,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,KAAK,CACpC,CAAC,IAAI,KAAK,IAAI,CAAC,QAAQ,EAAE,CAAC,QAAQ,CACnC,EACD;gBACA,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,gBAAgB,CAAC;;AAEvD,SAAC,CAAC;AAEF;;;;;;AAMG;QACH,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,EAAE,YAAW;YACrC,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,QAAQ,EAAE;AACzC,YAAA,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE;AACpC,YAAA,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM,IAAI,OAAO,CAAC,KAAK,KAAK,KAAK,EAAE;gBACxD;;YAEF,IAAI,CAAC,yBAAyB,EAAE;YAChC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,MAAM,EAAE;AACrC,gBAAA,IAAI,EAAE,IAAI;gBACV,OAAO;AACP,gBAAA,YAAY,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE;AAChC,aAAA,CAAC;AACJ,SAAC,CAAC;;AAGJ;;AAEG;AACI,IAAA,MAAM,OAAO,GAAA;AAClB,QAAA,IAAI,KAAyB;AAC7B,QAAA,IAAI,MAA0B;AAC9B,QAAA,IAAI,KAAK,EAAE,IAAI,IAAI,CAAC,UAAU,EAAE;YAC9B,MAAM,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,qBAAqB,EAAE;AACjD,YAAA,KAAK,GAAG,CAAC,CAAC,KAAK;AACf,YAAA,MAAM,GAAG,CAAC,CAAC,MAAM;;AACZ,aAAA,IAAI,OAAO,IAAI,IAAI,CAAC,UAAU,EAAE;AACrC,YAAA,MAAM,KAAK,GAAG,UAAU,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,UAAiB,EAAE,CAAC;AAC7D,YAAA,MAAM,GAAG,GAAG,MAAM,eAAe,CAAC,IAAI,IAAI,CAAC,EAAE,CAAA,CAAE,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,CAAC;AAC/D,YAAA,KAAK,GAAG,GAAG,CAAC,KAAK;AACjB,YAAA,MAAM,GAAG,GAAG,CAAC,MAAM;;aACd;AACL,YAAA,MAAM,GAAG,GAAG,MAAM,eAAe,CAAC,CAAI,CAAA,EAAA,IAAI,CAAC,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;AACxD,YAAA,KAAK,GAAG,GAAG,CAAC,KAAK;AACjB,YAAA,MAAM,GAAG,GAAG,CAAC,MAAM;;QAErB,IACE,OAAO,KAAK,KAAK,QAAQ;YACzB,OAAO,MAAM,KAAK,QAAQ;AAC1B,YAAA,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;AACvB,YAAA,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC;AACxB,YAAA,KAAK,IAAI,CAAC;YACV,MAAM,IAAI,CAAC,EACX;AACA,YAAA,MAAM,CAAC,GAAG,IAAI,CAAC,QAAQ,EAAE;AACzB,YAAA,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;;QAE7C,IAAI,CAAC,aAAa,CAAC;YACjB,KAAK;YACL,MAAM;AACN,YAAA,QAAQ,EAAE,IAAI;AACf,SAAA,CAAC;AACF,QAAA,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE;;AAG1B;;AAEG;IACH,yBAAyB,GAAA;AACvB,QAAA,MAAM,aAAa,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC;AACtD,QAAA,IAAI,KAAK,GAAG,IAAI,CAAC,KAAK,GAAG,CAAC;QAE1B,IAAI,KAAK,GAAG,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE;YACpC;;QAEF,OAAO,KAAK,GAAG,aAAa,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE;AAC5C,YAAA,MAAM,IAAI,GAAG,aAAa,CAAC,KAAK,CAAC;YACjC,MAAM,YAAY,GAAG,aAAa,CAAC,KAAK,GAAG,CAAC,CAAC;AAC7C,YAAA,MAAM,EACJ,GAAG,EAAE,eAAe,EACpB,MAAM,EAAE,kBAAkB,EAC1B,SAAS,EAAE,qBAAqB,GACjC,GAAG,YAAY,CAAC,QAAQ,EAAE;AAC3B,YAAA,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM;YAClC,IAAI,CAAC,aAAa,CAAC;AACjB,gBAAA,GAAG,EAAE,eAAe,GAAG,kBAAkB,GAAG,MAAM;AAClD,gBAAA,SAAS,EAAE,qBAAqB,GAAG,kBAAkB,GAAG,MAAM;AAC/D,aAAA,CAAC;;;AAIN;;AAEG;AACH,IAAA,IAAI,SAAS,GAAA;QACX,MAAM,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,GAAG,IAAI,CAAC,IAAI;AAC5D,QAAA,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,aAAa,EAAE,GAAG,IAAI,CAAC,QAAQ,EAAE;QACxE,QACE,aAAa,GAAG,iBAAiB;AACjC,YAAA,aAAa,GAAG,UAAU,GAAG,mBAAmB;;AAGrD;;;;"}

package/dist/components/water-flow/root.d.ts

@@ -2,7 +2,10 @@ import { Node } from './node';
 import { Section } from './section';
 import { StatefulEventBus } from './stateful-event-bus';
 import type { BaseProps, ScrollDirection, Size, WaterFlowProps } from './interface';
-export type RootProps = Pick<WaterFlowProps, 'cacheCount' | 'lowerThresholdCount' | 'upperThresholdCount'> & Required<Pick<BaseProps, 'id'>>;
+export type RootProps = Pick<WaterFlowProps, 'cacheCount' | 'lowerThresholdCount' | 'upperThresholdCount'> & Required<Pick<BaseProps, 'id'>> & {
+    /** scrollElement 模式下为 true，不测量自有容器；此时需布局全部 section 以展开完整高度 */
+    skipContainerMeasure?: boolean;
+};
 type RootState = {
     /** 是否在滚动中 */
     isScrolling: boolean;
@@ -52,9 +55,17 @@ export declare class Root extends StatefulEventBus<RootState, Events> {
      */
     sections: Section[];
     /**
-     * 设置预加载的 Item 条数。
+     * 设置预加载的 Item 条数（与 props.cacheCount 一致，收敛目标）。
      */
     cacheCount: number;
+    /**
+     * Node 层向上（列索引减小方向）预缓存条数，可与 cacheCount 不同（快速滑动单边放大）。
+     */
+    nodeCacheBackward: number;
+    /**
+     * Node 层向下（列索引增大方向）预缓存条数。
+     */
+    nodeCacheForward: number;
     upperThresholdCount: number;
     lowerThresholdCount: number;
     /**
@@ -65,7 +76,19 @@ export declare class Root extends StatefulEventBus<RootState, Events> {
      * 触发滚动阈值对应的 scrollTop 值
      */
     lowerThresholdScrollTop: number;
+    /** scrollElement 模式下为 true，需布局全部 section 以展开完整高度供父容器滚动 */
+    skipContainerMeasure: boolean;
+    /** 当前是否处于触顶区域；初始为 true（起始在顶部），只有从 false→true 时才触发事件 */
+    private _inUpperZone;
+    /** 当前是否处于触底区域；初始为 false */
+    private _inLowerZone;
+    /** scrollHeight 更新防抖（raf），减轻 pushNodes 后测量前后的高度跳变 */
+    private _scrollHeightRafId;
     constructor(props: RootProps);
+    /**
+     * 挂载后由 WaterFlow 调用：用当前根容器 DOM（与 #id 同节点或 ScrollView 外壳）测量 containerSize。
+     */
+    measureContainerSize(measureEl: HTMLElement | null): Promise<void>;
     /**
      * 设置订阅事件
      */
@@ -94,8 +117,15 @@ export declare class Root extends StatefulEventBus<RootState, Events> {
     /**
      * 处理滚动到阈值的情况
      * 检测当前滚动位置是否达到了上下阈值，并触发相应的事件
+     * scrollElement 模式：scrollOffset 为内容内偏移（scrollTop - startOffset），upper/lowerThresholdScrollTop 基于本组件内容计算，触顶/触底以本 WaterFlow 内容为基准
      */
     private handleReachThreshold;
+    /**
+     * 列表追加并完成 finalize 后调用：重置触底边沿状态（_inLowerZone），
+     * 使用户仍在底部时下一次滚动能再次触发 onScrollToLower，而不必先上滑再下滑。
+     * 不在此处同步调用 handleReachThreshold，避免仍在底部时立刻连发触底（与误触区分）。
+     */
+    resetLowerReachEdgeAfterContentChange(): void;
     /**
      * 容器的滚动上边界
      */
@@ -113,9 +143,10 @@ export declare class Root extends StatefulEventBus<RootState, Events> {
      */
     get sectionRange(): number[][];
     /**
-     * 计算滚动高度
+     * 更新总滚动高度（各 Section 累计）。
+     * @param immediate true 时跳过 raf 防抖（如 finalizePushNodesStateIfNeeded），避免高度滞后引起跳动
      */
-    updateScrollHeight(): void;
+    updateScrollHeight(immediate?: boolean): void;
     /**
      * 注册分组
      */
@@ -132,6 +163,10 @@ export declare class Root extends StatefulEventBus<RootState, Events> {
      * 查找节点
      */
     findNode(id: string): Node;
+    /**
+     * 设置 Node 层上下方向预缓存条数，并刷新可见分组内的列渲染区间。
+     */
+    setNodeCacheRange(backward: number, forward: number): void;
     /**
      * 获取分组渲染区间
      */