@tarojs/components-advanced 4.1.12-beta.2 → 4.1.12-beta.21

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

@@ -0,0 +1,84 @@
+import { useState, useRef, useEffect } from 'react';
+
+const WARNED_NESTED = new WeakSet();
+const MAX_RETRY = 20;
+const RETRY_DELAY = 50;
+/**
+ * 测量 scrollElement 内 content 节点之前所有兄弟的高度/宽度之和，作为 startOffset。
+ * 用于 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) {
+            retryCountRef.current = 0;
+            return;
+        }
+        const scrollEl = scrollElRef.current;
+        const contentEl = contentRef.current;
+        // 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;
+            const scroll = scrollElRef.current;
+            if (!el || !scroll)
+                return;
+            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 以获得更稳定的布局。');
+            }
+        };
+        measure();
+        scrollEl.addEventListener('scroll', measure, { passive: true });
+        const ro = typeof ResizeObserver !== 'undefined' ? new ResizeObserver(measure) : null;
+        if (ro) {
+            ro.observe(scrollEl);
+            Array.from(scrollEl.children).forEach((child) => ro.observe(child));
+            // 非直接子节点：content 自身或其祖先变化时也需重测
+            ro.observe(contentEl);
+        }
+        return () => {
+            scrollEl.removeEventListener('scroll', measure);
+            ro === null || ro === void 0 ? void 0 : ro.disconnect();
+        };
+    }, [enabled, scrollElRef, contentRef, isHorizontal, retryTrigger]);
+    return measuredStartOffset;
+}
+
+export { useMeasureStartOffset };
+//# sourceMappingURL=useMeasureStartOffset.js.map

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

@@ -0,0 +1 @@
+{"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/useMeasureStartOffsetWeapp.d.ts

@@ -0,0 +1,13 @@
+import type { MutableRefObject, RefObject } from 'react';
+/**
+ * 小程序版 startOffset 测量：通过 createSelectorQuery 获取 scroll-view 与 content 的位置，
+ * 计算 content 相对于 scroll 内容顶部的偏移。
+ *
+ * 公式：startOffset = contentRect.top - scrollRect.top + scrollTop
+ * （content 在屏幕上的 top - scroll 可视区 top + 已滚动距离）
+ */
+export declare function useMeasureStartOffsetWeapp(scrollElRef: RefObject<HTMLElement | null>, contentId: string, options: {
+    enabled: boolean;
+    isHorizontal?: boolean;
+    startOffsetRef?: MutableRefObject<number>;
+}): number;

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

@@ -0,0 +1,85 @@
+import Taro from '@tarojs/taro';
+import { useState, useRef, useEffect } from 'react';
+
+const MAX_RETRY = 20;
+const RETRY_DELAY = 50;
+/** 与 useListScrollElementAttachWeapp 容器测量间隔一致（H5 无 interval，用 ResizeObserver+scroll 事件驱动） */
+const MEASURE_INTERVAL = 150;
+/**
+ * 小程序版 startOffset 测量：通过 createSelectorQuery 获取 scroll-view 与 content 的位置，
+ * 计算 content 相对于 scroll 内容顶部的偏移。
+ *
+ * 公式：startOffset = contentRect.top - scrollRect.top + scrollTop
+ * （content 在屏幕上的 top - scroll 可视区 top + 已滚动距离）
+ */
+function useMeasureStartOffsetWeapp(scrollElRef, contentId, options) {
+    const { enabled, isHorizontal = false, startOffsetRef } = options;
+    const [measuredStartOffset, setMeasuredStartOffset] = useState(0);
+    const [retryTrigger, setRetryTrigger] = useState(0);
+    const retryCountRef = useRef(0);
+    const autoIdRef = useRef(`_ls_so_${Math.random().toString(36).slice(2, 9)}`);
+    useEffect(() => {
+        if (!enabled || !contentId) {
+            retryCountRef.current = 0;
+            return;
+        }
+        const measure = () => {
+            const scrollEl = scrollElRef.current;
+            if (!scrollEl)
+                return;
+            if (!scrollEl.id) {
+                scrollEl.id = autoIdRef.current;
+            }
+            const scrollViewId = scrollEl.id;
+            const instance = Taro.getCurrentInstance();
+            const query = (instance === null || instance === void 0 ? void 0 : instance.page)
+                ? Taro.createSelectorQuery().in(instance.page)
+                : Taro.createSelectorQuery();
+            query
+                .select(`#${scrollViewId}`)
+                .boundingClientRect()
+                .select(`#${scrollViewId}`)
+                .scrollOffset()
+                .select(`#${contentId}`)
+                .boundingClientRect()
+                .exec((res) => {
+                var _a, _b;
+                const scrollRect = res === null || res === void 0 ? void 0 : res[0];
+                const scrollInfo = res === null || res === void 0 ? void 0 : res[1];
+                const contentRect = res === null || res === void 0 ? void 0 : res[2];
+                if (!scrollRect || !scrollInfo || !contentRect)
+                    return;
+                const scrollTop = (_a = scrollInfo.scrollTop) !== null && _a !== void 0 ? _a : 0;
+                const scrollLeft = (_b = scrollInfo.scrollLeft) !== null && _b !== void 0 ? _b : 0;
+                const value = isHorizontal
+                    ? Math.max(0, contentRect.left - scrollRect.left + scrollLeft)
+                    : Math.max(0, contentRect.top - scrollRect.top + scrollTop);
+                startOffsetRef && (startOffsetRef.current = value);
+                setMeasuredStartOffset((prevVal) => (Math.abs(prevVal - value) < 1 ? prevVal : value));
+            });
+        };
+        const scrollEl = scrollElRef.current;
+        if (!scrollEl) {
+            if (retryCountRef.current < MAX_RETRY) {
+                retryCountRef.current += 1;
+                const id = setTimeout(() => setRetryTrigger((t) => t + 1), RETRY_DELAY);
+                return () => clearTimeout(id);
+            }
+            return;
+        }
+        retryCountRef.current = 0;
+        measure();
+        // 对标 H5：scroll 时触发测量（H5 用 scrollEl.addEventListener('scroll', measure)）
+        scrollEl.addEventListener('scroll', measure);
+        // 无 ResizeObserver，用 interval 兜底布局变化
+        const interval = setInterval(measure, MEASURE_INTERVAL);
+        return () => {
+            scrollEl.removeEventListener('scroll', measure);
+            clearInterval(interval);
+        };
+    }, [enabled, scrollElRef, contentId, isHorizontal, retryTrigger]);
+    return measuredStartOffset;
+}
+
+export { useMeasureStartOffsetWeapp };
+//# sourceMappingURL=useMeasureStartOffsetWeapp.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useMeasureStartOffsetWeapp.js","sources":["../../../../src/components/list/hooks/useMeasureStartOffsetWeapp.ts"],"sourcesContent":["import Taro from '@tarojs/taro'\nimport { useEffect, useRef, useState } from 'react'\n\nimport type { MutableRefObject, RefObject } from 'react'\n\nconst MAX_RETRY = 20\nconst RETRY_DELAY = 50\n/** 与 useListScrollElementAttachWeapp 容器测量间隔一致（H5 无 interval，用 ResizeObserver+scroll 事件驱动） */\nconst MEASURE_INTERVAL = 150\n\n/**\n * 小程序版 startOffset 测量：通过 createSelectorQuery 获取 scroll-view 与 content 的位置，\n * 计算 content 相对于 scroll 内容顶部的偏移。\n *\n * 公式：startOffset = contentRect.top - scrollRect.top + scrollTop\n * （content 在屏幕上的 top - scroll 可视区 top + 已滚动距离）\n */\nexport function useMeasureStartOffsetWeapp(\n  scrollElRef: RefObject<HTMLElement | null>,\n  contentId: string,\n  options: { enabled: boolean, isHorizontal?: boolean, startOffsetRef?: MutableRefObject<number> }\n): number {\n  const { enabled, isHorizontal = false, startOffsetRef } = options\n  const [measuredStartOffset, setMeasuredStartOffset] = useState(0)\n  const [retryTrigger, setRetryTrigger] = useState(0)\n  const retryCountRef = useRef(0)\n  const autoIdRef = useRef(`_ls_so_${Math.random().toString(36).slice(2, 9)}`)\n\n  useEffect(() => {\n    if (!enabled || !contentId) {\n      retryCountRef.current = 0\n      return\n    }\n\n    const measure = () => {\n      const scrollEl = scrollElRef.current as any\n      if (!scrollEl) return\n\n      if (!scrollEl.id) {\n        scrollEl.id = autoIdRef.current\n      }\n      const scrollViewId = scrollEl.id\n\n      const instance = Taro.getCurrentInstance()\n      const query = instance?.page\n        ? Taro.createSelectorQuery().in(instance.page as any)\n        : Taro.createSelectorQuery()\n      query\n        .select(`#${scrollViewId}`)\n        .boundingClientRect()\n        .select(`#${scrollViewId}`)\n        .scrollOffset()\n        .select(`#${contentId}`)\n        .boundingClientRect()\n        .exec((res) => {\n          const scrollRect = res?.[0]\n          const scrollInfo = res?.[1]\n          const contentRect = res?.[2]\n          if (!scrollRect || !scrollInfo || !contentRect) return\n\n          const scrollTop = scrollInfo.scrollTop ?? 0\n          const scrollLeft = scrollInfo.scrollLeft ?? 0\n          const value = isHorizontal\n            ? Math.max(0, contentRect.left - scrollRect.left + scrollLeft)\n            : Math.max(0, contentRect.top - scrollRect.top + scrollTop)\n          startOffsetRef && (startOffsetRef.current = value)\n          setMeasuredStartOffset((prevVal) => (Math.abs(prevVal - value) < 1 ? prevVal : value))\n        })\n    }\n\n    const scrollEl = scrollElRef.current\n    if (!scrollEl) {\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    measure()\n    // 对标 H5：scroll 时触发测量（H5 用 scrollEl.addEventListener('scroll', measure)）\n    scrollEl.addEventListener('scroll', measure)\n    // 无 ResizeObserver，用 interval 兜底布局变化\n    const interval = setInterval(measure, MEASURE_INTERVAL)\n    return () => {\n      scrollEl.removeEventListener('scroll', measure)\n      clearInterval(interval)\n    }\n  }, [enabled, scrollElRef, contentId, isHorizontal, retryTrigger])\n\n  return measuredStartOffset\n}\n"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,74 @@
+import React from 'react';
+/**
+ * List 组件内部的 refresher 配置类型（独立于 Refresher 组件）
+ * 与 ScrollView refresher 相关属性语义对齐
+ */
+export interface ListRefresherConfig {
+    refresherEnabled?: boolean;
+    refresherThreshold?: number;
+    refresherDefaultStyle?: 'black' | 'white' | 'none';
+    refresherBackground?: string;
+    refresherTriggered?: boolean;
+    /** 自定义刷新内容（来自 Refresher 子组件的 children） */
+    children?: React.ReactNode;
+    onRefresherPulling?: (e?: {
+        detail?: {
+            deltaY?: number;
+        };
+    }) => void;
+    onRefresherRefresh?: () => void | Promise<void>;
+    onRefresherRestore?: () => void;
+    onRefresherAbort?: () => void;
+    onRefresherWillRefresh?: () => void;
+    onRefresherStatusChange?: (e?: {
+        detail?: {
+            status?: number;
+            dy?: number;
+        };
+    }) => void;
+}
+/** 默认刷新层高度（对齐 Dynamic），无自定义 children 时使用 */
+export declare const DEFAULT_REFRESHER_HEIGHT = 50;
+/** 下拉刷新状态枚举（对齐微信小程序 RefreshStatus） */
+export declare const enum RefreshStatus {
+    /** 空闲 */
+    Idle = 0,
+    /** 超过下拉刷新阈值 */
+    CanRefresh = 1,
+    /** 刷新中 */
+    Refreshing = 2,
+    /** 刷新完成 */
+    Completed = 3,
+    /** 刷新失败 */
+    Failed = 4
+}
+interface UseRefresherReturn {
+    scrollViewRefresherProps: {
+        refresherEnabled?: boolean;
+        refresherThreshold?: number;
+        refresherDefaultStyle?: string;
+        refresherBackground?: string;
+        refresherTriggered?: boolean;
+    };
+    scrollViewRefresherHandlers: {
+        onRefresherPulling?: (e: any) => void;
+        onRefresherRefresh?: (e: any) => void;
+        onRefresherRestore?: () => void;
+        onRefresherAbort?: () => void;
+    };
+    h5RefresherProps: {
+        touchHandlers: Record<string, unknown>;
+        pullDistance: number;
+        isRefreshing: boolean;
+        /** H5 单结构下恒为 true，仅兼容旧类型 */
+        showRefresherLayer: boolean;
+    };
+    addImperativeTouchListeners?: (el: HTMLElement) => () => void;
+    renderRefresherContent: () => React.ReactNode | null;
+}
+export declare function useRefresher(config: ListRefresherConfig | null, 
+/** 列表逻辑顶部对应的 scrollTop，用于触顶判断；H5「顶栏悬浮+只滚列表」时传 0，imperative 内以 DOM scrollTop 为准 */
+scrollTopAtLogicalTop: number, 
+/** scrollElement 模式下可选：下拉起始点须在 List 内才触发刷新；未传时默认 true（沿用原逻辑） */
+getIsTouchInListArea?: (ev: TouchEvent) => boolean): UseRefresherReturn;
+export {};