@pixui-dev/pixui-react-virtualwaterfall - npm Package Compare versions

Comparing version 1.0.12 to 1.0.13

package.json

 {
   "name": "@pixui-dev/pixui-react-virtualwaterfall",
-  "version": "1.0.12",
+  "version": "1.0.13",
   "description": "pixui 高性能React虚拟瀑布流组件",
@@ -5,0 +5,0 @@ "publishConfig": {

README.md

 # VirtualWaterfallList 虚拟瀑布流组件
 
+## 组件功能
+
 PixUI 里基于 react 实现的高性能虚拟化瀑布流列表组件。支持 `虚拟滚动、元素复用、无限加载、下拉刷新、曝光回调` 等能力。
@@ -8,4 +10,7 @@ 以最小化节点变更为实现目的，可通过元素复用结合 Ref 更新，达到近乎无更新消耗的效果。
 
+![gif](./images/virtualwaterfall.gif)
+
 ## 安装
 
+
 ```bash
@@ -156,2 +161,4 @@ yarn add @pixui-dev/pixui-react-virtualwaterfall
 
+
+
 ### 1. 最简单案例，默认增删
@@ -1014,2 +1021,5 @@
 
+### 1.0.13
+1. 更新 下拉刷新 逻辑，添加额外的状态，支持下拉刷新悬停。
+
 ### 1.0.12
@@ -1016,0 +1026,0 @@ 1. 修复 removeItemByIndex 最后一个元素的报错，以及高度更新问题。

src/VirtualWaterfall.d.ts

@@ -164,4 +164,11 @@ import { h, Component, JSX } from 'preact';
     /**
+     * 达到下拉刷新阈值回调（准备刷新状态）
+     * @optional
+     * @description 当下拉距离达到阈值时触发，此时应显示"松手刷新"提示
+     */
+    onPullDownReady?: () => void;
+    /**
      * 下拉刷新回调
      * @optional
+     * @description 当用户松手且达到刷新阈值时触发，应在此执行实际的刷新逻辑
      */
@@ -277,2 +284,27 @@ onPullDownRefresh?: () => void;
     };
+    /** =================== 常量配置 =================== */
+    /**
+     * 滚动速度阈值（px/ms），超过此值被认为是快速滚动
+     * @private
+     * @constant
+     */
+    private readonly SCROLL_VELOCITY_THRESHOLD;
+    /**
+     * 平稳滚动时间阈值（ms），超过此时间解除异常标记
+     * @private
+     * @constant
+     */
+    private readonly SMOOTH_SCROLL_TIME_THRESHOLD;
+    /**
+     * 滚动事件节流时间（ms）
+     * @private
+     * @constant
+     */
+    private readonly SCROLL_THROTTLE_TIME;
+    /**
+     * 缓存池最大容量
+     * @private
+     * @constant
+     */
+    private readonly MAX_CACHE_SIZE;
     /** =================== DOM 引用 =================== */
@@ -380,13 +412,68 @@ /**
     /**
-     * 下拉刷新距离
+     * 下拉刷新的最小距离阈值
      * @private
      * @type {number}
      */
-    private pullDownRefreshDistance;
+    private pullDownRefreshThreshold;
     /**
-     * 下拉刷新的最小距离阈值
+     * 用户是否正在触摸/按下
      * @private
+     * @type {boolean}
+     */
+    private isUserPressed;
+    /**
+     * 上次下拉区域的scrollTop值（用于检测下拉方向）
+     * @private
      * @type {number}
      */
-    private pullDownRefreshThreshold;
+    private lastPullDownScrollTop;
+    /**
+     * 进入下拉区域的时间戳（用于检测异常快速触发）
+     * @private
+     * @type {number}
+     */
+    private pullDownStartTime;
+    /** =================== 滚动检测相关 =================== */
+    /**
+     * 上一次滚动位置
+     * @private
+     * @type {number}
+     */
+    private lastScrollTop;
+    /**
+     * 上一次滚动时间戳
+     * @private
+     * @type {number}
+     */
+    private lastScrollTime;
+    /**
+     * 滚动处理定时器ID（用于节流）
+     * @private
+     * @type {number | null}
+     */
+    private scrollThrottleTimer;
+    /**
+     * 上一次处理滚动的时间戳（用于节流）
+     * @private
+     * @type {number}
+     */
+    private lastScrollHandleTime;
+    /**
+     * 数据更新定时器ID（用于 componentWillUpdate）
+     * @private
+     * @type {number | null}
+     */
+    private dataUpdateTimer;
+    /**
+     * 是否正在处理可视区域计算
+     * @private
+     * @type {boolean}
+     */
+    private isCalculatingVisible;
+    /**
+     * 待处理的滚动位置（用于快速滚动时的延迟处理）
+     * @private
+     * @type {number | null}
+     */
+    private pendingScrollTop;
     /** =================== 加载更多相关 =================== */
@@ -425,3 +512,3 @@ /**
      * 组件卸载前的回调
-     * @description 清理缓存
+     * @description 清理缓存和定时器
      */
@@ -515,14 +602,34 @@ componentWillUnmount(): void;
     /**
+     * 鼠标按下事件处理
+     * @private
+     * @description 记录用户按下状态
+     */
+    private handleMouseDown;
+    /**
+     * 鼠标抬起事件处理
+     * @private
+     * @description 处理用户松手，触发下拉刷新
+     */
+    private handleMouseUp;
+    /**
      * 滚动事件处理函数
      * @private
-     * @description 处理滚动事件，更新可视区域和触发加载更多
+     * @description 处理滚动事件，更新可视区域和触发加载更多，带节流优化
      */
     private handleScroll;
     /**
-     * 检查下拉刷新状态
+     * 处理滚动逻辑（节流后执行）
+     * @private
      * @param {number} scrollTop - 当前滚动位置
-     * @description 检查下拉刷新状态，并触发下拉刷新
      */
-    checkAndTriggerPullDownRefresh(scrollTop: number): void;
+    private processScroll;
     /**
+     * 处理下拉刷新逻辑
+     * @private
+     * @param {number} scrollTop - 当前滚动位置
+     * @param {number} currentTime - 当前时间戳
+     * @description 统一处理下拉刷新的状态转换和回调触发
+     */
+    private handlePullDownRefresh;
+    /**
      * 检查并触发加载更多数据
@@ -542,2 +649,8 @@ * @private
     /**
+     * 重置滚动拦截状态
+     * @private
+     * @description 重置滚动检测等状态
+     */
+    private resetScrollInterceptState;
+    /**
      * 获取项目类型（用于分类缓存）
@@ -667,7 +780,2 @@ * @private
     /**
-     * 重置下拉刷新状态
-     * @private
-     */
-    private resetPullDownRefresh;
-    /**
      * 完成下拉刷新（外部调用）
@@ -674,0 +782,0 @@ * @public

No alert changes

Improved metrics

Total package byte prevSize

131013

15.35%

Lines of code

2261

22.41%

Number of lines in readme file

1050

0.96%

No dependency changes