更新记录

1.1.0（2026-09-01） 下载此版本

• 内置上拉加载：内部 scroll-view 滚动到底部触发 load-more 事件，loading / finished 控制状态并防止重复触发
• 底部内置加载状态条：加载中 / 没有更多 / 上拉加载更多，文案可自定义（loadingText / finishedText / loadMoreText）
• 新增属性：height（滚动高度，Number 单位 rpx 或字符串）、loading、finished、loadMoreText、loadingText、finishedText
• 不传 height 时组件高度自适应、无内部滚动，内容随页面滚动

平台兼容性

uni-app(4.87)

其他

fg-waterfall 瀑布流

左右两列瀑布流布局组件，v-model 传入数组后自动分列，通过 left / right 作用域插槽渲染内容；支持自定义间隔、空态展示。纯组件零依赖，兼容微信小程序、H5、App（vue），同时兼容 Vue2 与 Vue3 写法。

特性

• 🏞 瀑布流布局：v-model 绑定数组，自动按奇偶轮流分配到左右两列
• 🧩 作用域插槽：left / right 插槽直接拿 leftList / rightList 渲染
• 📐 左右两列：固定两列瀑布流，columns 可设 1（仅左列）或 2（默认）
• 📏 自定义间隔：gap 统一控制水平/垂直间隔，或 columnGap / rowGap 单独设置
• 🈳 空态展示：列表为空时显示 emptyText 文案或自定义 empty 插槽
• 零依赖、无测量：分列不依赖内容高度，图片未加载完成也不影响布局稳定性

安装

将 uni_modules/fg-waterfall 目录复制到项目的 uni_modules 目录下，即可在页面中直接使用（uni-app easycom 自动注册，无需手动引入）。

快速开始（两列，与 left/right 插槽示例一致）

<template>
    <view class="page">
        <fg-waterfall v-model="flowList" :gap="20">
            <template v-slot:left="{ leftList, itemStyle }">
                <view v-for="(item, index) in leftList" :key="index" class="card" :style="itemStyle">
                    <!-- 这里编写您的内容，item 为您传递给 v-model 的数组元素 -->
                    <image :src="item.cover" mode="widthFix"></image>
                    <text>{{ item.title }}</text>
                </view>
            </template>
            <template v-slot:right="{ rightList, itemStyle }">
                <view v-for="(item, index) in rightList" :key="index" class="card" :style="itemStyle">
                    <image :src="item.cover" mode="widthFix"></image>
                    <text>{{ item.title }}</text>
                </view>
            </template>
        </fg-waterfall>
    </view>
</template>

<script>
export default {
    data() {
        return {
            flowList: [
                { cover: '/static/1.jpg', title: '标题一' },
                { cover: '/static/2.jpg', title: '标题二' },
                // ... 追加数据即可，组件会自动重新分列
            ]
        }
    }
}
</script>

提示：itemStyle（含垂直间隔 marginBottom）为可选作用域数据，绑定到插槽内容根节点即可让 rowGap / gap 的垂直间隔生效；不绑定也完全可用，间隔由您自行控制。

上拉加载（内置）

组件内置上拉加载：内部使用 scroll-view，滚动到底部自动触发 @load-more 事件；配合 loading / finished 控制加载状态（为 true 时不再触发，防止重复请求），底部状态条（加载中 / 没有更多 / 上拉加载更多）由组件内置展示，文案可自定义。

<template>
    <fg-waterfall
        v-model="flowList"
        height="1000"
        :loading="loading"
        :finished="finished"
        @load-more="fetchList"
    >
        <template v-slot:left="{ leftList, itemStyle }">
            <view v-for="(item, index) in leftList" :key="item.id" :style="itemStyle">
                <!-- 左列内容 -->
            </view>
        </template>
        <template v-slot:right="{ rightList, itemStyle }">
            <view v-for="(item, index) in rightList" :key="item.id" :style="itemStyle">
                <!-- 右列内容 -->
            </view>
        </template>
    </fg-waterfall>
</template>

<script>
export default {
    data() {
        return {
            flowList: [],      // 瀑布流数据
            page: 1,
            pageSize: 10,
            loading: false,
            finished: false
        }
    },
    methods: {
        // 由 @load-more 触发；loading / finished 防止重复请求
        fetchList() {
            if (this.loading || this.finished) return
            this.loading = true
            setTimeout(() => {
                const slice = fetchApi(this.page, this.pageSize) // 替换为您的接口
                this.flowList = this.flowList.concat(slice)
                this.page++
                if (slice.length < this.pageSize) this.finished = true
                this.loading = false
            }, 300)
        }
    }
}
</script>

说明：

• height 必须设置（Number 单位 rpx，或字符串如 '100vh'），scroll-view 才有内部滚动空间；不传 height 时组件高度自适应、无内部滚动，内容随页面滚动，此时可按需用页面 onReachBottom 自行实现加载。
• 首次进入页面请自行触发一次加载（如 onLoad 中调用 fetchList）以填充首屏数据；scroll-view 内容不足一屏时不会触发 @load-more。
• loading / finished 由业务侧维护并传入组件；组件在二者为 true 时不会触发 load-more，业务侧也建议做同样的防抖。

属性（Props）

事件（Events）

插槽（Slots）

注意事项

• 分列策略为奇偶轮流分配（index % columns），不测量内容高度，因此图片未加载、内容高度不均时布局依然稳定；如需严格“最短列优先”可自行扩展。
• 列表数据变化（push / 替换数组）会自动触发重新分列，无需手动刷新。
• 间隔单位为 rpx，在小程序、H5、App 端由编译器统一换算。
• 组件不修改 v-model 传入的数组；删除/更新数据请在业务侧操作。
• 使用内置上拉加载时需设置 height（scroll-view 才有内部滚动空间）；不传 height 则退化为普通布局，内容随页面滚动。
• nvue 环境暂不支持。

changelog

详见 changelog.md。