tencent.jquery.pix.component 1.0.77 → 1.0.79

package/components/waterfall/waterfall.js

@@ -1,878 +1,1254 @@
-import "./waterfall.scss"
-import { getEnv } from "../config.js";
-import { remToPx } from "../../utils/utils.js";
-
-let $ = null;
-
-// 默认配置
-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="waterfall-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 Waterfall(optionsInput = {}) {
-    $ = getEnv().$;
-
-    this.optionsInput = optionsInput
-
-    this.init();
-}
-
-
-Waterfall.prototype.init = function (optionsMain = null) {
-    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(); // 数据ID -> 布局信息映射
-    this.nextDataId = 0; // 下一个数据ID
-    this.renderedDataIds = new Set(); // 已渲染的数据ID集合
-
-    this.$loadingNode = null;
-
-    this.isShowLoading = false;  // 是否展示loading
-
-
-    // 间隔字符串转数字
-    if (options.columnGap.constructor === String) {
-        // 如果是rem单位，则需要计算
-        if (options.columnGap.indexOf('rem') > -1) {
-            options.columnGap = remToPx(options.columnGap);
-        } else {
-            options.columnGap = parseFloat(options.columnGap);
-        }
-    }
-    if (options.rowGap.constructor === String) {
-        // 如果是rem单位，则需要计算
-        if (options.rowGap.indexOf('rem') > -1) {
-            options.rowGap = remToPx(options.rowGap);
-        } else {
-            options.rowGap = parseFloat(options.rowGap);
-        }
-    }
-    if (options.bufferHeight.constructor === String) {
-        // 如果是rem单位，则需要计算
-        if (options.bufferHeight.indexOf('rem') > -1) {
-            options.bufferHeight = remToPx(options.bufferHeight);
-        } else {
-            options.bufferHeight = parseFloat(options.bufferHeight);
-        }
-    }
-    if (options.marginTop.constructor === String) {
-        // 如果是rem单位，则需要计算
-        if (options.marginTop.indexOf('rem') > -1) {
-            options.marginTop = remToPx(options.marginTop);
-        } else {
-            options.marginTop = parseFloat(options.marginTop);
-        }
-    }
-    if (options.marginBottom.constructor === String) {
-        // 如果是rem单位，则需要计算
-        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;  // 渲染索引（保留兼容性）
-
-
-
-    // 新方案：初始化数据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 // 将在布局时填充
-        });
-    });
-
-    $container.html(`
-        <div class="waterfall-list-scroll" style="">
-          <div class="waterfall-list-viewport"></div>
-        </div>
-      `);
-
-
-
-    // 如果有定义loading函数  那么创建一个loading节点元素
-    console.log('options.createLoading', options.createLoading)
-    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);
-    }
-
-    // 绑定滚动事件（节流处理）
-    $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 强制更新渲染
-Waterfall.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;
-    // console.log('startTop', startTop)
-    // console.log('endTop', endTop)
-
-    // 进行可见区域的渲染更新
-    this.updateCardsInView({
-        start: startTop,
-        end: endTop,
-        force
-    });
-
-}
-
-// 新增卡片
-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="${dataId}"
-              style="position: absolute;transform:translate(${left}px,${top}px);"
-        >
-         </div> `
-    );
-
-    $viewport.append($card);
-
-    const str = options.renderItem(data, dataInfo.originalIndex, $card);
-
-    if (str) {
-        $card.html(str);
-    }
-
-    this.renderedDataIds.add(dataId);
-
-    if (options.columns !== 1) {
-        $card.width(this.columnWidth + 'px');
-    }
-
-
-    return $card;
-}
-
-// 获取指定高度下的卡片索引
-Waterfall.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('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;
-            }
-
-            // 在可视区域内 进行有关卡片的操作
-            const bool = row.top <= endNum && row.bottom >= startNum;
-            if (bool) {
-                // 理论上什么都不动，因为卡片的位置不会变
-                const $card = this.activeNodes.get(dataId);
-
-                let $node = null;
-
-                // 遍历当前的节点是否被占用，如果被占用的话，就得要从nodePool中取一个
-                let bool = true;
-                if ($card) {
-                    bool = hasNodeInActives(newActiveNodes, $card)
-                }
-                // 如果卡片已经在DOM中，则不用更新位置
-                if (bool === false) {
-                    $node = $card;
-                    this.activeNodes.delete(dataId);
-                    // 如果是强更，这里才会采取更新
-                    if (force) {
-                        this.updateRenderUI($node, data, dataId);
-                    }
-
-                } else {
-                    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 {
-                        // 卡片不在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);
-                }
-
-                // console.log('302-row', row.dataId, dataInfo);
-            }
-        }
-    }
-
-    // 阶段2：处理不活跃节点
-    this.activeNodes.forEach($node => {
-        $node.css('transform', `translateY(-9999px)`);// 移出可视区域
-        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++) {
-        const column = this.columnItems[i]
-
-        // 获取每组元素列表的最后一个bottom值
-        maxHeight = Math.max(maxHeight, column.bottom);
-
-    }
-    return maxHeight;
-}
-
-Waterfall.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;
-        }
-        // 获取每组元素列表的最后一个bottom值
-        minHeight = Math.min(minHeight, column.bottom);
-
-    }
-    return minHeight;
-}
-
-Waterfall.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) {
-            // 获取每组元素列表的最后一个bottom值
-            minHeight = column.bottom;
-            mimHeightColumn = column;
-            index = i;
-        }
-
-    }
-
-    if (minHeight === 0 && index > -1) {
-        if (startPoints.length > index) {
-            // 设置一下起始点的初始化
-            mimHeightColumn.bottom = startPoints[index];
-        }
-    }
-
-    return mimHeightColumn;
-}
-
-// 创建卡片
-Waterfall.prototype.createCards = function ({ end, dataId = -1 }, callback) {
-    const self = this;
-    const options = this.options;
-
-    return new Promise((resolve) => {
-        // 新方案：获取下一个未渲染的数据ID
-        let nextDataId = null;
-        for (let [dataId, dataInfo] of this.dataIdMap) {
-            if (!this.renderedDataIds.has(dataId)) {
-                nextDataId = dataId;
-                break;
-            }
-        }
-
-
-        // 如果没有更多数据需要渲染
-        if (nextDataId === null) {
-            this.setScrollHeight();
-            return resolve();
-        }
-
-        const dataInfo = this.dataIdMap.get(nextDataId);
-        if (!dataInfo || !dataInfo.data) {
-            console.warn('Waterfall: Invalid data for dataId', nextDataId);
-            return resolve();
-        }
-
-        if (this.renderIndex >= options.data.length) {
-            this.setScrollHeight();
-            return resolve();
-        }
-
-        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);
-
-        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; // 使用dataId替代renderIndex
-        if (dataId !== -1) {
-            row.dataId = dataId;
-        }
-
-        if (specialNode === false) {
-            // 把新增的卡片放进 activeNodes 当成活跃节点元素，那么是 可以动态使用的
-            this.activeNodes.set(nextDataId, $card);
-
-            this.allReadyNodes.set(nextDataId, $card);
-        } else {
-            // 如果是特殊的，这里不要记录了 
-            this.allReadyNodes.set(nextDataId, null);
-        }
-
-        this.renderedDataIds.add(nextDataId);
-
-        // setTimeout(() => {
-        //window.requestAnimationFrame(() => {
-
-        column.bottom = top + $card.height();
-
-        column.children.push(row);
-        row.bottom = column.bottom;
-
-        // 检查是否需要继续创建卡片
-        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();
-            }
-        }
-        //});
-        // }, 42);
-    });
-
-}
-
-
-Waterfall.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;
-}
-
-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, dataInfo.originalIndex)
-    } else {
-        const str = options.renderItem(data, dataInfo.originalIndex, $node);
-        if (str) {
-            $node.html(str);
-        }
-    }
-}
-
-
-
-Waterfall.prototype.updateData = async function (newData) {
-    const options = this.options;
-    options.data = newData;
-
-    // 新方案：重新建立数据ID映射
-    //this.dataIdMap.clear();
-    //this.renderedDataIds.clear();
-    //this.nextDataId = 0;
-
-    // 为每个数据项分配唯一ID
-    let bool = true
-    let count = options.data.length - 1;
-    let index = 0;
-
-    while (bool) {
-        if (index > count) {
-            bool = false
-            this.updateVisibleItems(true); // 强制更新渲染
-            break;
-        }
-
-        const dataId = index;
-        this.dataIdMap.set(dataId, {
-            data: true,
-            originalIndex: dataId,
-            layoutInfo: null
-        });
-
-        await this.createCards({ end: 0, dataId })
-
-        index += 1;
-
-    }
-    // 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); // 强制更新渲染
-
-
-}
-
-// 某个数据进行了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) {
-    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;
-        // window.requestAnimationFrame(() => {
-        //     setTimeout(() => {
-        //         this.$scrollDom.scrollTop(loadingTop + this.$loadingNode.height());
-        //     });
-        // });
-    }
-
-    if (callback) callback($node)
-    this.setScrollHeight();
-}
-
-// 隐藏loading的回调函数
-Waterfall.prototype.hideLoading = function (callback = null) {
-    this.isShowLoading = false;
-    const options = this.options;
-    let $node = null
-    if (this.$loadingNode) {
-        let h1 = this.getMaxHeight() + options.marginBottom
-        this.$loadingNode.css('transform', `translate(0px,-99999px)`);
-        //如果要设置高度，那么这里判断一下当前是否正在做updata  一般这里被调用时，数据已经读到，在updata的同一时间调用了该函数
-        // 如果两个时刻高度是一致的 那么数据就是一致的 这里重新设置回来高度即可
-        window.requestAnimationFrame(() => {
-            this.setScrollHeight();
-        })
-        $node = this.$loadingNode
-    }
-
-    if (callback) callback($node)
-    this.setScrollHeight();
-}
-
-// 设置滚动条列表的高度
-Waterfall.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('.waterfall-list-scroll').css('height', h + 'px');
-}
-
-// 销毁自己
-Waterfall.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;
-}
-
+import { remToPx } from "../../utils/utils.js";
+import { getEnv } from "../config.js";
+import "./waterfall.scss";
+
+let $ = null;
+
+// 默认配置
+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="waterfall-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 Waterfall(optionsInput = {}) {
+    $ = getEnv().$;
+
+    this.optionsInput = optionsInput
+
+    this.init();
+}
+
+
+Waterfall.prototype.init = function (optionsMain = null) {
+    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(); // 数据ID -> 布局信息映射
+    this.nextDataId = 0; // 下一个数据ID
+    this.renderedDataIds = new Set(); // 已渲染的数据ID集合
+
+    this.$loadingNode = null;
+
+    this.isShowLoading = false;  // 是否展示loading
+
+
+    // 间隔字符串转数字
+    if (options.columnGap.constructor === String) {
+        // 如果是rem单位，则需要计算
+        if (options.columnGap.indexOf('rem') > -1) {
+            options.columnGap = remToPx(options.columnGap);
+        } else {
+            options.columnGap = parseFloat(options.columnGap);
+        }
+    }
+    if (options.rowGap.constructor === String) {
+        // 如果是rem单位，则需要计算
+        if (options.rowGap.indexOf('rem') > -1) {
+            options.rowGap = remToPx(options.rowGap);
+        } else {
+            options.rowGap = parseFloat(options.rowGap);
+        }
+    }
+    if (options.bufferHeight.constructor === String) {
+        // 如果是rem单位，则需要计算
+        if (options.bufferHeight.indexOf('rem') > -1) {
+            options.bufferHeight = remToPx(options.bufferHeight);
+        } else {
+            options.bufferHeight = parseFloat(options.bufferHeight);
+        }
+    }
+    if (options.marginTop.constructor === String) {
+        // 如果是rem单位，则需要计算
+        if (options.marginTop.indexOf('rem') > -1) {
+            options.marginTop = remToPx(options.marginTop);
+        } else {
+            options.marginTop = parseFloat(options.marginTop);
+        }
+    }
+    if (options.marginBottom.constructor === String) {
+        // 如果是rem单位，则需要计算
+        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;  // 渲染索引（保留兼容性）
+
+
+
+    // 新方案：初始化数据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 // 将在布局时填充
+        });
+    });
+
+    $container.html(`
+        <div class="waterfall-list-scroll" style="">
+          <div class="waterfall-list-viewport"></div>
+        </div>
+      `);
+
+
+
+    // 如果有定义loading函数  那么创建一个loading节点元素
+    console.log('options.createLoading', options.createLoading)
+    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);
+    }
+
+    // 绑定滚动事件（节流处理）
+    $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 强制更新渲染
+Waterfall.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;
+    // console.log('startTop', startTop)
+    // console.log('endTop', endTop)
+
+    // 进行可见区域的渲染更新
+    this.updateCardsInView({
+        start: startTop,
+        end: endTop,
+        force
+    });
+
+}
+
+// 新增卡片
+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="${dataId}"
+              style="position: absolute;transform:translate(${left}px,${top}px);"
+        >
+         </div> `
+    );
+
+    $viewport.append($card);
+
+    const str = options.renderItem(data, dataInfo.originalIndex, $card);
+
+    if (str) {
+        $card.html(str);
+    }
+
+    this.renderedDataIds.add(dataId);
+
+    if (options.columns !== 1) {
+        $card.width(this.columnWidth + 'px');
+    }
+
+
+    return $card;
+}
+
+// 获取指定高度下的卡片索引
+Waterfall.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('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) {
+                // 特殊节点：只更新位置，不参与复用逻辑
+                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('Waterfall: 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;
+
+                // 遍历当前的节点是否被占用，如果被占用的话，就得要从nodePool中取一个
+                let bool = true;
+                if ($card) {
+                    bool = hasNodeInActives(newActiveNodes, $card)
+                }
+                // 如果卡片已经在DOM中，则不用更新位置
+                if (bool === false) {
+                    $node = $card;
+                    this.activeNodes.delete(dataId);
+                    // 如果是强更，这里才会采取更新
+                    if (force) {
+                        this.updateRenderUI($node, data, dataId);
+                    }
+
+                } else {
+                    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 {
+                        // 卡片不在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);
+                }
+
+                // console.log('302-row', row.dataId, dataInfo);
+            }
+        }
+    }
+
+    // 阶段2：处理不活跃节点
+    this.activeNodes.forEach($node => {
+        $node.css('transform', `translateY(-9999px)`);// 移出可视区域
+        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++) {
+        const column = this.columnItems[i]
+
+        // 获取每组元素列表的最后一个bottom值
+        maxHeight = Math.max(maxHeight, column.bottom);
+
+    }
+    return maxHeight;
+}
+
+Waterfall.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;
+        }
+        // 获取每组元素列表的最后一个bottom值
+        minHeight = Math.min(minHeight, column.bottom);
+
+    }
+    return minHeight;
+}
+
+Waterfall.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) {
+            // 获取每组元素列表的最后一个bottom值
+            minHeight = column.bottom;
+            mimHeightColumn = column;
+            index = i;
+        }
+
+    }
+
+    if (minHeight === 0 && index > -1) {
+        if (startPoints.length > index) {
+            // 设置一下起始点的初始化
+            mimHeightColumn.bottom = startPoints[index];
+        }
+    }
+
+    return mimHeightColumn;
+}
+
+// 创建卡片
+Waterfall.prototype.createCards = function ({ end, dataId = -1 }, callback) {
+    const self = this;
+    const options = this.options;
+
+    return new Promise((resolve) => {
+        // 新方案：获取下一个未渲染的数据ID
+        let nextDataId = null;
+        for (let [dataId, dataInfo] of this.dataIdMap) {
+            if (!this.renderedDataIds.has(dataId)) {
+                nextDataId = dataId;
+                break;
+            }
+        }
+
+
+        // 如果没有更多数据需要渲染
+        if (nextDataId === null) {
+            this.setScrollHeight();
+            return resolve();
+        }
+
+        const dataInfo = this.dataIdMap.get(nextDataId);
+        if (!dataInfo || !dataInfo.data) {
+            console.warn('Waterfall: Invalid data for dataId', nextDataId);
+            return resolve();
+        }
+
+        if (this.renderIndex >= options.data.length) {
+            this.setScrollHeight();
+            return resolve();
+        }
+
+        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);
+
+        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; // 使用dataId替代renderIndex
+        if (dataId !== -1) {
+            row.dataId = dataId;
+        }
+
+        if (specialNode === false) {
+            // 把新增的卡片放进 activeNodes 当成活跃节点元素，那么是 可以动态使用的
+            this.activeNodes.set(nextDataId, $card);
+
+            this.allReadyNodes.set(nextDataId, $card);
+        } else {
+            // 如果是特殊的，这里不要记录了 
+            this.allReadyNodes.set(nextDataId, null);
+        }
+
+        this.renderedDataIds.add(nextDataId);
+
+        // setTimeout(() => {
+        //window.requestAnimationFrame(() => {
+
+        column.bottom = top + $card.height();
+
+        column.children.push(row);
+        row.bottom = column.bottom;
+
+        // 建立 dataIdMap -> row 的引用，用于快速访问布局信息
+        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();
+            }
+        }
+        //});
+        // }, 42);
+    });
+
+}
+
+
+Waterfall.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;
+}
+
+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, dataInfo.originalIndex)
+    } else {
+        const str = options.renderItem(data, dataInfo.originalIndex, $node);
+        if (str) {
+            $node.html(str);
+        }
+    }
+}
+
+// 辅助方法：使用 renderItem 渲染节点（用于全新节点）
+Waterfall.prototype.renderUI = function ($node, data, dataId) {
+    const options = this.options;
+
+    // 新方案：基于数据ID的数据验证
+    if (!this.dataIdMap.has(dataId)) {
+        console.error('Waterfall: Invalid dataId in renderUI', dataId);
+        return;
+    }
+
+    const dataInfo = this.dataIdMap.get(dataId);
+    if (!dataInfo || !dataInfo.data) {
+        console.warn('Waterfall: Empty data for dataId', dataId);
+    }
+
+    // 始终使用 renderItem，因为这是全新节点
+    const str = options.renderItem(data, dataInfo.originalIndex, $node);
+    if (str) {
+        $node.html(str);
+    }
+}
+
+
+
+Waterfall.prototype.updateData = async function (newData) {
+    const options = this.options;
+    options.data = newData;
+
+    // 步骤1: 批量获取所有卡片的新高度（只需一次 requestAnimationFrame）
+    const dataIds = this.renderedDataIds;
+    const newHeightsMap = await this.getBatchCardNewHeights(dataIds, newData);
+
+    // 步骤2: 收集高度变化
+    const heightChanges = new Map(); // dataId -> {oldHeight, newHeight, heightDiff}
+
+    for (let dataId of dataIds) {
+        const oldHeight = this.getCardOldHeight(dataId);
+        const newHeight = newHeightsMap.get(dataId);
+
+        if (oldHeight !== newHeight) {
+            heightChanges.set(dataId, {
+                oldHeight,
+                newHeight,
+                heightDiff: newHeight - oldHeight
+            });
+        }
+    }
+
+    // 步骤3: 使用累积差分算法更新每一列的布局
+    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;
+                // 更新当前卡片的 bottom
+                row.bottom += change.heightDiff;
+            }
+        }
+
+        // 更新列的总高度
+        if (accumulatedDiff !== 0) {
+            column.bottom += accumulatedDiff;
+        }
+    }
+
+    // 步骤4: 同步视图
+    this.setScrollHeight();
+    this.updateVisibleItems(true); // 这里会处理内容更新和DOM位置同步
+}
+
+// 辅助方法：获取卡片的旧高度（从布局信息）
+Waterfall.prototype.getCardOldHeight = function(dataId) {
+    const dataInfo = this.dataIdMap.get(dataId);
+
+    if (!dataInfo) {
+        // dataId 不存在
+        return 0;
+    }
+
+    if (!dataInfo.layoutInfo) {
+        // 布局信息未初始化（卡片还未创建）
+        return 0;
+    }
+
+    const row = dataInfo.layoutInfo;
+    return row.bottom - row.top;
+}
+
+// 辅助方法：获取特殊节点的 DOM 引用
+Waterfall.prototype.getSpecialNodeDOM = function(dataId) {
+    const dataInfo = this.dataIdMap.get(dataId);
+    if (dataInfo && dataInfo.layoutInfo && dataInfo.layoutInfo.$node) {
+        return dataInfo.layoutInfo.$node;
+    }
+    return null;
+}
+
+// 辅助方法：批量获取卡片的新高度（用于 updateData）
+Waterfall.prototype.getBatchCardNewHeights = async function(dataIds, newData) {
+    const options = this.options;
+    const $ = getEnv().$;
+    const $container = $(options.container);
+    const $viewport = $container.find('.waterfall-list-viewport');
+
+    // 用于记录每个卡片的信息
+    const cardInfos = new Map(); // dataId -> { $node, needCleanup, cleanupType }
+
+    // 记录从节点池借用的节点，需要在完成后归还
+    const borrowedNodes = [];
+    // 记录新创建的临时节点，需要在完成后删除
+    const tempNodesToDelete = [];
+
+    // 第一步：优先处理所有可视区域节点（activeNodes）
+    for (let dataId of dataIds) {
+        if (this.activeNodes.has(dataId)) {
+            const $node = this.activeNodes.get(dataId);
+            const data = newData[dataId];
+
+            // 重新渲染内容
+            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;
+        }
+
+        const data = newData[dataId];
+
+        // 情况1: 卡片在 allReadyNodes 中
+        if (this.allReadyNodes.has(dataId)) {
+            const $existingNode = this.allReadyNodes.get(dataId);
+
+            // 特殊节点（null）：通过 layoutInfo 获取 DOM 引用
+            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 {
+                    // 无法获取特殊节点DOM，使用旧高度
+                    console.warn('Waterfall: Special node DOM not found for dataId', dataId);
+                    cardInfos.set(dataId, {
+                        $node: null,
+                        needCleanup: false,
+                        cleanupType: 'special-notfound'
+                    });
+                }
+                continue;
+            }
+
+            // 情况2: 普通节点 - 从节点池获取或创建临时节点
+            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');
+                }
+
+                // 使用 updateRenderUI（节点池的节点已有结构）
+                this.updateRenderUI($node, data, dataId);
+
+                cardInfos.set(dataId, {
+                    $node: $node,
+                    needCleanup: false,
+                    cleanupType: 'borrowed'
+                });
+            } else {
+                // 节点池空了，创建临时节点
+                $node = $(
+                    `<div class="waterfall-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');
+                }
+
+                // 使用 renderUI（临时节点是全新的）
+                this.renderUI($node, data, dataId);
+
+                cardInfos.set(dataId, {
+                    $node: $node,
+                    needCleanup: false,
+                    cleanupType: 'temp'
+                });
+            }
+            continue;
+        }
+
+        // 情况3: 未找到节点，标记为使用旧高度
+        cardInfos.set(dataId, {
+            $node: null,
+            needCleanup: false,
+            cleanupType: 'notfound'
+        });
+    }
+
+    // 第三步：在单个 requestAnimationFrame 中统一获取所有高度
+    return new Promise(resolve => {
+        window.requestAnimationFrame(() => {
+            const heightMap = new Map(); // dataId -> newHeight
+
+            for (let [dataId, info] of cardInfos) {
+                if (info.$node) {
+                    // 从DOM获取高度
+                    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);
+        });
+    });
+}
+
+// 辅助方法：获取卡片的新高度（通过渲染）- 用于单卡片更新
+Waterfall.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);
+
+        // 等待DOM更新
+        return new Promise(resolve => {
+            window.requestAnimationFrame(() => {
+                resolve($node.height());
+            });
+        });
+    }
+
+    // 情况2: 卡片不在可视区域（allReadyNodes）
+    if (this.allReadyNodes.has(dataId)) {
+        const $existingNode = this.allReadyNodes.get(dataId);
+
+        // 特殊节点（null）：通过 layoutInfo 获取 DOM 引用并更新
+        if ($existingNode === null) {
+            const $specialNode = this.getSpecialNodeDOM(dataId);
+
+            if ($specialNode) {
+                // 重新渲染特殊节点的内容
+                this.updateRenderUI($specialNode, data, dataId);
+
+                // 等待DOM更新后获取新高度
+                return new Promise(resolve => {
+                    window.requestAnimationFrame(() => {
+                        resolve($specialNode.height());
+                    });
+                });
+            }
+
+            // 无法获取特殊节点DOM，返回旧高度
+            console.warn('Waterfall: Special node DOM not found for dataId', dataId);
+            return this.getCardOldHeight(dataId);
+        }
+
+        // 普通节点：从节点池获取或创建临时节点
+        const $container = $(options.container);
+        const $viewport = $container.find('.waterfall-list-viewport');
+
+        let $node = getNodePoolPop(this.nodePool, this.activeNodes);
+        let isBorrowed = false;
+
+        if ($node) {
+            // 从节点池借用节点
+            isBorrowed = true;
+
+            // 设置位置和样式
+            $node.css({
+                'transform': 'translate(-9999px, -9999px)',
+            });
+
+            // 设置宽度
+            if (options.columns !== 1) {
+                $node.width(this.columnWidth + 'px');
+            }
+
+            // 使用 updateRenderUI（节点池的节点已有结构）
+            this.updateRenderUI($node, data, dataId);
+        } else {
+            // 节点池空了，创建临时节点
+            $node = $(
+                `<div class="waterfall-item"
+                      data-index="${dataId}"
+                      style="position: absolute; transform: translate(-9999px, -9999px);"
+                >
+                 </div>`
+            );
+            $viewport.append($node);
+
+            // 设置宽度
+            if (options.columns !== 1) {
+                $node.width(this.columnWidth + 'px');
+            }
+
+            // 使用 renderUI（临时节点是全新的）
+            this.renderUI($node, data, dataId);
+        }
+
+        // 等待DOM更新
+        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变更，触发高度重新绘制
+Waterfall.prototype.updateCard = async function (data) {
+    const self = this;
+    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
+    }
+
+    // 检查数据是否已经渲染过
+    if (!this.renderedDataIds.has(dataId)) {
+        console.log('Waterfall: dataId not rendered yet', dataId);
+        return
+    }
+
+    const itemData = options.data[dataId];
+
+    // 获取旧高度
+    const oldHeight = this.getCardOldHeight(dataId);
+
+    // 获取新高度（会自动处理渲染和临时节点）
+    const newHeight = await this.getCardNewHeight(dataId, itemData);
+
+    // 应用高度变化
+    this.applyHeightChange(dataId, oldHeight, newHeight);
+}
+
+// 应用高度变化到布局
+Waterfall.prototype.applyHeightChange = function (dataId, oldHeight, newHeight) {
+    const minus = newHeight - oldHeight;
+
+    // 如果高度没有变化，直接退出
+    if (minus === 0) {
+        console.log('Waterfall: Card height unchanged for dataId', dataId);
+        return;
+    }
+
+    console.log('Waterfall: 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;
+
+        // 这里为了简化，各列的瀑布流保持不动，只更新各列下节点的top位置，不做节点的跨列位移
+        for (let j = 0; j < column.children.length; j++) {
+            const row = column.children[j];
+
+            if (row.dataId === dataId) {
+                foundCard = true;
+                needUpdate = true;
+
+                // 更新当前卡片的bottom
+                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);
+    }
+}
+
+// 重新计算设置一遍所有的卡片位置
+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) {
+    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;
+        // window.requestAnimationFrame(() => {
+        //     setTimeout(() => {
+        //         this.$scrollDom.scrollTop(loadingTop + this.$loadingNode.height());
+        //     });
+        // });
+    }
+
+    if (callback) callback($node)
+    this.setScrollHeight();
+}
+
+// 隐藏loading的回调函数
+Waterfall.prototype.hideLoading = function (callback = null) {
+    this.isShowLoading = false;
+    const options = this.options;
+    let $node = null
+    if (this.$loadingNode) {
+        let h1 = this.getMaxHeight() + options.marginBottom
+        this.$loadingNode.css('transform', `translate(0px,-99999px)`);
+        //如果要设置高度，那么这里判断一下当前是否正在做updata  一般这里被调用时，数据已经读到，在updata的同一时间调用了该函数
+        // 如果两个时刻高度是一致的 那么数据就是一致的 这里重新设置回来高度即可
+        window.requestAnimationFrame(() => {
+            this.setScrollHeight();
+        })
+        $node = this.$loadingNode
+    }
+
+    if (callback) callback($node)
+    this.setScrollHeight();
+}
+
+// 设置滚动条列表的高度
+Waterfall.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('.waterfall-list-scroll').css('height', h + 'px');
+}
+
+// 销毁自己
+Waterfall.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;
+}