更新记录

1.0.0（2026-07-30） 下载此版本

首个版本。

• 支持固定列数或按最小列宽自适应
• 列表项绝对定位，测量高度后放进最短列
• 图片异步加载通过稳定性轮询自动重排，零配置
• 支持 H5 / App(app-vue) / 微信小程序

平台兼容性

uni-app(3.7.11)

dazhi-waterfall 瀑布流组件

支持 H5 / App(app-vue) / 微信小程序 的瀑布流（Pinterest 风格）组件，列数可固定或按最小列宽自适应，图片异步加载后自动重排，数据驱动渲染。

特性

• 单套代码跨三端（H5 / App / 微信小程序）
• 列数两种策略：固定列数 columns，或按最小列宽 columnWidth 自适应（columns 优先）
• 项高度参差不齐，自动测量后放进最短列
• 图片异步加载后自动重排（稳定性轮询，零配置，无需手动绑定事件）
• 作用域插槽，列表项内容完全自定义
• easycom 自动引入，无需手动 import

安装

将 dazhi-waterfall 目录放入项目的 uni_modules/ 目录即可，easycom 会自动注册组件。

基础用法

<template>
    <dazhi-waterfall :list="list" :columns="2" :gap="20" item-key="id">
        <template #default="{ item }">
            <view class="card">
                <image :src="item.img" mode="widthFix" />
                <text>{{ item.title }}</text>
            </view>
        </template>
    </dazhi-waterfall>
</template>

<script>
    export default {
        data() {
            return {
                list: [
                    { id: 1, img: 'https://picsum.photos/300/400', title: 'A' },
                    { id: 2, img: 'https://picsum.photos/300/260', title: 'B' },
                    { id: 3, img: 'https://picsum.photos/300/320', title: 'C' }
                ]
            }
        }
    }
</script>

关键点：图片加载自动重排

瀑布流的核心是「项高度参差不齐」，而图片是异步加载的——图片加载前后高度不同。本组件内置稳定性轮询：每次重排后延迟 250ms 再测一次，若总高度发生变化（说明有图片加载完成导致高度变了）就继续重测，直到高度稳定或达到 6 次上限。全程自动，无需手动绑定事件。

mode="widthFix" 让图片按宽度缩放、高度自适应，是瀑布流图片的推荐模式。

若项内有其它异步内容，或图片加载较慢超出轮询窗口，可调用组件的 relayout() 方法手动重排：

<dazhi-waterfall ref="wf" :list="list">...</dazhi-waterfall>

this.$refs.wf.relayout()

注：小程序端插槽 prop 不能用作事件处理器（@load="slotProp" 会报 method not found），故不提供 onImageLoad 插槽回调，改用自动轮询。

API

Props

Slots

方法（通过 ref 调用）

跨端实现说明

列表项为绝对定位的普通 view，位置由 uni.createSelectorQuery 测量高度后计算（放进最短列）。

• 列数：传 columns 则固定；否则按 containerWidth / columnWidth 自适应。
• 高度测量：数据变化时延迟测量（MP 端 nextTick 早于原生渲染，需 setTimeout 等渲染完成）；图片异步加载通过「稳定性轮询」自动重测（每次重排后若总高度变化则再测一次，直到稳定）。
• 跨端要点：
  • 动态定位用字符串 style（对象语法在微信小程序端会丢值，导致定位失效）
  • createSelectorQuery 必须 .in(this)（自定义组件内不带 .in(this) 查不到节点，返回空）
  • 小程序端插槽 prop 不能用作事件处理器，故图片重排用自动轮询而非插槽回调
  • 列数/列宽/间距变化时组件自动重排，无需调用方手动 relayout

限制与路线图

当前 1.0.0 版本的已知限制：

• 首次渲染前有一帧隐藏（opacity:0），测量完成后显示，避免项堆在左上角闪烁
• 数据变化（如追加）时，新增项有一帧位于左上角，测量后归位
• 图片加载超出轮询窗口（约 1.5s）时不会自动重排，需手动调 relayout()
• 不内置「下拉刷新 / 上拉加载」，由外层 scroll-view 或页面实现
• 未实现虚拟化（超长列表性能优化）

路线图：

• [ ] 虚拟化长列表
• [ ] 减少追加时新增项的一帧闪烁
• [ ] app-nvue 适配

许可

MIT