tencent.jquery.pix.component 1.0.63 → 1.0.64

package/components/banner/banner.js

@@ -1,7 +1,9 @@
 import "./banner.scss"
-import { $, windowEnv } from "../config";
+import { windowEnv, getEnv } from "../config";
 import { addResizeFunc, nextAnimationFrame, removeResizeFunc } from "../utils/utils";
 
+let $ = null;
+
 /**
  * 在页面上放置一个banner组件
  * @constructor
@@ -17,7 +19,9 @@ import { addResizeFunc, nextAnimationFrame, removeResizeFunc } from "../utils/ut
  * @param {function} [options.pageChanged] 翻页时触发，第一个参数为新生效页面元素的jq，第二个参数为 options.list 中对应的项，第三个参数为当前页码
  * @param {function} [options.renderCallback] 自定义渲染回调，第一个参数为 options.list 中对应的项，第二个参数为当前页码，返回值为渲染后的元素
  */
-export function Banner(options = {}){
+export function Banner(options = {}) {
+    $ = getEnv().$;
+
     this.options = options;
     this.options.isTitleEnabled ??= true;
     this.options.autoResize ??= true;
@@ -30,7 +34,7 @@ export function Banner(options = {}){
     this.init();
 }
 
-Banner.prototype.setWidth = function(width) {
+Banner.prototype.setWidth = function (width) {
     this.signWidth = width;
     this.allWidth = this.signWidth * (this.options.list.length + 2);
     $(this.options.container).width(width);
@@ -39,7 +43,7 @@ Banner.prototype.setWidth = function(width) {
     this.setTranslate(-this.signWidth * (this.index + 1));
 }
 
-Banner.prototype.fitWidth = function() {
+Banner.prototype.fitWidth = function () {
     console.log('banner fitWidth');
     const newWidth = $(this.options.container).parent().width();
     if (newWidth != this.signWidth) {
@@ -50,7 +54,7 @@ Banner.prototype.fitWidth = function() {
 /**
  * 跳转到上一页
  */
-Banner.prototype.prevPage = async function() {
+Banner.prototype.prevPage = async function () {
     this.pauseAutoPlay();
     await this.gotoPageUnchecked(this.index - 1);
     this.startAutoPlay();
@@ -59,7 +63,7 @@ Banner.prototype.prevPage = async function() {
 /**
  * 跳转到下一页
  */
-Banner.prototype.nextPage = async function() {
+Banner.prototype.nextPage = async function () {
     this.pauseAutoPlay();
     await this.gotoPageUnchecked(this.index + 1);
     this.startAutoPlay();
@@ -69,7 +73,7 @@ Banner.prototype.nextPage = async function() {
  * 跳转到指定页
  * @param {number} newIdx 要切换到的页码 [0, len)
  */
-Banner.prototype.gotoPage = async function(newIdx) {
+Banner.prototype.gotoPage = async function (newIdx) {
     if (newIdx < 0 || newIdx >= this.options.list.length) {
         throw new Error('index out of range');
     }
@@ -81,7 +85,7 @@ Banner.prototype.gotoPage = async function(newIdx) {
     this.startAutoPlay();
 }
 
-Banner.prototype.gotoPageUnchecked = async function(newIdx) {
+Banner.prototype.gotoPageUnchecked = async function (newIdx) {
     const len = this.options.list.length;
     let wrap = 0;
     if (newIdx <= -1) {
@@ -100,14 +104,14 @@ Banner.prototype.gotoPageUnchecked = async function(newIdx) {
     }
 
     this.$inner.css('transition', 'transform 0.3s ease-out');
-    const newTranslate = -this.signWidth * (newIdx+1);
+    const newTranslate = -this.signWidth * (newIdx + 1);
     this.setTranslate(newTranslate);
     if (this.options.isTitleEnabled) {
-        this.$pagination.children().eq(newIdx+1).addClass('active').siblings().removeClass('active');
+        this.$pagination.children().eq(newIdx + 1).addClass('active').siblings().removeClass('active');
         this.$titleBox.text(this.options.list[newIdx].title);
     }
     if (this.options.pageChanged && newIdx != this.index) {
-        this.options.pageChanged(this.$inner.children().eq(newIdx+1), this.options.list[newIdx], newIdx);
+        this.options.pageChanged(this.$inner.children().eq(newIdx + 1), this.options.list[newIdx], newIdx);
     }
     this.index = newIdx;
 }
@@ -116,11 +120,11 @@ Banner.prototype.gotoPageUnchecked = async function(newIdx) {
  * 获取当前页的序号
  * @returns {number} 当前页的序号 [0,len]
  */
-Banner.prototype.getCurrentPage = function() {
+Banner.prototype.getCurrentPage = function () {
     return this.index;
 }
 
-Banner.prototype.init = function(){
+Banner.prototype.init = function () {
     const $t = $(this.options.container)
     console.log('banner container:', $t.dom);
     const signWidth = $t.width()
@@ -139,10 +143,10 @@ Banner.prototype.init = function(){
         });
     }
     this.startAutoPlay();
-    console.log('list:', this.options.list, ' signWidth:',signWidth)
+    console.log('list:', this.options.list, ' signWidth:', signWidth)
 }
 
-Banner.prototype.startAutoPlay = function() {
+Banner.prototype.startAutoPlay = function () {
     if (this.options.durationMs > 0 && this.timer == null) {
         this.timer = setInterval(() => {
             this.nextPage()
@@ -150,7 +154,7 @@ Banner.prototype.startAutoPlay = function() {
     }
 }
 
-Banner.prototype.pauseAutoPlay = function() {
+Banner.prototype.pauseAutoPlay = function () {
     if (this.timer == null) {
         return;
     }
@@ -158,25 +162,25 @@ Banner.prototype.pauseAutoPlay = function() {
     this.timer = null;
 }
 
-Banner.prototype.createHtml = function(){
+Banner.prototype.createHtml = function () {
     const len = this.options.list.length
-    if(len<1){
+    if (len < 1) {
         return
     }
     const $t = $(this.options.container)
     $t.empty();
     const signWidth = this.signWidth = $t.width()
-    
+
     const allWidth = this.allWidth = signWidth * (len + 2)
     const $inner = this.$inner = $(`<div class="banner-inner-transform"></div>`)
     this.currentTranslate = -signWidth * (this.index + 1)
-    $inner.width(allWidth).css('transform',`translateX(${this.currentTranslate}px)`)
+    $inner.width(allWidth).css('transform', `translateX(${this.currentTranslate}px)`)
 
     // 加第0个位置
-    $inner.append(`<div class="banner-inner-li" data-background-url="${this.options.list[len-1].url}" style="width:${this.signWidth}px;">
+    $inner.append(`<div class="banner-inner-li" data-background-url="${this.options.list[len - 1].url}" style="width:${this.signWidth}px;">
             </div>
         `)
-    for(let i=0;i<len;i++){
+    for (let i = 0; i < len; i++) {
         const item = this.options.list[i]
         const $li = $(`<div class="banner-inner-li" data-background-url="${item.url}" style="width:${this.signWidth}px;">
             </div>
@@ -210,7 +214,7 @@ Banner.prototype.createHtml = function(){
         this.$titleBox = $titleBox
         this.$pagination = $pagination
 
-        $pagination.children().eq(this.index+1).addClass('active').siblings().removeClass('active')
+        $pagination.children().eq(this.index + 1).addClass('active').siblings().removeClass('active')
 
         $t.append($pagination)
     }
@@ -223,21 +227,21 @@ Banner.prototype.createHtml = function(){
 /**
  * 由 this.options.renderCallback 生成页面
  */
-Banner.prototype.createCustomHtml = function() {
+Banner.prototype.createCustomHtml = function () {
     const len = this.options.list.length
-    if(len<1){
+    if (len < 1) {
         return
     }
     const $t = $(this.options.container)
     $t.empty();
     const signWidth = this.signWidth = $t.width()
-    
+
     const allWidth = this.allWidth = signWidth * (len + 2)
     const $inner = this.$inner = $(`<div class="banner-inner-transform"></div>`)
     this.currentTranslate = -signWidth * (this.index + 1)
-    $inner.width(allWidth).css('transform',`translateX(${this.currentTranslate}px)`)
+    $inner.width(allWidth).css('transform', `translateX(${this.currentTranslate}px)`)
 
-    let $li = $(this.options.renderCallback(this.options.list[len-1], len-1));
+    let $li = $(this.options.renderCallback(this.options.list[len - 1], len - 1));
     $li.width(signWidth);
     $inner.append($li);
 
@@ -254,7 +258,7 @@ Banner.prototype.createCustomHtml = function() {
     $t.append($inner);
 }
 
-Banner.prototype.bindEvent = function(){
+Banner.prototype.bindEvent = function () {
     const self = this
     const len = this.options.list.length;
     const $inner = this.$inner;
@@ -317,7 +321,7 @@ Banner.prototype.bindEvent = function(){
             } else if (newTranslate < -this.signWidth * len) {
                 newTranslate += this.signWidth * len;
             }
-            
+
             // 在移动到新位置前，先变换当前位置到正确区域
             await this.normalizeTranslate();
         } else {
@@ -325,7 +329,7 @@ Banner.prototype.bindEvent = function(){
         }
 
         $inner.css('transition', 'transform 0.3s ease-out')
-        $inner.css('transform',`translateX(${this.currentTranslate}px)`);
+        $inner.css('transform', `translateX(${this.currentTranslate}px)`);
 
         if (newTranslate !== this.currentTranslate) {
             this.setTranslate(newTranslate);
@@ -335,11 +339,11 @@ Banner.prototype.bindEvent = function(){
         // 由于 newTranslate 包含了前后的循环占位（位置 0 和 len+1 ），需要减1后取模
         const newIndex = (Math.round(-newTranslate / this.signWidth) + len - 1) % len;
         if (this.options.isTitleEnabled) {
-            this.$pagination.children().eq(newIndex+1).addClass('active').siblings().removeClass('active');
+            this.$pagination.children().eq(newIndex + 1).addClass('active').siblings().removeClass('active');
             this.$titleBox.text(this.options.list[newIndex].title);
         }
         if (this.options.pageChanged && newIndex != this.index) {
-            this.options.pageChanged(this.$inner.children().eq(newIndex+1), this.options.list[newIndex], newIndex);
+            this.options.pageChanged(this.$inner.children().eq(newIndex + 1), this.options.list[newIndex], newIndex);
         }
         this.index = newIndex;
         this.startAutoPlay();
@@ -350,15 +354,15 @@ Banner.prototype.bindEvent = function(){
     if (windowEnv === 'h5') { // 浏览器环境
         $inner
             .attr('draggable', 'false')
-            .on('pointerdown', function(e) {
+            .on('pointerdown', function (e) {
                 pStart(e.originalEvent.clientX, () => {
                     this.setPointerCapture(e.originalEvent.pointerId);
                 });
             })
-            .on('pointermove', function(e) {
+            .on('pointermove', function (e) {
                 pMove(e.originalEvent.clientX);
             })
-            .on('pointerup', async function(e) {
+            .on('pointerup', async function (e) {
                 await pEnd(() => {
                     this.releasePointerCapture(e.originalEvent.pointerId);
                 });
@@ -380,23 +384,23 @@ Banner.prototype.bindEvent = function(){
     $inner.on('transitionend', () => {
         $inner.css('transition', 'none');
     })
-    .on('click', function(e){
-        if(!self.options.click){
-            return 
-        }
-        if (windowEnv === 'h5' && Math.abs(e.clientX - originalX) > 10) {
-            // 防止浏览器中拖动时触发click
-            return
-        }
+        .on('click', function (e) {
+            if (!self.options.click) {
+                return
+            }
+            if (windowEnv === 'h5' && Math.abs(e.clientX - originalX) > 10) {
+                // 防止浏览器中拖动时触发click
+                return
+            }
 
-        const $t = self.$inner.children().eq(self.index + 1);
-        self.options.click($t, self.options.list[self.index], self.index);
-    });
+            const $t = self.$inner.children().eq(self.index + 1);
+            self.options.click($t, self.options.list[self.index], self.index);
+        });
 }
 
 Banner.prototype.setTranslate = function (transX) {
     this.currentTranslate = transX;
-    this.$inner.css('transform',`translateX(${this.currentTranslate}px)`);
+    this.$inner.css('transform', `translateX(${this.currentTranslate}px)`);
 }
 
 /**
@@ -420,7 +424,7 @@ Banner.prototype.normalizeTranslate = async function () {
  * 加载所有背景图片，将data-background-url属性设置为背景图片
  */
 Banner.prototype.loadAllBackgrounds = function () {
-    this.$inner.children().each(function() {
+    this.$inner.children().each(function () {
         $(this).css('background-image', `url(${$(this).attr('data-background-url')})`)
     });
     // console.log('banner images loaded');

package/components/list/list.js

@@ -1,4 +1,7 @@
-import { $, windowEnv } from "../config";
+import { getEnv } from "../config";
+
+let $ = null;
+
 // 默认配置
 const DEFAULTS = {
     itemHeight: 50,       // 单条数据高度
@@ -14,6 +17,8 @@ const DEFAULTS = {
 };
 
 export function List(options = {}) {
+    $ = getEnv().$;
+
     this.options = Object.assign({}, DEFAULTS, options);
     // 标记是否有更新元素用的回调函数
     this.hasUpdateItem = options.updateItem && (options.updateItem.constructor === Function) ? true : false;

package/components/waterfall/waterfall.js

@@ -1,3 +1,4 @@
+import "./waterfall.scss"
 import { getEnv } from "../config.js";
 import { remToPx } from "../../utils/utils.js";
 
@@ -19,6 +20,10 @@ const DEFAULTS = {
     // 传入 $node, data, index
     updateItem: null, // 元素更新时的回调函数
     onscroll: null,   // 滚动事件回调函数
+    shouldOccupySpace: null, // 是否是静态数据的回调函数，静态数据能够占用元素
+    showLoading: null,  // 展示loading的回调函数 params:$node
+    hideLoading: null,  // 隐藏loading的回调函数 
+    createLoading: null,  // 创建loading的回调函数
 };
 
 export function Waterfall(optionsInput = {}) {
@@ -30,6 +35,14 @@ export function Waterfall(optionsInput = {}) {
     // 标记是否有更新元素用的回调函数
     this.hasUpdateItem = options.updateItem && (options.updateItem.constructor === Function) ? true : false;
 
+    // 新方案：数据ID映射机制
+    this.dataIdMap = new Map(); // 数据ID -> 布局信息映射
+    this.nextDataId = 0; // 下一个数据ID
+    this.renderedDataIds = new Set(); // 已渲染的数据ID集合
+
+    this.$loadingNode = null;
+
+
     // 间隔字符串转数字
     if (options.columnGap.constructor === String) {
         // 如果是rem单位，则需要计算
@@ -85,13 +98,29 @@ export function Waterfall(optionsInput = {}) {
         this.columnItems.push(this.createColumn(i));
     }
 
-    this.renderIndex = 0;  // 渲染索引
-    this.activeNodes = new Map();  // 当前活跃节点（索引 -> DOM）
+    this.renderIndex = 0;  // 渲染索引（保留兼容性）
+    this.activeNodes = new Map();  // 当前活跃节点（数据ID -> DOM）
     this.nodePool = [];            // DOM 节点池
 
+    // 新方案：初始化数据ID映射
+    this.dataIdMap = new Map(); // 数据ID -> 布局信息映射
+    this.nextDataId = 0; // 下一个数据ID
+    this.renderedDataIds = new Set(); // 已渲染的数据ID集合
+
+    // 为初始数据分配数据ID
+    this.options.data.forEach((item, index) => {
+        const dataId = index; //this.nextDataId++;
+        this.dataIdMap.set(dataId, {
+            data: true,//item,
+            originalIndex: index,
+            layoutInfo: null // 将在布局时填充
+        });
+    });
+
     this.init();
 }
 
+
 Waterfall.prototype.init = function () {
     const self = this;
     const options = this.options;
@@ -99,8 +128,8 @@ Waterfall.prototype.init = function () {
 
     this.nodePool = [];            // DOM 节点池
     this.activeNodes = new Map();  // 当前活跃节点（索引 -> DOM）
-
-
+    this.allReadyNodes = new Map();    // 所有节点（索引 -> DOM）
+    this.renderIndex = 0;  // 渲染索引（保留兼容性）
 
     $container.html(`
         <div class="waterfall-list-scroll" style="">
@@ -108,6 +137,18 @@ Waterfall.prototype.init = function () {
         </div>
       `);
 
+
+
+    // 如果有定义loading函数  那么创建一个loading节点元素
+    if (options.createLoading) {
+        this.$loadingNode = $(
+            `<div class="waterfall-loading" style="transform: translate(0px, -99999px)"></div>`
+        );
+        $container.find('.waterfall-list-viewport').append(this.$loadingNode);
+
+        options.createLoading(this.$loadingNode);
+    }
+
     // 绑定滚动事件（节流处理）
     $container.off().on('scroll', function () {
         self.scrollTop = $(this).scrollTop();
@@ -134,8 +175,9 @@ Waterfall.prototype.updateVisibleItems = function (force = false) {
     const options = this.options;
     const $container = $(options.container);
 
-    const startTop = this.scrollTop;
+    const startTop = self.scrollTop; // 当前滚动位置
     const endTop = startTop + $container.height();
+    // console.log('startTop', startTop)
 
     // 进行可见区域的渲染更新
     this.updateCardsInView({
@@ -143,23 +185,44 @@ Waterfall.prototype.updateVisibleItems = function (force = false) {
         end: endTop,
         force
     });
+
 }
 
 // 新增卡片
-Waterfall.prototype.appendCard = function (data, index, { top, left }) {
+Waterfall.prototype.appendCard = function (data, dataId, { top, left }) {
     const self = this;
     const options = this.options;
     const $container = $(options.container);
     const $viewport = $container.find('.waterfall-list-viewport');
+
+    // 新方案：基于数据ID的数据验证
+    if (!this.dataIdMap.has(dataId)) {
+        console.error('Waterfall: Invalid dataId in appendCard', dataId);
+        return null;
+    }
+
+    const dataInfo = this.dataIdMap.get(dataId);
+    if (!dataInfo || !dataInfo.data) {
+        console.warn('Waterfall: Empty data for dataId', dataId);
+    }
+
+
     const $card = $(
         `<div class="waterfall-item" 
-              data-index="${index}"
-              style="position: absolute;transform:translate(${left}px,${top}px); width:${this.columnWidth}px;"
+              data-index="${dataId}"
+              style="position: absolute;transform:translate(${left}px,${top}px);"
         >
-        ${options.renderItem(data, index)}
+        ${options.renderItem(data, dataInfo.originalIndex)}
          </div> `
     );
 
+    this.renderedDataIds.add(dataId);
+
+    if (options.columns !== 1) {
+        $card.width(this.columnWidth + 'px');
+    }
+
+
     $viewport.append($card);
     return $card;
 }
@@ -174,49 +237,105 @@ Waterfall.prototype.updateCardsInView = function ({ start, end, force = false })
         this.createCards({ end: endBuffer });
     }
 
-    // 基于已有的列信息，进行高度可视区域下的判定 操作已有信息。 如果是新建信息 则依赖上方的createCards方法进行创建,那么在上方会异步创建新卡片。
-    // 阶段1：复用已有节点
+    const startNum = start - options.bufferHeight;
+    const endNum = end + options.bufferHeight;
+    // 新方案：基于数据ID映射机制
     const newActiveNodes = new Map();
     for (let i = 0; i < this.columns; i++) {
         const column = this.columnItems[i];
 
         for (let j = 0; j < column.children.length; j++) {
             const row = column.children[j];
-            const renderIndex = row.renderIndex;
+            const dataId = row.dataId; // 使用dataId替代renderIndex
+
+            // 验证数据ID有效性
+            if (!this.dataIdMap.has(dataId)) {
+                console.warn('Waterfall: Invalid dataId detected', dataId);
+                continue;
+            }
+
+            const dataInfo = this.dataIdMap.get(dataId);
+
+            if (!dataInfo) {
+                console.warn('Waterfall: Invalid data for dataId', dataId);
+                continue;
+            }
+
+            const data = options.data[dataId]
+
+            // 如果当前这个节点是特殊节点 不用做处理
+            // 如果是特殊的静态占用元素卡片，需要指定节点不变更的数据，那么该数据的节点不能被其他数据使用
+            let specialNode = false;
+            if (options.shouldOccupySpace) {
+                specialNode = options.shouldOccupySpace(data) || false;
+            }
+            if (specialNode) {
+                continue;
+            }
+
             // 在可视区域内 进行有关卡片的操作
-            if (row.top <= end && row.bottom >= start) {
+            const bool = row.top <= endNum && row.bottom >= startNum;
+            if (bool) {
                 // 理论上什么都不动，因为卡片的位置不会变
-                const $card = this.activeNodes.get(renderIndex);
+                const $card = this.activeNodes.get(dataId);
 
                 let $node = null;
-                // 如果卡片已经在DOM中，则不用更新位置
+
+                // 遍历当前的节点是否被占用，如果被占用的话，就得要从nodePool中取一个
+                let bool = true;
                 if ($card) {
+                    bool = hasNodeInActives(newActiveNodes, $card)
+                }
+                // 如果卡片已经在DOM中，则不用更新位置
+                if (bool === false) {
                     $node = $card;
-                    this.activeNodes.delete(renderIndex);
+                    this.activeNodes.delete(dataId);
+                    // 如果是强更，这里才会采取更新
                     if (force) {
-                        this.updateRenderUI($node, options.data[renderIndex], renderIndex);
+                        this.updateRenderUI($node, data, dataId);
                     }
+
                 } else {
-                    // 卡片不在DOM中，则更新位置
-                    let nodePool = this.nodePool;
-                    if (nodePool.length === 0) {
-                        // 这里是往上方拖动时，可能需要补建的情况
-                        // 如果池子没有节点,那么进行创建
-                        $node = this.appendCard(options.data[renderIndex], renderIndex, {
-                            top: row.top, left: row.left
-                        })
-                        row.$node = $node;
+                    const $card = this.allReadyNodes.get(dataId);
+                    // 遍历当前的节点是否被占用，如果被占用的话，就得要从nodePool中取一个
+                    let bool = true;
+                    if ($card) {
+                        bool = hasNodeInActives(newActiveNodes, $card)
+                    }
+                    if (bool === false) {
+                        // 如果成功获取到card并没有占用 那么就复用这个card
+                        $node = $card;
+
+                        this.updateRenderUI($node, data, dataId);
+
                     } else {
-                        $node = $(this.nodePool.pop());
-                        $node.css({
-                            'transform': `translate(${row.left}px,${row.top}px)`,
-                        }).attr('data-index', renderIndex);
-                        this.updateRenderUI($node, options.data[renderIndex], renderIndex);
-                        row.$node = $node;
+                        // 卡片不在DOM中，则更新位置
+                        $node = getNodePoolPop(this.nodePool, newActiveNodes);
+                        if ($node === null) {
+                            // 这里是往上方拖动时，可能需要补建的情况
+                            $node = this.appendCard(data, dataId, {
+                                top: row.top, left: row.left
+                            });
+                            row.$node = $node;
+                        } else {
+                            this.updateRenderUI($node, data, dataId);
+                            row.$node = $node;
+                        }
                     }
                 }
+                $node.css({
+                    'transform': `translate(${row.left}px,${row.top}px)`,
+                }).attr('data-index', dataId);
+
+                newActiveNodes.set(dataId, $node);
+
+                // 清除掉在NodePool中的card
+                const index = this.nodePool.indexOf($card);
+                if (index !== -1) {
+                    this.nodePool.splice(index, 1);
+                }
 
-                newActiveNodes.set(renderIndex, $node);
+                // console.log('302-row', row.dataId, dataInfo);
             }
         }
     }
@@ -224,11 +343,16 @@ Waterfall.prototype.updateCardsInView = function ({ start, end, force = false })
     // 阶段2：处理不活跃节点
     this.activeNodes.forEach($node => {
         $node.css('transform', `translateY(-9999px)`);// 移出可视区域
-        this.nodePool.push($node);
+        if (this.nodePool.indexOf($node) === -1) {
+            this.nodePool.push($node);
+        }
     });
     this.activeNodes = newActiveNodes;
+    // console.log('this.activeNodes', this.activeNodes);
+    // console.log('this.nodePool', this.nodePool);
 }
 
+
 Waterfall.prototype.getMaxHeight = function () {
     let maxHeight = 0;
     for (let i = 0; i < this.columns; i++) {
@@ -276,79 +400,126 @@ Waterfall.prototype.getMinHeightColumn = function () {
 }
 
 // 创建卡片
-Waterfall.prototype.createCards = function ({ end }) {
+Waterfall.prototype.createCards = function ({ end, dataId = -1 }) {
     const self = this;
     const options = this.options;
     const $container = $(options.container);
-    const renderIndex = this.renderIndex;
 
-    if (renderIndex >= options.data.length) {
+    // 新方案：获取下一个未渲染的数据ID
+    let nextDataId = null;
+    for (let [dataId, dataInfo] of this.dataIdMap) {
+        if (!this.renderedDataIds.has(dataId)) {
+            nextDataId = dataId;
+            break;
+        }
+    }
+
+
+    // 如果没有更多数据需要渲染
+    if (nextDataId === null) {
         const maxHeight = this.getMaxHeight();
-        // 设置一次整体高度
-        $(options.container).find('.waterfall-list-scroll').css('height', maxHeight + options.marginBottom)
+        $container.find('.waterfall-list-scroll').css('height', maxHeight + options.marginBottom + 'px');
+        return;
+    }
+
+    const dataInfo = this.dataIdMap.get(nextDataId);
+    if (!dataInfo || !dataInfo.data) {
+        console.warn('Waterfall: Invalid data for dataId', nextDataId);
         return;
     }
 
+    if (this.renderIndex >= options.data.length) {
+        const maxHeight = this.getMaxHeight();
+        $container.find('.waterfall-list-scroll').css('height', maxHeight + options.marginBottom + 'px');
+        return
+    }
+
+    const data = options.data[nextDataId];
+
     let column = this.getMinHeightColumn();
     if (column === null) {
-        // 没有可用的列，则在第一列创建，说明此时还没有数据
         column = this.columnItems[0];
     }
 
     const top = column.bottom === 0 ? options.marginTop : (column.bottom + options.rowGap);
+    const position = { top, left: column.left };
+    const row = createDefaultRow(position);
 
-    // 设置卡片位置
-    const position = {
-        top,
-        left: column.left,
-    }
+    this.renderIndex += 1;
 
-    const row = createDefaultRow(position);
+    let specialNode = false;
 
+    // 如果是特殊的卡片，需要指定节点不变更的数据，那么该数据的节点不能被其他数据使用
+    if (options.shouldOccupySpace) {
+        specialNode = options.shouldOccupySpace(data) || false;
+    }
 
-    // 添加卡片
+    // 添加卡片，使用dataId作为唯一标识
     let $card = null;
-    if (this.nodePool.length === 0) {
-        $card = this.appendCard(options.data[renderIndex], renderIndex, position);
+    if (this.nodePool.length === 0 || specialNode === true) {
+        $card = this.appendCard(data, nextDataId, position);
     } else {
-        $card = $(this.nodePool.pop());
-        $card.css({
-            'transform': `translate(${row.left}px,${row.top}px)`,
-        }).attr('data-index', renderIndex);
-        this.updateRenderUI($card, options.data[renderIndex], renderIndex);
-    }
+        const $tmp = getNodePoolPop(this.nodePool, this.activeNodes);
+        if ($tmp) {
+            $card = $tmp;
+            $card.css({
+                'transform': `translate(${row.left}px,${row.top}px)`,
+            }).attr('data-index', nextDataId);
+            this.updateRenderUI($card, data, nextDataId);
+        } else {
+            $card = this.appendCard(data, nextDataId, position);
+        }
 
+    }
 
     row.$node = $card;
+    row.dataId = nextDataId; // 使用dataId替代renderIndex
+    if (dataId !== -1) {
+        row.dataId = dataId;
+    }
+
+    // 记录布局信息
+    // dataInfo.layoutInfo = {
+    //     //columnIndex: this.columnItems.indexOf(column),
+    //     //position: position,
+    //     // row: row
+    // };
+
 
-    // 把新增的卡片放进 activeNodes, 当前是 展示状态的
-    this.activeNodes.set(renderIndex, $card);
 
 
+    if (specialNode === false) {
+        // 把新增的卡片放进 activeNodes 当成活跃节点元素，那么是 可以动态使用的
+        this.activeNodes.set(nextDataId, $card);
+
+        this.allReadyNodes.set(nextDataId, $card);
+    } else {
+        // 如果是特殊的，这里不要记录了 
+        this.allReadyNodes.set(nextDataId, null);
+    }
+
+    this.renderedDataIds.add(nextDataId);
+
     // 更新列的底部距离
     column.bottom = top + $card.height();
     column.children.push(row);
-
-    // 计算当前卡片的位置
     row.bottom = column.bottom;
-    row.renderIndex = renderIndex;
-
-    this.renderIndex += 1;
-
-    let hasNextData = this.renderIndex < options.data.length;
 
+    // 检查是否需要继续创建卡片
     const minHeight = this.getMinHeight();
-    if (hasNextData && (minHeight < end)) {
+    const hasMoreData = this.renderedDataIds.size < this.dataIdMap.size;
+
+    if (hasMoreData && (minHeight < end)) {
         window.requestAnimationFrame(() => {
             this.createCards({ end });
         });
     } else {
         const maxHeight = this.getMaxHeight();
-        // 设置一次整体高度
-        $(options.container).find('.waterfall-list-scroll').css('height', maxHeight + options.marginBottom)
+        $(options.container).find('.waterfall-list-scroll').css('height', maxHeight + options.marginBottom + 'px');
     }
 }
 
+
 Waterfall.prototype.createColumn = function (index) {
     const res = {
         left: 0,
@@ -365,18 +536,205 @@ Waterfall.prototype.createColumn = function (index) {
     return res;
 }
 
-Waterfall.prototype.updateRenderUI = function ($node, data, index) {
+Waterfall.prototype.updateRenderUI = function ($node, data, dataId) {
     const options = this.options;
+
+    // 新方案：基于数据ID的数据验证
+    if (!this.dataIdMap.has(dataId)) {
+        console.error('Waterfall: Invalid dataId in updateRenderUI', dataId);
+        return;
+    }
+
+    const dataInfo = this.dataIdMap.get(dataId);
+    if (!dataInfo || !dataInfo.data) {
+        console.warn('Waterfall: Empty data for dataId', dataId);
+    }
+
     if (this.hasUpdateItem === true) {
-        options.updateItem($node, data, index)
+        options.updateItem($node, data, dataInfo.originalIndex)
     } else {
-        $node.html(options.renderItem(data, index));
+        $node.html(options.renderItem(data, dataInfo.originalIndex));
     }
 }
 
+
+
 Waterfall.prototype.updateData = function (newData) {
-    this.options.data = newData;
+    const options = this.options;
+    options.data = newData;
+
+    // 新方案：重新建立数据ID映射
+    //this.dataIdMap.clear();
+    //this.renderedDataIds.clear();
+    //this.nextDataId = 0;
+
+    // 为每个数据项分配唯一ID
+    options.data.forEach((item, index) => {
+        const dataId = index; // this.nextDataId++;
+        if (!this.allReadyNodes.has(dataId)) {
+            this.dataIdMap.set(dataId, {
+                data: true,// item,
+                originalIndex: index,
+                layoutInfo: null // 将在布局时填充
+            });
+            // 如果没有准备好这个数据，这里要创建一个占位节点
+            this.createCards({ end: 0, dataId });
+        }
+    });
+
     this.updateVisibleItems(true); // 强制更新渲染
+
+    // 重新计算所有卡片位置并更新位置
+    // this.updatePointCards();
+}
+
+// 某个数据进行了UI变更，触发高度重新绘制
+Waterfall.prototype.updateCard = function (data) {
+    const options = this.options;
+    let dataId = -1;
+    if (typeof data === 'number') {
+        dataId = data;
+    } else {
+        for (let i = 0; i < options.data.length; i++) {
+            if (options.data[i] === data) {
+                dataId = i;
+                break;
+            }
+        }
+    }
+    if (dataId === -1) {
+        // 没有匹配到数据，进行退出
+        console.log('Waterfall: Invalid data in options.data');
+        return
+    }
+
+    // 从activeNodes中获取该数据的节点
+    if (!this.activeNodes.has(dataId)) {
+        console.log('Waterfall: Invalid dataId in activeNodes');
+        return
+    }
+
+    const $node = this.activeNodes.get(dataId);
+    const height = $node.height();
+
+    // 重新计算该数据所在列的卡片位置
+    let needUpdate = false
+    const columnItems = this.columnItems;
+    for (let i = 0; i < columnItems.length; i++) {
+        const column = columnItems[i];
+        let bool = false
+        let minus = 0
+        // 这里为了简化，各列的瀑布流保持不动，只更新各列下节点的top位置，不做节点的跨列位移
+        for (let j = 0; j < column.children.length; j++) {
+            const row = column.children[j];
+            if (row.dataId === dataId) {
+                bool = true
+                const oldHeight = row.bottom - row.top;
+
+                minus = height - oldHeight;
+
+                if (minus === 0) {
+                    // 找到了原节点数据，对比后没有变更 那么直接退出
+                    return;
+                }
+                needUpdate = true
+                row.bottom += minus;
+            } else if (minus !== 0) {
+                row.top += minus;
+                row.bottom += minus;
+            }
+        }
+        if (bool) {
+            column.bottom += minus;
+            break;
+        }
+    }
+    if (needUpdate) {
+        this.updateVisibleItems(true); // 强制更新渲染
+    }
+}
+
+// 重新计算设置一遍所有的卡片位置
+Waterfall.prototype.updatePointCards = function () {
+    // 有问题 不要用
+    return
+    const self = this;
+    const options = this.options;
+    const columnItems = this.columnItems;
+    let top = options.marginTop;
+    for (let i = 0; i < columnItems.length; i++) {
+        const column = columnItems[i];
+        // 这里为了简化，各列的瀑布流保持不动，只更新各列下节点的top位置，不做节点的跨列位移
+        for (let j = 0; j < column.children.length; j++) {
+            const row = column.children[j];
+            const $card = row.$node;
+
+            // 验证数据ID有效性
+            if (!this.dataIdMap.has(row.dataId)) {
+                console.warn('Waterfall: Invalid dataId in updatePointCards', row.dataId);
+                continue;
+            }
+
+            // 第一个的top不需要更新
+            if (j === 0) {
+                row.bottom = top + $card.height();
+            } else {
+                row.top = column.children[j - 1].bottom + options.rowGap;
+                row.bottom = row.top + $card.height();
+                // 更新卡片位置
+                // $card.css({
+                //     'transform': `translate(${row.left}px,${row.top}px)`,
+                // })
+            }
+
+        }
+        // 设置一次该列的bottom
+        column.bottom = getBottomByColumn(column);
+    }
+}
+
+// 展示loading的回调函数
+Waterfall.prototype.showLoading = function (callback = null) {
+    const options = this.options;
+    const $container = $(options.container);
+    let $node = null
+    if (this.$loadingNode) {
+        let loadingTop = this.getMaxHeight() + options.rowGap
+        let h = loadingTop + this.$loadingNode.height() + options.marginBottom
+
+        this.$loadingNode.css('transform', `translate(0px,${loadingTop}px)`);
+        $(options.container).find('.waterfall-list-scroll').css('height', h + 'px');
+
+        $node = this.$loadingNode
+    }
+
+    if (callback) callback($node)
+}
+
+// 隐藏loading的回调函数
+Waterfall.prototype.hideLoading = function (callback = null) {
+    const options = this.options;
+    const $container = $(options.container);
+    let $node = null
+    if (this.$loadingNode) {
+        let h1 = this.getMaxHeight() + options.marginBottom
+        this.$loadingNode.css('transform', `translate(0px,-99999px)`);
+        //如果要设置高度，那么这里判断一下当前是否正在做updata  一般这里被调用时，数据已经读到，在updata的同一时间调用了该函数
+        // 如果两个时刻高度是一致的 那么数据就是一致的 这里重新设置回来高度即可
+        window.requestAnimationFrame(() => {
+            let h2 = this.getMaxHeight() + options.marginBottom
+            if (h1 === h2) {
+                const $scroll = $(options.container).find('.waterfall-list-scroll')
+                const h = $scroll.height()
+                if (h !== h1) {
+                    $scroll.css('height', h1 + 'px');
+                }
+            }
+        })
+        $node = this.$loadingNode
+    }
+
+    if (callback) callback($node)
 }
 
 function createDefaultRow({ top, left }) {
@@ -385,13 +743,37 @@ function createDefaultRow({ top, left }) {
         left,
         bottom: 0,
         $node: null,
-        renderIndex: -1
+        dataId: -1 // 新方案：使用dataId替代renderIndex
     }
 }
 
-function getBottomByColumn(rows) {
-    if (rows.children.length === 0) {
+
+function getBottomByColumn(column) {
+    if (column.children.length === 0) {
         return 0;
     }
-    return rows[rows.length - 1].bottom;
+    const child = column.children;
+    return child[child.length - 1].bottom;
+}
+
+function hasNodeInActives(mapObj, $node) {
+    let bool = false
+    mapObj.forEach((item) => {
+        if (item === $node) {
+            bool = true;
+        }
+    });
+    return bool;
+}
+
+// 从众多jq对象数组取得一个不重复的
+function getNodePoolPop(nodePool, actives) {
+    for (let i = 0; i < nodePool.length; i++) {
+        const $node = nodePool[i];
+        if (!hasNodeInActives(actives, $node)) {
+            nodePool.splice(i, 1);
+            return $node;
+        }
+    }
+    return null;
 }

package/components/waterfall/waterfall.scss

@@ -0,0 +1,17 @@
+.waterfall-list-scroll {
+  height: 100%;
+  .waterfall-loading {
+    position: absolute;
+    width: 100%;
+    align-items: center;
+    justify-content: center;
+  }
+  .waterfall-item {
+    flex: 1;
+    flex-shrink: 1;
+    flex-grow: 1;
+    flex-basis: 0;
+    width: 100%;
+    position: absolute;
+  }
+}

package/package.json

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