tencent.jquery.pix.component 1.0.86 → 1.0.87

package/change.md

@@ -1,5 +1,9 @@
 # 更新日志
 
+### 1.0.87
+
+- waterfallv2 添加下拉刷新功能及相关回调
+
 ### 1.0.86
 
 #### `2026.4.15`

package/components/banner/banner.js

@@ -9,7 +9,7 @@ let $ = null;
  * @constructor
  * @param {object} options 选项
  * @param {string} options.container 容器元素的jquery选择器
- * @param {Array<{url: string, title: string}>} options.list 轮播图列表， url 为图片背景， title 为图片标题
+ * @param {Array<{url: string, title: string, imgObj?: any}>} options.list 轮播图列表， url 为图片背景， title 为图片标题， imgObj 为可选的图片对象引用，若提供则优先作为背景图使用
  * @param {number} [options.index=0] 轮播图初始位置
  * @param {boolean} [options.isTitleEnabled=true] 是否启用标题、翻页栏
  * @param {number} [options.durationMs=0] 轮播图切换时间间隔，单位毫秒，0表示不自动轮播，默认为 0
@@ -28,6 +28,8 @@ export function Banner(options = {}) {
     this.options.durationMs = Number(options.durationMs || 0) || 0;
     this.options.dragThreshold = Number(options.dragThreshold || 0.2) || 0.2;
     this.index = Number(options.index || 0) || 0;
+    // 用于保存 options.list 中每一项对应的 imgObj（按 list 索引存储），避免依赖 jQuery 的 data 功能
+    this.imgObjMap = {};
     if (typeof options.renderCallback === 'function') {
         this.options.isTitleEnabled = false;
     }
@@ -176,6 +178,14 @@ Banner.prototype.createHtml = function () {
     this.currentTranslate = -signWidth * (this.index + 1)
     $inner.width(allWidth).css('transform', `translateX(${this.currentTranslate}px)`)
 
+    // 重置 imgObj 映射表，按 list 的索引保存 imgObj 引用
+    this.imgObjMap = {};
+    for (let i = 0; i < len; i++) {
+        if (this.options.list[i].imgObj) {
+            this.imgObjMap[i] = this.options.list[i].imgObj;
+        }
+    }
+
     // 加第0个位置
     $inner.append(`<div class="banner-inner-li" data-background-url="${this.options.list[len - 1].url}" style="width:${this.signWidth}px;">
             </div>
@@ -421,33 +431,70 @@ Banner.prototype.normalizeTranslate = async function () {
 }
 
 /**
- * 加载所有背景图片，将data-background-url属性设置为背景图片
+ * 应用背景图到指定元素，若存在对应的 imgObj 则优先使用，否则使用 data-background-url
+ * @param {jQuery} $item 目标元素
+ * @param {object} imgObj 可选的图片对象引用
+ */
+function applyBackgroundImage($item, imgObj) {
+    if (imgObj) {
+        // 优先使用 imgObj 作为背景图引用，兼容 Image 实例、{url:''}、以及直接为字符串等形式
+        const src = imgObj.src || imgObj.url || imgObj;
+        $item.css('background-image', `url(${src})`);
+    } else {
+        $item.css('background-image', `url(${$item.attr('data-background-url')})`);
+    }
+}
+
+/**
+ * 根据 inner 中的子元素下标，换算成 options.list 的索引
+ * 由于 inner 首尾各有一个循环占位，所以：
+ *   childIdx === 0          对应 list[len-1]
+ *   childIdx === len+1      对应 list[0]
+ *   其余                     对应 list[childIdx - 1]
+ * @param {number} childIdx inner 的子元素下标
+ * @param {number} len options.list 的长度
+ * @returns {number} options.list 的索引
+ */
+function childIdxToListIdx(childIdx, len) {
+    if (childIdx === 0) return len - 1;
+    if (childIdx === len + 1) return 0;
+    return childIdx - 1;
+}
+
+/**
+ * 加载所有背景图片，优先使用imgObj，否则使用data-background-url属性
  */
 Banner.prototype.loadAllBackgrounds = function () {
-    this.$inner.children().each(function () {
-        $(this).css('background-image', `url(${$(this).attr('data-background-url')})`)
+    const len = this.options.list.length;
+    const imgObjMap = this.imgObjMap || {};
+    this.$inner.children().each(function (childIdx) {
+        const listIdx = childIdxToListIdx(childIdx, len);
+        applyBackgroundImage($(this), imgObjMap[listIdx]);
     });
     // console.log('banner images loaded');
 }
 
 /**
- * 加载背景图片，将data-background-url属性设置为背景图片
+ * 加载背景图片，优先使用imgObj，否则使用data-background-url属性
  * @param {number} pos 为加载的图片编号，取值[0, len)，如果为0或len-1，会同时加载滚动占位的图片
  */
 Banner.prototype.loadBackground = function (pos) {
     console.log('loadBackground pos === ', pos);
+    const imgObjMap = this.imgObjMap || {};
     let $item = this.$inner.children().eq(pos + 1);
-    $item.css('background-image', `url(${$item.attr('data-background-url')})`);
+    applyBackgroundImage($item, imgObjMap[pos]);
 
     // 加载滚动占位的图片
     if (pos === 0) {
         $item = this.$inner.children().eq(this.options.list.length + 1);
-        $item.css('background-image', `url(${$item.attr('data-background-url')})`);
+        // inner 末位占位对应 list[0]
+        applyBackgroundImage($item, imgObjMap[0]);
     }
 
     if (pos === this.options.list.length - 1) {
         $item = this.$inner.children().eq(0);
-        $item.css('background-image', `url(${$item.attr('data-background-url')})`);
+        // inner 首位占位对应 list[len-1]
+        applyBackgroundImage($item, imgObjMap[this.options.list.length - 1]);
     }
 }
 

package/components/waterfallv2/waterfallv2.js

@@ -48,6 +48,8 @@ const DEFAULTS = {
     showLoading: null,  // 展示loading的回调函数 params:$node
     hideLoading: null,  // 隐藏loading的回调函数 
     createLoading: null,  // 创建loading的回调函数
+    createDropDown: null, // 创建下拉时展现出来的元素的回调函数 params:$node
+    dropDownCall: null,   // 当下拉位置超过50%时触发的有效下拉回调函数
 };
 
 export function Waterfallv2(optionsInput = {}) {
@@ -199,6 +201,222 @@ Waterfallv2.prototype.init = function (optionsMain = null) {
         }
     });
 
+    const $child = $container.children();
+    // 给child容器绑定一个下拉事件
+    // 仅当 $scrollDom.scrollTop() === 0 时，才会跟随手指下拉产生 translateY 位移
+    // 松手后以过渡动画自然恢复到 translateY(0)
+    let pullStartY = 0;         // 触摸起始位置
+    let pullCurrentY = 0;       // 当前位移
+    let isPulling = false;      // 是否处于下拉中
+    let pullReachThreshold = false; // 本次下拉是否已达到有效阈值（超过50%）
+    const PULL_DAMPING = 0.7;   // 下拉阻尼系数（手指滑动距离 * 系数 = 实际位移），产生橡皮筋效果
+    const PULL_DEFAULT_HEIGHT = 200; // 下拉元素默认高度（当 $dropDownNode 不存在或高度为 0 时的兜底值）
+    const PULL_RESET_DURATION = 300; // 松手回弹动画时长（ms）
+    // 以下 3 个变量会在每次 touchstart 时基于 $dropDownNode 的实际高度动态计算：
+    let pullMax = PULL_DEFAULT_HEIGHT * 1.5;          // 下拉最大位移（px）
+    let pullThreshold = PULL_DEFAULT_HEIGHT;        // 有效下拉阈值（超过此距离则视为一次有效下拉）
+    let pullHoldOffset = PULL_DEFAULT_HEIGHT;       // 触发有效下拉后，松手悬停保持的位移量（保持下拉元素可见）
+
+    // 下拉保持状态标志（挂在实例上，方便 hideDropDown 等原型方法访问）
+    this.isPullHolding = false;
+
+    // 根据 $dropDownNode 的实际高度动态计算下拉相关的 3 个关键位移值
+    // 每次触摸开始时调用，保证拿到最新高度（适应运行时 $dropDownNode 内容变化）
+    const recalcPullMetrics = function () {
+        let dropH = 0;
+        if (self.$dropDownNode && self.$dropDownNode.length) {
+            dropH = self.$dropDownNode.height() || 0;
+        }
+        if (dropH <= 0) {
+            dropH = PULL_DEFAULT_HEIGHT;
+        }
+        pullThreshold = dropH;          // 下拉超过 dropDown 完整高度即视为有效
+        pullHoldOffset = dropH;         // 保持位置刚好让 dropDown 完全可见
+        pullMax = dropH * 1.5;            // 下拉最大位移为 1.5 倍高度，提供橡皮筋余量
+    };
+
+    const pullDomNode = $child.get(0);
+    console.log('pullDomNode',pullDomNode);
+
+    // 通用的 clientY 提取函数：同时兼容触摸事件和鼠标事件
+    // - 触摸事件：从 e.touches[0] 或 e.originalEvent.touches[0] 读取
+    // - 鼠标事件：直接从 e.clientY 读取
+    const getClientY = function (e) {
+        if (e.touches && e.touches.length) return e.touches[0].clientY;
+        if (e.originalEvent && e.originalEvent.touches && e.originalEvent.touches.length) {
+            return e.originalEvent.touches[0].clientY;
+        }
+        if (typeof e.clientY === 'number') return e.clientY;
+        return null;
+    };
+
+    // 创建下拉时展现出来的元素（类似 loading 节点的机制）
+    // 节点放置在 $child 内部最顶部，通过 top: -Hpx 自身负偏移隐藏在列表可视区之上；
+    // 当 $child 执行 translateY(offset) 向下位移时，该元素会跟随一起下移并自然露出。
+    this.$dropDownNode = null;
+    if (options.createDropDown && options.createDropDown.constructor === Function) {
+        this.$dropDownNode = $(
+            `<div class="waterfallv2-dropdown" style="position:absolute;left:0;right:0;bottom:100%;width:100%;"></div>`
+        );
+        // 插入到 $child 的最前面，使其定位参考 $child（$child 为定位上下文时最佳；
+        // 若 $child 不是定位元素，也可使用 bottom:100% 让其处于 $child 上方）
+        $child.css('position', $child.css('position') === 'static' ? 'relative' : $child.css('position'));
+        $child.prepend(this.$dropDownNode);
+        options.createDropDown(this.$dropDownNode);
+    }
+
+    const onTouchStart = function (e) {
+        // 若处于下拉保持状态（等待开发者手动收回），则忽略新的下拉手势
+        if (self.isPullHolding) {
+            isPulling = false;
+            return;
+        }
+        // 仅当滚动容器已在顶部时才进入下拉模式
+        if ($scrollDom.scrollTop() !== 0) {
+            isPulling = false;
+            return;
+        }
+        const clientY = getClientY(e);
+        if (clientY === null) return;
+        // 在每次下拉开始时动态获取 $dropDownNode 的实际高度，重新计算下拉关键位移值
+        recalcPullMetrics();
+        pullStartY = clientY;
+        pullCurrentY = 0;
+        isPulling = true;
+        // 移除过渡，确保跟手
+        $child.css('transition', 'none');
+    };
+
+    const onTouchMove = function (e) {
+        if (!isPulling) return;
+        const clientY = getClientY(e);
+        if (clientY === null) return;
+
+        const dy = clientY - pullStartY;
+   
+        // 仅响应下拉方向
+        if (dy <= 0) {
+            pullCurrentY = 0;
+            $child.css('transform', 'translateY(0px)');
+            return;
+        }
+
+        // 若在下拉过程中滚动位置不为 0（例如系统反弹），则中断下拉
+        if ($scrollDom.scrollTop() > 0) {
+            return;
+        }
+
+        // 阻尼衰减 + 最大位移限制
+        let offset = dy * PULL_DAMPING;
+    
+        if (offset > pullMax) offset = pullMax;
+        pullCurrentY = offset;
+
+        // 判断是否达到有效下拉阈值（只要过程中曾经超过阈值即视为达到）
+
+        if (offset >= pullThreshold) {
+        
+            pullReachThreshold = true;
+        }
+
+        // 在模拟器下 下拉元素还有个默认下滑，这里相对再减去一点值
+        $child.css('transform', 'translateY(' + offset * 0.8 + 'px)');
+
+        // 处于下拉偏移过程中，阻止原生滚动与橡皮筋效果
+        if (e.cancelable) {
+            if(e.preventDefault) e.preventDefault();
+        }
+    };
+
+    const onTouchEnd = function () {
+        if (!isPulling) return;
+        isPulling = false;
+
+        // 本次是否达到有效阈值
+        const reached = pullReachThreshold;
+        pullReachThreshold = false;
+
+        if (reached) {
+            // === 有效下拉：悬停保持，等待开发者手动调用 hideDropDown() 收回 ===
+            // 悬停保持位移：使用 touchstart 时动态计算出的 pullHoldOffset（基于 $dropDownNode 实际高度）
+            const holdOffset = pullHoldOffset;
+
+            // 标记进入保持状态
+            self.isPullHolding = true;
+
+            // 以过渡动画平滑过渡到保持位置
+            $child.css('transition', 'transform ' + PULL_RESET_DURATION + 'ms ease-out');
+            $child.css('transform', 'translateY(' + holdOffset + 'px)');
+
+            // 动画结束后清理 transition
+            setTimeout(function () {
+                $child.css('transition', '');
+                pullCurrentY = holdOffset;
+            }, PULL_RESET_DURATION);
+
+            // 触发 dropDownCall 回调（在进入保持状态后回调，便于开发者在回调内部发起请求，
+            // 完成后调用 self.hideDropDown() 收回下拉）
+            if (options.dropDownCall && options.dropDownCall.constructor === Function) {
+                try {
+                    options.dropDownCall(self.$dropDownNode);
+                } catch (err) {
+                    console.error('Waterfallv2: dropDownCall error', err);
+                }
+            }
+            return;
+        }
+
+        // === 未达到阈值：按原逻辑自然回弹到 0 ===
+        $child.css('transition', 'transform ' + PULL_RESET_DURATION + 'ms ease-out');
+        $child.css('transform', 'translateY(0px)');
+
+        // 动画结束后清理 transition，避免影响后续其他 transform 修改
+        setTimeout(function () {
+            $child.css('transition', '');
+            pullCurrentY = 0;
+        }, PULL_RESET_DURATION);
+    };
+
+    // 桌面端鼠标事件支持：按照触摸事件的同样规律实现鼠标拖拽下拉
+    // mousedown / mousemove / mouseup 均绑定在 pullDomNode 上
+    // 由于鼠标可能拖出 pullDomNode 边界，额外绑定 mouseleave 作为兼底中断（视同松手）
+    const onMouseMove = function (e) {
+        onTouchMove(e);
+    };
+    const onMouseUp = function (e) {
+        onTouchEnd(e);
+    };
+    const onMouseLeave = function (e) {
+        // 拖拽过程中移出 pullDomNode 时视为松手，触发回弹或保持逻辑
+        if (isPulling) {
+            onTouchEnd(e);
+        }
+    };
+    const onMouseDown = function (e) {
+        onTouchStart(e);
+    };
+    // 小应用环境只支持mousedown的鼠标点击类型事件,不支持touch事件
+    if (pullDomNode) {
+        pullDomNode.addEventListener('mousedown', onMouseDown);
+        pullDomNode.addEventListener('mousemove', onMouseMove);
+        pullDomNode.addEventListener('mouseup', onMouseUp);
+        pullDomNode.addEventListener('mouseleave', onMouseLeave);
+    }
+
+    // 保存引用，便于 destroy 时解绑；同时供 hideDropDown 原型方法使用
+    this._pullHandlers = {
+        $child: $child,
+        node: pullDomNode,
+        onTouchStart: onTouchStart,
+        onTouchMove: onTouchMove,
+        onTouchEnd: onTouchEnd,
+        onMouseDown: onMouseDown,
+        onMouseMove: onMouseMove,
+        onMouseUp: onMouseUp,
+        onMouseLeave: onMouseLeave,
+        resetDuration: PULL_RESET_DURATION,
+    };
+
     this.scrollTop = $scrollDom.scrollTop();  // 当前滚动位置
 
     // 首次渲染
@@ -1372,10 +1590,69 @@ Waterfallv2.prototype.setScrollHeight = function () {
     $container.find('.waterfallv2-list-scroll').css('height', h + 'px');
 }
 
+/**
+ * 手动收回下拉元素（供开发者调用）
+ * 使用场景：触发 dropDownCall 后，$child 悬停保持在可见位置，开发者在异步操作（如刷新数据）完成后，
+ *           调用此方法把下拉元素自然退回到初始位置。
+ * @param {Function} [callback] - 回弹动画完成后的回调（可选）
+ */
+Waterfallv2.prototype.hideDropDown = function (callback) {
+    // 未处于保持状态时，直接回调并返回（空操作）
+    if (!this.isPullHolding) {
+        if (callback && callback.constructor === Function) callback();
+        return;
+    }
+
+    const handlers = this._pullHandlers;
+    if (!handlers || !handlers.$child || !handlers.$child.length) {
+        this.isPullHolding = false;
+        if (callback && callback.constructor === Function) callback();
+        return;
+    }
+
+    const $child = handlers.$child;
+    const duration = handlers.resetDuration || 300;
+
+    // 以过渡动画自然回到 0
+    $child.css('transition', 'transform ' + duration + 'ms ease-out');
+    $child.css('transform', 'translateY(0px)');
+
+    const self = this;
+    setTimeout(function () {
+        $child.css('transition', '');
+        self.isPullHolding = false;
+        if (callback && callback.constructor === Function) callback();
+    }, duration);
+};
+
 // 销毁自己
 Waterfallv2.prototype.destroy = function () {
     const options = this.options;
     const $container = $(options.container);
+
+    // 解绑下拉事件监听器
+    if (this._pullHandlers && this._pullHandlers.node) {
+        const h = this._pullHandlers;
+        h.node.removeEventListener('touchstart', h.onTouchStart);
+        h.node.removeEventListener('touchmove', h.onTouchMove);
+        h.node.removeEventListener('touchend', h.onTouchEnd);
+        h.node.removeEventListener('touchcancel', h.onTouchEnd);
+        // 解绑鼠标事件（均绑在 pullDomNode 上）
+        if (h.onMouseDown) {
+            h.node.removeEventListener('mousedown', h.onMouseDown);
+        }
+        if (h.onMouseMove) {
+            h.node.removeEventListener('mousemove', h.onMouseMove);
+        }
+        if (h.onMouseUp) {
+            h.node.removeEventListener('mouseup', h.onMouseUp);
+        }
+        if (h.onMouseLeave) {
+            h.node.removeEventListener('mouseleave', h.onMouseLeave);
+        }
+        this._pullHandlers = null;
+    }
+
     $container.html('');
     this.activeNodes.clear();
     this.allReadyNodes.clear();
@@ -1388,7 +1665,9 @@ Waterfallv2.prototype.destroy = function () {
     this.renderIndex = 0;
     this.scrollTop = 0;
     this.isShowLoading = false;
+    this.isPullHolding = false;
     this.$loadingNode = null;
+    this.$dropDownNode = null;
     this.$scrollDom = null;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tencent.jquery.pix.component",
-  "version": "1.0.86",
+  "version": "1.0.87",
   "description": "",
   "main": "index.js",
   "files": [