tencent.jquery.pix.component 1.0.83 → 1.0.86

package/components/waterfallv2/waterfallv2.js

@@ -0,0 +1,1434 @@
+import { remToPx } from "../../utils/utils.js";
+import { getEnv } from "../config.js";
+import "./waterfallv2.scss";
+
+let $ = null;
+
+// 全局自增 ID 计数器，用于为没有 dataId 的数据元素统一分配唯一 ID
+let _globalDataIdCounter = 0;
+
+/**
+ * 为数据列表中没有 dataId 的元素统一分配唯一 ID
+ * 规则：遍历所有元素，若某个元素缺少 dataId 属性，则统一为整个列表重新分配
+ * @param {Array} data - 数据列表
+ */
+function assignDataIds(data) {
+    // 检查是否有元素缺少 dataId
+    const hasMissing = data.some(item => item.dataId === undefined || item.dataId === null);
+    if (!hasMissing) return; // 全部已有 dataId，无需处理
+
+    // 存在缺失，统一为所有元素分配 dataId
+    console.warn('Waterfallv2: 数据列表中存在未定义 dataId 的元素，将由组件统一分配。');
+    data.forEach(item => {
+        if (item.dataId === undefined || item.dataId === null) {
+            item.dataId = 'pix_wf_' + (_globalDataIdCounter++);
+        }
+    });
+}
+
+// 默认配置
+const DEFAULTS = {
+    columns: 2,       // 列数
+    columnGap: 10,              // 左右间隔
+    rowGap: 12,         // 上下间隔
+    marginTop: 0,  // 距离顶部距离
+    marginBottom: 12,  // 最后一行距离底部距离
+    bufferHeight: '2rem', // 缓冲高度，进行可能的预先添加高度
+    startPoints: [], // 起始点距离
+    data: [],              // 数据源
+    container: '',                // 容器元素
+    renderItem(data, index, $card) {      // 元素首次渲染时的回调函数, 如果把updateItem设置为空，那么更新时则会兜底触发renderItem
+        return '<div class="waterfallv2-item"></div>';
+    },
+    scrollDom: null, // 滚动元素,如果传入了滚动元素，那么用来计算的窗口高度就以滚动元素的高度为准
+    // 传入 $node, data, index
+    updateItem: null, // 元素更新时的回调函数
+    onscroll: null,   // 滚动事件回调函数
+    shouldOccupySpace: null, // 是否是静态数据的回调函数，静态数据能够占用元素
+    showLoading: null,  // 展示loading的回调函数 params:$node
+    hideLoading: null,  // 隐藏loading的回调函数 
+    createLoading: null,  // 创建loading的回调函数
+};
+
+export function Waterfallv2(optionsInput = {}) {
+    $ = getEnv().$;
+
+    this.optionsInput = optionsInput
+
+    this.init();
+}
+
+
+Waterfallv2.prototype.init = function (optionsMain = null) {
+    // 重置自增的基础数值
+    _globalDataIdCounter = 0;
+    if (optionsMain) {
+        this.options = Object.assign({}, DEFAULTS, optionsMain);
+    } else {
+        this.options = Object.assign({}, DEFAULTS, this.optionsInput);
+    }
+    const self = this;
+    const options = this.options;
+    const $container = $(options.container);
+    const $scrollDom = options.scrollDom ? $(options.scrollDom) : $container;
+
+
+    // 标记是否有更新元素用的回调函数
+    this.hasUpdateItem = options.updateItem && (options.updateItem.constructor === Function) ? true : false;
+
+    // 数据ID映射机制
+    this.dataIdMap = new Map(); // dataId -> 布局信息映射
+    this.renderedDataIds = new Set(); // 已渲染的 dataId 集合
+
+    this.$loadingNode = null;
+
+    this.isShowLoading = false;  // 是否展示loading
+
+
+    // 间隔字符串转数字
+    if (options.columnGap.constructor === String) {
+        if (options.columnGap.indexOf('rem') > -1) {
+            options.columnGap = remToPx(options.columnGap);
+        } else {
+            options.columnGap = parseFloat(options.columnGap);
+        }
+    }
+    if (options.rowGap.constructor === String) {
+        if (options.rowGap.indexOf('rem') > -1) {
+            options.rowGap = remToPx(options.rowGap);
+        } else {
+            options.rowGap = parseFloat(options.rowGap);
+        }
+    }
+    if (options.bufferHeight.constructor === String) {
+        if (options.bufferHeight.indexOf('rem') > -1) {
+            options.bufferHeight = remToPx(options.bufferHeight);
+        } else {
+            options.bufferHeight = parseFloat(options.bufferHeight);
+        }
+    }
+    if (options.marginTop.constructor === String) {
+        if (options.marginTop.indexOf('rem') > -1) {
+            options.marginTop = remToPx(options.marginTop);
+        } else {
+            options.marginTop = parseFloat(options.marginTop);
+        }
+    }
+    if (options.marginBottom.constructor === String) {
+        if (options.marginBottom.indexOf('rem') > -1) {
+            options.marginBottom = remToPx(options.marginBottom);
+        } else {
+            options.marginBottom = parseFloat(options.marginBottom);
+        }
+    }
+    options.startPoints.forEach((item, index) => {
+        if (item.constructor === String) {
+            options.startPoints[index] = remToPx(item);
+        } else {
+            item = parseFloat(item);
+        }
+    });
+
+    const allWidth = $container.width();
+    this.allWidth = allWidth;
+    // 计算每列的宽度
+    this.columnWidth = (allWidth - (options.columns - 1) * options.columnGap) / options.columns;
+
+    // 记录列数
+    this.columns = options.columns;
+
+    this.columnItems = [];  // 列元素数组
+    for (let i = 0; i < this.columns; i++) {
+        this.columnItems.push(this.createColumn(i));
+    }
+
+    this.$scrollDom = $scrollDom;
+
+    this.nodePool = [];            // DOM 节点池
+    this.activeNodes = new Map();  // 当前活跃节点（索引 -> DOM）
+    this.allReadyNodes = new Map();    // 所有节点（索引 -> DOM）
+    this.renderIndex = 0;  // 渲染索引（保留兼容性）
+
+
+
+    // 为数据列表中缺少 dataId 的元素统一分配唯一 ID
+    assignDataIds(this.options.data);
+
+    // 数据ID映射：dataId -> 布局信息
+    this.dataIdMap = new Map();
+    this.renderedDataIds = new Set(); // 已渲染的 dataId 集合
+
+    // 为初始数据建立 dataIdMap
+    this.options.data.forEach((item) => {
+        const dataId = item.dataId;
+        this.dataIdMap.set(dataId, {
+            data: true,
+            layoutInfo: null // 将在布局时填充
+        });
+    });
+
+    $container.html(`
+        <div class="waterfallv2-list-scroll" style="">
+          <div class="Waterfallv2-list-viewport" style="position:relative;"></div>
+        </div>
+      `);
+
+
+
+    // 如果有定义loading函数  那么创建一个loading节点元素
+    console.log('options.createLoading', options.createLoading)
+    if (options.createLoading) {
+        this.$loadingNode = $(
+            `<div class="waterfallv2-loading" style="position:absolute;top:0;left:0;width:100%;transform: translate(0px, -99999px)"></div>`
+        );
+        $container.find('.Waterfallv2-list-viewport').append(this.$loadingNode);
+
+        options.createLoading(this.$loadingNode);
+    }
+
+    // 绑定滚动事件（节流处理）
+    $scrollDom.off().on('scroll', function () {
+        self.scrollTop = $(this).scrollTop();
+
+        window.requestAnimationFrame(() => {
+            self.updateVisibleItems();
+        });
+
+        if (options.onscroll && options.onscroll.constructor === Function) {
+            options.onscroll(this, self.scrollTop);
+        }
+    });
+
+    this.scrollTop = $scrollDom.scrollTop();  // 当前滚动位置
+
+    // 首次渲染
+    self.updateVisibleItems();
+
+}
+
+// force 强制更新渲染
+Waterfallv2.prototype.updateVisibleItems = function (force = false) {
+    const self = this;
+    const options = this.options;
+    let h = 0;
+    if (options.scrollDom) {
+        h = $(options.scrollDom).height();
+    } else {
+        h = $(options.container).height();
+    }
+
+    const startTop = self.scrollTop; // 当前滚动位置
+    const endTop = startTop + h;
+
+    // 进行可见区域的渲染更新
+    this.updateCardsInView({
+        start: startTop,
+        end: endTop,
+        force
+    });
+
+}
+
+// 新增卡片
+Waterfallv2.prototype.appendCard = function (data, dataId, { top, left }) {
+    const options = this.options;
+    const $container = $(options.container);
+    const $viewport = $container.find('.Waterfallv2-list-viewport');
+
+    if (!this.dataIdMap.has(dataId)) {
+        console.error('Waterfallv2: Invalid dataId in appendCard', dataId);
+        return null;
+    }
+
+    // 获取该数据在 options.data 中的当前索引
+    const originalIndex = options.data.indexOf(data);
+
+    const $card = $(
+        `<div class="waterfallv2-item" 
+              data-index="${dataId}"
+              style="position: absolute;transform:translate(${left}px,${top}px);"
+        >
+         </div> `
+    );
+
+    $viewport.append($card);
+
+    const str = options.renderItem(data, originalIndex, $card);
+
+    if (str) {
+        $card.html(str);
+    }
+
+    this.renderedDataIds.add(dataId);
+
+    if (options.columns !== 1) {
+        $card.width(this.columnWidth + 'px');
+    }
+
+    return $card;
+}
+
+// 获取指定高度下的卡片索引
+Waterfallv2.prototype.updateCardsInView = async function ({ start, end, force = false }) {
+    const options = this.options;
+    const minHeight = this.getMinHeight();
+    const endBuffer = end + options.bufferHeight;
+    if (minHeight < endBuffer) {
+        // 如果不够 进行补建
+        await this.createCards({ end: endBuffer });
+    }
+
+    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 dataId = row.dataId; // 使用dataId替代renderIndex
+
+            // 验证数据ID有效性
+            if (!this.dataIdMap.has(dataId)) {
+                console.warn('Waterfallv2: Invalid dataId detected', dataId);
+                continue;
+            }
+
+            const dataInfo = this.dataIdMap.get(dataId);
+
+            if (!dataInfo) {
+                console.warn('Waterfallv2: Invalid data for dataId', dataId);
+                continue;
+            }
+
+            // 通过 dataId 找到对应的数据对象
+            const data = options.data.find(item => item.dataId === dataId);
+
+            // 如果当前这个节点是特殊节点，只更新位置，不参与节点复用
+            let specialNode = false;
+            if (options.shouldOccupySpace) {
+                specialNode = options.shouldOccupySpace(data) || false;
+            }
+            if (specialNode) {
+                // 特殊节点：只更新位置，不参与复用逻辑
+                if (row.$node && row.$node.length) {
+                    row.$node.css({
+                        'transform': `translate(${row.left}px,${row.top}px)`,
+                    }).attr('data-index', dataId);
+
+                    if (force) {
+                        this.updateRenderUI(row.$node, data, dataId);
+                    }
+                } else {
+                    console.warn('Waterfallv2: Special node DOM not found for dataId', dataId);
+                }
+                continue;
+            }
+
+            // 在可视区域内 进行有关卡片的操作
+            const bool = row.top <= endNum && row.bottom >= startNum;
+            if (bool) {
+                const $card = this.activeNodes.get(dataId);
+
+                let $node = null;
+
+                let bool = true;
+                if ($card) {
+                    bool = hasNodeInActives(newActiveNodes, $card)
+                }
+                if (bool === false) {
+                    $node = $card;
+                    this.activeNodes.delete(dataId);
+                    if (force) {
+                        this.updateRenderUI($node, data, dataId);
+                    }
+
+                } else {
+                    const $card = this.allReadyNodes.get(dataId);
+                    let bool = true;
+                    if ($card) {
+                        bool = hasNodeInActives(newActiveNodes, $card)
+                    }
+                    if (bool === false) {
+                        $node = $card;
+                        this.updateRenderUI($node, data, dataId);
+
+                    } else {
+                        $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);
+                }
+            }
+        }
+    }
+
+    // 阶段2：处理不活跃节点
+    this.activeNodes.forEach($node => {
+        $node.css('transform', `translateY(-9999px)`);// 移出可视区域
+        if (this.nodePool.indexOf($node) === -1) {
+            this.nodePool.push($node);
+        }
+    });
+    this.activeNodes = newActiveNodes;
+}
+
+
+Waterfallv2.prototype.getMaxHeight = function () {
+    let maxHeight = 0;
+    for (let i = 0; i < this.columns; i++) {
+        const column = this.columnItems[i];
+        // 优先从 children 最后一个 row.bottom 读取，避免 column.bottom 因各种操作累积误差
+        if (column.children.length > 0) {
+            const lastRow = column.children[column.children.length - 1];
+            maxHeight = Math.max(maxHeight, lastRow.bottom);
+        } else {
+            maxHeight = Math.max(maxHeight, column.bottom);
+        }
+    }
+    return maxHeight;
+}
+
+Waterfallv2.prototype.getMinHeight = function () {
+    let minHeight = 0;
+    for (let i = 0; i < this.columns; i++) {
+        const column = this.columnItems[i]
+        if (minHeight === 0) {
+            minHeight = column.bottom;
+        }
+        minHeight = Math.min(minHeight, column.bottom);
+    }
+    return minHeight;
+}
+
+Waterfallv2.prototype.getMinHeightColumn = function () {
+    let minHeight = -1;
+    let mimHeightColumn = null;
+    let index = -1;
+    const startPoints = this.options.startPoints || [];
+    for (let i = 0; i < this.columns; i++) {
+        const column = this.columnItems[i]
+        if (minHeight === -1) {
+            minHeight = column.bottom;
+            mimHeightColumn = column;
+            index = i;
+        } else if (minHeight > column.bottom) {
+            minHeight = column.bottom;
+            mimHeightColumn = column;
+            index = i;
+        }
+    }
+
+    if (minHeight === 0 && index > -1) {
+        if (startPoints.length > index) {
+            mimHeightColumn.bottom = startPoints[index];
+        }
+    }
+
+    return mimHeightColumn;
+}
+
+// 创建卡片
+Waterfallv2.prototype.createCards = function ({ end, dataId = -1 }, callback) {
+    const self = this;
+    const options = this.options;
+
+    return new Promise((resolve) => {
+        // 获取下一个未渲染的数据（按 options.data 顺序）
+        let nextDataId = null;
+        let nextData = null;
+        for (let i = 0; i < options.data.length; i++) {
+            const item = options.data[i];
+            const id = item.dataId;
+            if (!this.renderedDataIds.has(id)) {
+                nextDataId = id;
+                nextData = item;
+                break;
+            }
+        }
+
+        // 如果没有更多数据需要渲染
+        if (nextDataId === null) {
+            this.setScrollHeight();
+            return resolve();
+        }
+
+        if (!this.dataIdMap.has(nextDataId)) {
+            console.warn('Waterfallv2: Invalid dataId in createCards', nextDataId);
+            return resolve();
+        }
+
+        const data = nextData;
+
+        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);
+
+        this.renderIndex += 1;
+
+        let specialNode = false;
+
+        if (options.shouldOccupySpace) {
+            specialNode = options.shouldOccupySpace(data) || false;
+        }
+
+        // 添加卡片，使用dataId作为唯一标识
+        let $card = null;
+        if (this.nodePool.length === 0 || specialNode === true) {
+            $card = this.appendCard(data, nextDataId, position);
+        } else {
+            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;
+
+        if (specialNode === false) {
+            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;
+
+        // 建立 dataIdMap -> row 的引用，用于快速访问布局信息
+        const dataInfo = this.dataIdMap.get(nextDataId);
+        if (dataInfo) {
+            dataInfo.layoutInfo = row;
+        }
+
+        // 检查是否需要继续创建卡片
+        const minHeight = this.getMinHeight();
+        const hasMoreData = this.renderedDataIds.size < this.dataIdMap.size;
+
+        if (hasMoreData && (minHeight < end)) {
+
+            this.createCards({ end }, () => {
+                resolve();
+                if (callback) {
+                    callback();
+                }
+            });
+        } else {
+            this.setScrollHeight();
+            resolve();
+            if (callback) {
+                callback();
+            }
+        }
+    });
+
+}
+
+
+Waterfallv2.prototype.createColumn = function (index) {
+    const res = {
+        left: 0,
+        bottom: 0,
+        width: 0,
+        children: []
+    }
+
+    const options = this.options;
+    const columnWidth = this.columnWidth;
+
+    res.width = this.columnWidth;
+    res.left = (index * (columnWidth + options.columnGap));
+    return res;
+}
+
+Waterfallv2.prototype.updateRenderUI = function ($node, data, dataId) {
+    const options = this.options;
+
+    if (!this.dataIdMap.has(dataId)) {
+        console.error('Waterfallv2: Invalid dataId in updateRenderUI', dataId);
+        return;
+    }
+
+    // 实时获取数据在 options.data 中的当前索引
+    const originalIndex = options.data.indexOf(data);
+
+    if (this.hasUpdateItem === true) {
+        options.updateItem($node, data, originalIndex);
+    } else {
+        const str = options.renderItem(data, originalIndex, $node);
+        if (str) {
+            $node.html(str);
+        }
+    }
+}
+
+// 辅助方法：使用 renderItem 渲染节点（用于全新节点）
+Waterfallv2.prototype.renderUI = function ($node, data, dataId) {
+    const options = this.options;
+
+    if (!this.dataIdMap.has(dataId)) {
+        console.error('Waterfallv2: Invalid dataId in renderUI', dataId);
+        return;
+    }
+
+    // 实时获取数据在 options.data 中的当前索引
+    const originalIndex = options.data.indexOf(data);
+    const str = options.renderItem(data, originalIndex, $node);
+    if (str) {
+        $node.html(str);
+    }
+}
+
+
+
+Waterfallv2.prototype.updateData = async function (newData) {
+    const options = this.options;
+
+    // 步骤0: 为新数据中没有 dataId 的元素分配新 dataId（视为新增元素）
+    // 注意：这里只给缺失 dataId 的元素分配，已有 dataId 的元素保持不变
+    newData.forEach(item => {
+        if (item.dataId === undefined || item.dataId === null) {
+            item.dataId = 'pix_wf_' + (_globalDataIdCounter++);
+        }
+    });
+
+    // 构建新数据的 dataId Set，用于快速判断
+    const newDataIdSet = new Set(newData.map(item => item.dataId));
+    // 构建新数据的 dataId -> 数据对象 Map，用于快速查找
+    const newDataMap = new Map(newData.map(item => [item.dataId, item]));
+
+    // 步骤1: 找出需要删除的 dataId（旧数据有、新数据没有）
+    const toDeleteIds = [];
+    for (const dataId of this.dataIdMap.keys()) {
+        if (!newDataIdSet.has(dataId)) {
+            toDeleteIds.push(dataId);
+        }
+    }
+
+    // 步骤2: 找出需要更新的 dataId（新旧数据都有）
+    const toUpdateIds = [];
+    for (const item of newData) {
+        if (this.dataIdMap.has(item.dataId)) {
+            toUpdateIds.push(item.dataId);
+        }
+    }
+
+    // 步骤3: 找出需要新增的 dataId（新数据有、旧数据没有）
+    const toAddItems = [];
+    for (const item of newData) {
+        if (!this.dataIdMap.has(item.dataId)) {
+            toAddItems.push(item);
+        }
+    }
+
+    // 步骤4: 先同步更新 options.data 为新数据
+    options.data = newData;
+
+    // 步骤5: 执行删除操作（复用 removeCard 的内部逻辑，但不触发视图刷新）
+    for (const dataId of toDeleteIds) {
+        this._removeCardInternal(dataId);
+    }
+
+    // 步骤6: 执行更新操作（批量获取新高度，应用高度变化）
+    if (toUpdateIds.length > 0) {
+        // 只对已渲染的卡片进行高度更新
+        const renderedUpdateIds = toUpdateIds.filter(id => this.renderedDataIds.has(id));
+
+        if (renderedUpdateIds.length > 0) {
+            const newHeightsMap = await this.getBatchCardNewHeights(renderedUpdateIds, newData);
+
+            // 收集高度变化
+            const heightChanges = new Map();
+            for (const dataId of renderedUpdateIds) {
+                const oldHeight = this.getCardOldHeight(dataId);
+                const newHeight = newHeightsMap.get(dataId);
+                if (oldHeight !== newHeight) {
+                    heightChanges.set(dataId, {
+                        oldHeight,
+                        newHeight,
+                        heightDiff: newHeight - oldHeight
+                    });
+                }
+            }
+
+            // 使用累积差分算法更新每一列的布局
+            for (let i = 0; i < this.columnItems.length; i++) {
+                const column = this.columnItems[i];
+                let accumulatedDiff = 0;
+
+                for (let j = 0; j < column.children.length; j++) {
+                    const row = column.children[j];
+                    const dataId = row.dataId;
+
+                    if (accumulatedDiff !== 0) {
+                        row.top += accumulatedDiff;
+                        row.bottom += accumulatedDiff;
+                    }
+
+                    if (heightChanges.has(dataId)) {
+                        const change = heightChanges.get(dataId);
+                        accumulatedDiff += change.heightDiff;
+                        row.bottom += change.heightDiff;
+                    }
+                }
+
+                if (accumulatedDiff !== 0) {
+                    column.bottom += accumulatedDiff;
+                }
+            }
+        }
+    }
+
+    // 步骤7: 执行新增操作（为新增数据建立 dataIdMap 映射，等待 updateVisibleItems 时自动渲染）
+    for (const item of toAddItems) {
+        const dataId = item.dataId;
+        if (!this.dataIdMap.has(dataId)) {
+            this.dataIdMap.set(dataId, {
+                data: true,
+                layoutInfo: null
+            });
+        }
+    }
+
+    // 步骤8: 同步视图
+    // 修正 scrollTop：删除数据后，若当前滚动位置超过新的内容高度，则重置到顶部
+    // 否则 updateVisibleItems 会因为 scrollTop 过大而判断所有剩余卡片不在可视区域，导致位置不更新
+    const newMaxHeight = this.getMaxHeight();
+    if (this.scrollTop > newMaxHeight) {
+        this.scrollTop = 0;
+        const $scrollDom = options.scrollDom ? $(options.scrollDom) : $(options.container);
+        $scrollDom.scrollTop(0);
+    }
+    this.setScrollHeight();
+    this.updateVisibleItems(true);
+}
+
+/**
+ * 删除卡片的内部实现（不触发视图刷新，供 updateData 批量调用）
+ * @private
+ */
+Waterfallv2.prototype._removeCardInternal = function (dataId) {
+    const options = this.options;
+
+    if (!this.dataIdMap.has(dataId)) {
+        return;
+    }
+
+    // 找到该卡片所在列及其 row，计算被删除卡片的高度
+    let targetColumn = null;
+    let targetRowIndex = -1;
+    let removedHeight = 0;
+
+    for (let i = 0; i < this.columnItems.length; i++) {
+        const column = this.columnItems[i];
+        for (let j = 0; j < column.children.length; j++) {
+            const row = column.children[j];
+            if (row.dataId === dataId) {
+                targetColumn = column;
+                targetRowIndex = j;
+                removedHeight = row.bottom - row.top;
+                break;
+            }
+        }
+        if (targetColumn !== null) break;
+    }
+
+    if (targetColumn === null) {
+        // 卡片尚未渲染到布局中，只清理数据映射即可
+        this._cleanupCardData(dataId);
+        return;
+    }
+
+    // 回收被删除卡片的 DOM 节点
+    // 优先从 activeNodes 获取节点引用（虚拟化后 row.$node 可能已被复用给其他卡片）
+    const isSpecial = this.allReadyNodes.get(dataId) === null;
+    const $activeNode = this.activeNodes.get(dataId);
+
+    if ($activeNode && $activeNode.length) {
+        // 节点当前在可视区域，直接回收
+        $activeNode.css('transform', 'translateY(-9999px)');
+        if (!isSpecial) {
+            if (this.nodePool.indexOf($activeNode) === -1) {
+                this.nodePool.push($activeNode);
+            }
+        } else {
+            $activeNode.remove();
+        }
+    } else if (isSpecial) {
+        // 特殊节点不在 activeNodes 里，从 row.$node 获取并移除
+        const removedRow = targetColumn.children[targetRowIndex];
+        const $specialNode = removedRow.$node;
+        if ($specialNode && $specialNode.length) {
+            $specialNode.remove();
+        }
+    }
+    // 普通节点不在 activeNodes 里，说明已被回收到 nodePool，无需额外处理
+
+    // 从该列的 children 中移除该 row
+    targetColumn.children.splice(targetRowIndex, 1);
+
+    // 对该列中被删除卡片之后的所有 row，向上位移
+    // 后面还有卡片时：位移量 = removedHeight + rowGap（卡片高度 + 与下一张卡片的间距）
+    // 后面没有卡片时：位移量 = removedHeight（仅减去卡片高度，无需减 rowGap）
+    const hasFollowingCards = targetRowIndex < targetColumn.children.length;
+    const shiftAmount = hasFollowingCards ? (removedHeight + options.rowGap) : removedHeight;
+    for (let j = targetRowIndex; j < targetColumn.children.length; j++) {
+        const row = targetColumn.children[j];
+        row.top -= shiftAmount;
+        row.bottom -= shiftAmount;
+    }
+
+    // 更新该列的 bottom
+    if (targetColumn.children.length === 0) {
+        targetColumn.bottom = 0;
+    } else {
+        targetColumn.bottom -= shiftAmount;
+        if (targetColumn.bottom < 0) targetColumn.bottom = 0;
+    }
+
+    // 清理各种映射中的引用
+    this._cleanupCardData(dataId);
+}
+
+// 辅助方法：获取卡片的旧高度（从布局信息）
+Waterfallv2.prototype.getCardOldHeight = function (dataId) {
+    const dataInfo = this.dataIdMap.get(dataId);
+
+    if (!dataInfo) {
+        return 0;
+    }
+
+    if (!dataInfo.layoutInfo) {
+        return 0;
+    }
+
+    const row = dataInfo.layoutInfo;
+    return row.bottom - row.top;
+}
+
+// 辅助方法：获取特殊节点的 DOM 引用
+Waterfallv2.prototype.getSpecialNodeDOM = function (dataId) {
+    const dataInfo = this.dataIdMap.get(dataId);
+    if (dataInfo && dataInfo.layoutInfo && dataInfo.layoutInfo.$node) {
+        return dataInfo.layoutInfo.$node;
+    }
+    return null;
+}
+
+// 辅助方法：批量获取卡片的新高度（用于 updateData）
+Waterfallv2.prototype.getBatchCardNewHeights = async function (dataIds, newData) {
+    const options = this.options;
+    const $ = getEnv().$;
+    const $container = $(options.container);
+    const $viewport = $container.find('.Waterfallv2-list-viewport');
+
+    const cardInfos = new Map();
+
+    const borrowedNodes = [];
+    const tempNodesToDelete = [];
+
+    // 构建 dataId -> 数据对象 的快速查找 Map，避免多次 find 遍历
+    const newDataMap = new Map();
+    for (const item of newData) {
+        if (item.dataId != null) {
+            newDataMap.set(item.dataId, item);
+        }
+    }
+
+    // 第一步：优先处理所有可视区域节点（activeNodes）
+    for (let dataId of dataIds) {
+        if (this.activeNodes.has(dataId)) {
+            const $node = this.activeNodes.get(dataId);
+            // 通过 dataId 找到对应的数据对象
+            const data = newDataMap.get(dataId);
+
+            if (!data) {
+                // 新数据中找不到对应 dataId，跳过更新，保留旧高度
+                console.warn('Waterfallv2: getBatchCardNewHeights - dataId not found in newData:', dataId);
+                cardInfos.set(dataId, { $node: $node, needCleanup: false, cleanupType: null });
+                continue;
+            }
+
+            this.updateRenderUI($node, data, dataId);
+
+            cardInfos.set(dataId, {
+                $node: $node,
+                needCleanup: false,
+                cleanupType: null
+            });
+        }
+    }
+
+    // 第二步：处理所有非可视区域节点
+    for (let dataId of dataIds) {
+        if (this.activeNodes.has(dataId)) {
+            continue;
+        }
+
+        // 通过 dataId 找到对应的数据对象
+        const data = newDataMap.get(dataId);
+
+        if (!data) {
+            // 新数据中找不到对应 dataId，跳过更新，保留旧高度
+            console.warn('Waterfallv2: getBatchCardNewHeights - dataId not found in newData:', dataId);
+            cardInfos.set(dataId, { $node: null, needCleanup: false, cleanupType: 'notfound' });
+            continue;
+        }
+
+        if (this.allReadyNodes.has(dataId)) {
+            const $existingNode = this.allReadyNodes.get(dataId);
+
+            if ($existingNode === null) {
+                const $specialNode = this.getSpecialNodeDOM(dataId);
+
+                if ($specialNode) {
+                    this.updateRenderUI($specialNode, data, dataId);
+
+                    cardInfos.set(dataId, {
+                        $node: $specialNode,
+                        needCleanup: false,
+                        cleanupType: 'special'
+                    });
+                } else {
+                    console.warn('Waterfallv2: Special node DOM not found for dataId', dataId);
+                    cardInfos.set(dataId, {
+                        $node: null,
+                        needCleanup: false,
+                        cleanupType: 'special-notfound'
+                    });
+                }
+                continue;
+            }
+
+            let $node = getNodePoolPop(this.nodePool, this.activeNodes);
+
+            if ($node) {
+                borrowedNodes.push($node);
+
+                $node.css({
+                    'transform': 'translate(-9999px, -9999px)',
+                });
+
+                if (options.columns !== 1) {
+                    $node.width(this.columnWidth + 'px');
+                }
+
+                $node.attr('data-index', dataId);
+
+                this.updateRenderUI($node, data, dataId);
+
+                cardInfos.set(dataId, {
+                    $node: $node,
+                    needCleanup: false,
+                    cleanupType: 'borrowed'
+                });
+            } else {
+                $node = $(
+                    `<div class="waterfallv2-item"
+                          data-index="${dataId}"
+                          style="position: absolute; transform: translate(-9999px, -9999px);"
+                    >
+                     </div>`
+                );
+                $viewport.append($node);
+                tempNodesToDelete.push($node);
+
+                if (options.columns !== 1) {
+                    $node.width(this.columnWidth + 'px');
+                }
+
+                this.renderUI($node, data, dataId);
+
+                cardInfos.set(dataId, {
+                    $node: $node,
+                    needCleanup: false,
+                    cleanupType: 'temp'
+                });
+            }
+            continue;
+        }
+
+        cardInfos.set(dataId, {
+            $node: null,
+            needCleanup: false,
+            cleanupType: 'notfound'
+        });
+    }
+
+    // 第三步：在单个 requestAnimationFrame 中统一获取所有高度
+    return new Promise(resolve => {
+        requestAnimationFrame(() => {
+            const heightMap = new Map();
+
+            for (let [dataId, info] of cardInfos) {
+                if (info.$node) {
+                    heightMap.set(dataId, info.$node.height());
+                } else {
+                    heightMap.set(dataId, this.getCardOldHeight(dataId));
+                }
+            }
+
+            // 清理：归还借用的节点到节点池
+            for (let $node of borrowedNodes) {
+                $node.css('transform', 'translateY(-9999px)');
+                this.nodePool.push($node);
+            }
+
+            // 清理：删除临时节点
+            for (let $node of tempNodesToDelete) {
+                $node.remove();
+            }
+
+            resolve(heightMap);
+        });
+    });
+}
+
+// 辅助方法：获取卡片的新高度（通过渲染）- 用于单卡片更新
+Waterfallv2.prototype.getCardNewHeight = async function (dataId, data) {
+    const options = this.options;
+    const $ = getEnv().$;
+
+    // 情况1: 卡片在可视区域（activeNodes）
+    if (this.activeNodes.has(dataId)) {
+        const $node = this.activeNodes.get(dataId);
+
+        this.updateRenderUI($node, data, dataId);
+
+        return new Promise(resolve => {
+            window.requestAnimationFrame(() => {
+                resolve($node.height());
+            });
+        });
+    }
+
+    // 情况2: 卡片不在可视区域（allReadyNodes）
+    if (this.allReadyNodes.has(dataId)) {
+        const $existingNode = this.allReadyNodes.get(dataId);
+
+        if ($existingNode === null) {
+            const $specialNode = this.getSpecialNodeDOM(dataId);
+
+            if ($specialNode) {
+                this.updateRenderUI($specialNode, data, dataId);
+
+                return new Promise(resolve => {
+                    window.requestAnimationFrame(() => {
+                        resolve($specialNode.height());
+                    });
+                });
+            }
+
+            console.warn('Waterfallv2: Special node DOM not found for dataId', dataId);
+            return this.getCardOldHeight(dataId);
+        }
+
+        const $container = $(options.container);
+        const $viewport = $container.find('.Waterfallv2-list-viewport');
+
+        let $node = getNodePoolPop(this.nodePool, this.activeNodes);
+        let isBorrowed = false;
+
+        if ($node) {
+            isBorrowed = true;
+
+            $node.css({
+                'transform': 'translate(-9999px, -9999px)',
+            });
+
+            $node.attr('data-index', dataId);
+
+            if (options.columns !== 1) {
+                $node.width(this.columnWidth + 'px');
+            }
+
+            this.updateRenderUI($node, data, dataId);
+        } else {
+            $node = $(
+                `<div class="waterfallv2-item"
+                      data-index="${dataId}"
+                      style="position: absolute; transform: translate(-9999px, -9999px);"
+                >
+                 </div>`
+            );
+            $viewport.append($node);
+
+            if (options.columns !== 1) {
+                $node.width(this.columnWidth + 'px');
+            }
+
+            this.renderUI($node, data, dataId);
+        }
+
+        return new Promise(resolve => {
+            window.requestAnimationFrame(() => {
+                const newHeight = $node.height();
+
+                if (isBorrowed) {
+                    $node.css('transform', 'translateY(-9999px)');
+                    this.nodePool.push($node);
+                } else {
+                    $node.remove();
+                }
+
+                resolve(newHeight);
+            });
+        });
+    }
+
+    // 情况3: 未找到节点，返回旧高度
+    return this.getCardOldHeight(dataId);
+}
+
+// 某个数据进行了UI变更，触发高度重新绘制
+/**
+ * @param {string} dataId - 要更新的卡片的 dataId
+ * @param {object} data - 更新后的数据对象
+ */
+Waterfallv2.prototype.updateCard = async function (dataId, data) {
+    // 1. 校验参数
+    if (typeof dataId !== 'string') {
+        console.warn('Waterfallv2: updateCard - dataId must be a string');
+        return;
+    }
+
+    if (!this.renderedDataIds.has(dataId)) {
+        console.log('Waterfallv2: dataId not rendered yet', dataId);
+        return;
+    }
+
+    // 2. 同步更新 options.data 中对应的数据
+    const options = this.options;
+    if (data !== undefined) {
+        const index = options.data.findIndex(item => item.dataId === dataId);
+        if (index !== -1) {
+            options.data[index] = Object.assign({}, options.data[index], data);
+        }
+    }
+
+    const itemData = options.data.find(item => item.dataId === dataId);
+
+    const oldHeight = this.getCardOldHeight(dataId);
+
+    const newHeight = await this.getCardNewHeight(dataId, itemData);
+
+    this.applyHeightChange(dataId, oldHeight, newHeight);
+}
+
+// 应用高度变化到布局
+Waterfallv2.prototype.applyHeightChange = function (dataId, oldHeight, newHeight) {
+    const minus = newHeight - oldHeight;
+
+    if (minus === 0) {
+        console.log('Waterfallv2: Card height unchanged for dataId', dataId);
+        return;
+    }
+
+    console.log('Waterfallv2: Card height changed for dataId', dataId, 'from', oldHeight, 'to', newHeight, 'diff', minus);
+
+    let needUpdate = false;
+    const columnItems = this.columnItems;
+
+    for (let i = 0; i < columnItems.length; i++) {
+        const column = columnItems[i];
+        let foundCard = false;
+
+        for (let j = 0; j < column.children.length; j++) {
+            const row = column.children[j];
+
+            if (row.dataId === dataId) {
+                foundCard = true;
+                needUpdate = true;
+
+                row.bottom += minus;
+
+            } else if (foundCard) {
+                row.top += minus;
+                row.bottom += minus;
+            }
+        }
+
+        if (foundCard) {
+            column.bottom += minus;
+            break;
+        }
+    }
+
+    if (needUpdate) {
+        this.setScrollHeight();
+        this.updateVisibleItems(true);
+    }
+}
+
+/**
+ * 删除某个卡片，并动态重新位移被删除卡片所在列的其他卡片位置
+ * @param {string} dataId - 要删除的卡片的 dataId
+ */
+Waterfallv2.prototype.removeCard = function (dataId) {
+    const options = this.options;
+
+    // 1. 校验参数
+    if (typeof dataId !== 'string') {
+        console.warn('Waterfallv2: removeCard - dataId must be a string');
+        return;
+    }
+
+    // 2. 通过 dataId 查找对应的数据对象
+    const targetData = options.data.find(item => item.dataId === dataId) || null;
+
+    if (!this.dataIdMap.has(dataId)) {
+        console.warn('Waterfallv2: removeCard - dataId not in dataIdMap', dataId);
+        return;
+    }
+
+    // 3. 从 options.data 中移除该数据（通过对象引用精确定位）
+    const spliceIndex = options.data.indexOf(targetData);
+    if (spliceIndex !== -1) {
+        options.data.splice(spliceIndex, 1);
+    }
+
+    // 3. 找到该卡片所在列及其 row，计算被删除卡片的高度
+    let targetColumn = null;
+    let targetRowIndex = -1;
+    let removedHeight = 0;
+
+    for (let i = 0; i < this.columnItems.length; i++) {
+        const column = this.columnItems[i];
+        for (let j = 0; j < column.children.length; j++) {
+            const row = column.children[j];
+            if (row.dataId === dataId) {
+                targetColumn = column;
+                targetRowIndex = j;
+                removedHeight = row.bottom - row.top;
+                break;
+            }
+        }
+        if (targetColumn !== null) break;
+    }
+
+    if (targetColumn === null) {
+        // 卡片尚未渲染到布局中，只清理数据映射即可
+        console.log('Waterfallv2: removeCard - card not yet laid out, cleaning up data only', dataId);
+        this._cleanupCardData(dataId);
+        return;
+    }
+
+    // 4. 回收被删除卡片的 DOM 节点到节点池
+    const removedRow = targetColumn.children[targetRowIndex];
+    const $removedNode = removedRow.$node;
+
+    if ($removedNode && $removedNode.length) {
+        // 移出可视区
+        $removedNode.css('transform', 'translateY(-9999px)');
+        // 放入节点池（如果不是特殊节点）
+        const isSpecial = this.allReadyNodes.get(dataId) === null;
+        if (!isSpecial) {
+            if (this.nodePool.indexOf($removedNode) === -1) {
+                this.nodePool.push($removedNode);
+            }
+        } else {
+            // 特殊节点直接从 DOM 中移除
+            $removedNode.remove();
+        }
+    }
+
+    // 5. 从该列的 children 中移除该 row
+    targetColumn.children.splice(targetRowIndex, 1);
+
+    // 6. 对该列中被删除卡片之后的所有 row，向上位移
+    //    后面还有卡片时：位移量 = removedHeight + rowGap（卡片高度 + 与下一张卡片的间距）
+    //    后面没有卡片时：位移量 = removedHeight（仅减去卡片高度，无需减 rowGap）
+    const hasFollowingCards = targetRowIndex < targetColumn.children.length;
+    const shiftAmount = hasFollowingCards ? (removedHeight + options.rowGap) : removedHeight;
+
+    for (let j = targetRowIndex; j < targetColumn.children.length; j++) {
+        const row = targetColumn.children[j];
+        row.top -= shiftAmount;
+        row.bottom -= shiftAmount;
+    }
+
+    // 7. 更新该列的 bottom
+    if (targetColumn.children.length === 0) {
+        targetColumn.bottom = 0;
+    } else {
+        targetColumn.bottom -= shiftAmount;
+        // 确保 bottom 不小于 0
+        if (targetColumn.bottom < 0) targetColumn.bottom = 0;
+    }
+
+    // 8. 清理各种映射中的引用
+    this._cleanupCardData(dataId);
+
+    // 9. 刷新视图（dataId 是稳定的唯一标识，无需重建映射）
+    this.setScrollHeight();
+    this.updateVisibleItems(true);
+}
+
+/**
+ * 清理被删除卡片在各映射中的引用
+ * @private
+ */
+Waterfallv2.prototype._cleanupCardData = function (dataId) {
+    // 从 activeNodes 中移除
+    this.activeNodes.delete(dataId);
+
+    // 从 allReadyNodes 中移除
+    this.allReadyNodes.delete(dataId);
+
+    // 从 renderedDataIds 中移除
+    this.renderedDataIds.delete(dataId);
+
+    // 从 dataIdMap 中移除
+    this.dataIdMap.delete(dataId);
+}
+
+// _rebuildDataIdMap 已不再需要：
+// dataId 现在是数据元素自身携带的稳定唯一标识，删除某条数据后其他数据的 dataId 不变，无需重建映射。
+
+
+// 展示loading的回调函数
+Waterfallv2.prototype.showLoading = function (callback = null) {
+    this.isShowLoading = true;
+    const options = this.options;
+    let $node = null
+    if (this.$loadingNode) {
+        let loadingTop = this.getMaxHeight() + options.rowGap
+        this.$loadingNode.css('transform', `translate(0px,${loadingTop}px)`);
+        $node = this.$loadingNode;
+    }
+
+    if (callback) callback($node)
+    // 延迟到下一帧再计算高度，确保 loadingNode 已完成渲染，height() 返回准确值
+    window.requestAnimationFrame(() => {
+        this.setScrollHeight();
+    });
+}
+
+// 隐藏loading的回调函数
+Waterfallv2.prototype.hideLoading = function (callback = null) {
+    this.isShowLoading = false;
+    const options = this.options;
+    let $node = null
+    if (this.$loadingNode) {
+        this.$loadingNode.css('transform', `translate(0px,-99999px)`);
+        $node = this.$loadingNode
+    }
+
+    if (callback) callback($node)
+    // 延迟到下一帧再计算高度，确保 loadingNode 已完成位移渲染
+    window.requestAnimationFrame(() => {
+        this.setScrollHeight();
+    });
+}
+
+// 设置滚动条列表的高度
+Waterfallv2.prototype.setScrollHeight = function () {
+    const options = this.options;
+    const $container = $(options.container);
+    let h = this.getMaxHeight();
+    if (this.isShowLoading === true) {
+        if (this.$loadingNode) {
+            h += options.rowGap + this.$loadingNode.height();
+        }
+    }
+    h += options.marginBottom;
+    $container.find('.waterfallv2-list-scroll').css('height', h + 'px');
+}
+
+// 销毁自己
+Waterfallv2.prototype.destroy = function () {
+    const options = this.options;
+    const $container = $(options.container);
+    $container.html('');
+    this.activeNodes.clear();
+    this.allReadyNodes.clear();
+    this.dataIdMap.clear();
+    this.renderedDataIds.clear();
+    this.nodePool = [];
+    this.columnItems = [];
+    this.columns = 0;
+    this.columnWidth = 0;
+    this.renderIndex = 0;
+    this.scrollTop = 0;
+    this.isShowLoading = false;
+    this.$loadingNode = null;
+    this.$scrollDom = null;
+}
+
+function createDefaultRow({ top, left }) {
+    return {
+        top,
+        left,
+        bottom: 0,
+        $node: null,
+        dataId: -1 // 新方案：使用dataId替代renderIndex
+    }
+}
+
+
+function getBottomByColumn(column) {
+    if (column.children.length === 0) {
+        return 0;
+    }
+    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;
+}