LimeWaterflow 瀑布流组件

一个瀑布流布局组件，支持虚拟滚动、下拉刷新、自动布局等特性，兼容uniapp/uniappx。

插件依赖lime-style,lime-shared不喜勿下。

基础功能

瀑布流布局，支持自定义列数
支持虚拟滚动，只渲染可视区域内的元素
支持下拉刷新
支持自动布局，根据内容高度自动排列
支持加载更多
支持自定义间距和内边距

文档链接

📚 组件详细文档请访问以下站点：

安装方法

在uni-app 中搜索并导入lime-waterflow
首次导入可能需要重新编译

代码演示

基础使用

html

 <l-waterflow 
  :crossAxisCount="2" 
  :mainAxisGap="10" 
  :crossAxisGap="10" 
  :padding="[10, 10, 10, 10]"
  @scrolltolower="onLoadMore"
  refresherEnabled
  @refresherrefresh="onRefresh"
>
  <l-flow-item v-for="(item, index) in list" :key="index">
	<view class="item">
	  <view class="title">{{item.title}}</view>
	</view>
  </l-flow-item>
</l-waterflow>

使用内容插槽处理动态高度内容

当瀑布流项目中包含图片或其它不确定高度的组件时，需要使用 content 插槽，并在内容加载完成后调用 measure 事件，以便准确计算布局位置：

html

  <l-waterflow
    :cross-axis-count="2"
    :main-axis-gap="10"
    :cross-axis-gap="10"
    :padding="[10, 10, 10, 10]"
	@scrolltolower="load"
  >
    <l-flow-item
      v-for="(item, index) in list"
      :key="index"
      :index="index"
    >
		<template #content="{measure}">
			<view class="item">
				<image class="item-image" :src="item.img" mode="widthFix" @load="measure" />
				<text class="item-text">{{item.name}}</text>
			</view>
		</template>
    </l-flow-item>
	<!-- 加载更多 -->
	<!-- #ifndef APP-ANDROID || APP-IOS -->
	<template #load-more>
		<l-load-more status="loading"></l-load-more>
	</template>
	<!-- #endif -->
	<!-- #ifdef APP-ANDROID || APP-IOS -->
	<flow-item slot="load-more" type=3>
		<l-load-more status="loading"></l-load-more>
	</flow-item>
	<!-- #endif -->
  </l-waterflow>

// 数据列表
const list = ref<UTSJSONObject[]>([]);

// 图片列表
const imgs = [
	"https://plus.unsplash.com/premium_photo-1750317246680-8e0c19023ec5?q=80&w=686&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D",
	"https://gips0.baidu.com/it/u=567323913,331130417&fm=3028&app=3028&f=JPEG&fmt=auto&q=100&size=f1000_1000",
	"http://gips3.baidu.com/it/u=775223787,1959096310&fm=3028&app=3028&f=JPEG&fmt=auto?w=1440&h=2560",
	"http://gips3.baidu.com/it/u=3886271102,3123389489&fm=3028&app=3028&f=JPEG&fmt=auto?w=1280&h=960",
	"http://gips3.baidu.com/it/u=100751361,1567855012&fm=3028&app=3028&f=JPEG&fmt=auto?w=960&h=1280",
	"https://gips3.baidu.com/it/u=3732737575,1337431568&fm=3028&app=3028&f=JPEG&fmt=auto&q=100&size=f1440_2560",
	"http://gips0.baidu.com/it/u=3560029307,576412274&fm=3028&app=3028&f=JPEG&fmt=auto?w=960&h=1280",
	"http://gips3.baidu.com/it/u=3892227616,2240763844&fm=3028&app=3028&f=JPEG&fmt=auto?w=3200&h=3200",
	"http://gips1.baidu.com/it/u=3885198370,1571719977&fm=3028&app=3028&f=JPEG&fmt=auto?w=2560&h=1920",
	"http://gips0.baidu.com/it/u=3557606594,2640240494&fm=3028&app=3028&f=JPEG&fmt=auto?w=2048&h=2048",
	"http://gips2.baidu.com/it/u=3589715542,620993072&fm=3028&app=3028&f=JPEG&fmt=auto?w=2048&h=2048",
	"http://gips0.baidu.com/it/u=398917425,2942293409&fm=3028&app=3028&f=JPEG&fmt=auto?w=1920&h=2560",
	"http://gips0.baidu.com/it/u=1370402140,2009956566&fm=3028&app=3028&f=JPEG&fmt=auto?w=960&h=1280",
	"http://gips2.baidu.com/it/u=3579059838,1031544773&fm=3028&app=3028&f=JPEG&fmt=auto?w=1280&h=720",
	"http://gips3.baidu.com/it/u=1121275038,3924754772&fm=3028&app=3028&f=JPEG&fmt=auto?w=1920&h=2560",
	"https://gips1.baidu.com/it/u=2622851591,902014643&fm=3028&app=3028&f=JPEG&fmt=auto&q=100&size=f600_800",
	"http://gips2.baidu.com/it/u=658660608,3402622316&fm=3028&app=3028&f=JPEG&fmt=auto?w=1280&h=960",
	"http://gips3.baidu.com/it/u=1821127123,1149655687&fm=3028&app=3028&f=JPEG&fmt=auto?w=720&h=1280",
	"http://gips3.baidu.com/it/u=3557221034,1819987898&fm=3028&app=3028&f=JPEG&fmt=auto?w=1280&h=960",
	"http://gips1.baidu.com/it/u=1647344915,1746921568&fm=3028&app=3028&f=JPEG&fmt=auto?w=720&h=1280",
	"http://gips3.baidu.com/it/u=3419425165,837936650&fm=3028&app=3028&f=JPEG&fmt=auto?w=1024&h=1024",
	"https://oss.smalld.cn/prod/novel/20250630/a98d11b7-71f8-4322-bba3-cf43c445d5c2.jpg",
	"https://oss.smalld.cn/image_service/prod/20250426/fb6784b5-64da-53ad-b81b-8699412fa578.jpg",
	"https://oss.smalld.cn/prod/novel/20250513/9f2761e1-2d65-4219-84c4-386c014291e6.jpg",
	"https://oss.smalld.cn/prod/novel/20250630/37e2b951-abb1-43c7-b1f6-1dbe7387bd9b.jpg",
	"https://oss.smalld.cn/common/aigc/1700802756981088257_1939691525118230529.jpg",
	"https://oss.smalld.cn/prod/novel/20250630/b8a2b96a-aea8-4e81-ab12-a8e77c8af1d8.jpg",
	"https://oss.smalld.cn/image_service/prod/20250601/3490ebad-404d-517a-ad5d-6ae4b6bf15d9.jpg",
]


let pageNum = 0

const load = (e : UniScrollToLowerEvent|null) => {
	pageNum++
	setTimeout(()=>{
		uni.hideToast()
		let items:UTSJSONObject[] = [];
		for (let index = 0; index < 20; index++) {
		    items.push({
		        id: Math.random().toString(16).replace('0.',''),
				name: '测试',
		        img: imgs[index % imgs.length],
		    });
		}
		list.value = list.value.concat(items)
	},1000)
}


const refresherTriggered = ref(false)

const onRefresherpulling = (event : UniRefresherEvent) => {
	console.log('refresherpulling', event)
}
const onRefresherrefresh = (event : UniRefresherEvent) => {
	refresherTriggered.value = true
	console.log('refresherrefresh', event)
	setTimeout(()=>{
		list.value = []
		pageNum = 0
		refresherTriggered.value = false
		load(null)
	},1000)
}
const onRefresherrestore = (event : UniRefresherEvent) => {
	console.log('refresherrestore', event)
}

load(null)

快速预览

导入插件后，可以直接使用以下标签查看演示效果：

html

<!-- 代码位于 uni_modules/lime-waterflow/components/lime-waterflow -->
<lime-waterflow />

插件标签说明

l-waterflow：瀑布流容器组件
l-flow-item：瀑布流项目组件
lime-waterflow：演示标签

API文档

Waterflow Props

属性名	类型	默认值	说明
crossAxisCount	number	-	交叉轴元素数量（列数）
mainAxisGap	number	-	主轴方向间隔（行间距）
crossAxisGap	number	-	交叉轴方向间隔（列间距）
padding	number[]	-	内边距，长度为4的数组，按top、right、bottom、left顺序指定
bounces	boolean	-	是否启用回弹效果
upperThreshold	number	-	距顶部多远时（单位px），触发scrolltoupper事件
lowerThreshold	number	-	距底部多远时（单位px），触发scrolltolower事件
scrollTop	number	-	设置竖向滚动条位置
showScrollbar	boolean	-	是否显示滚动条
refresherEnabled	boolean	false	是否开启下拉刷新（暂不支持横向刷新）
refresherThreshold	number	-	下拉刷新阈值（仅在refresherDefaultStyle='none'时生效）
refresherMaxDragDistance	number	-	下拉最大拖拽距离（px），默认为刷新控件高度的2.5倍
refresherDefaultStyle	'black' \| 'white' \| 'none'	-	下拉刷新默认样式
refresherTriggered	boolean	false	当前下拉刷新状态
virtualScroll	boolean	-	是否启用虚拟滚动（只渲染可视区域）
preloadScreens	number	-	预加载屏幕数量（可视区域外预加载的屏幕数量）

FlowItem Props

属性名	类型	默认值	说明
type	number	-	项目类型
index	number	-	可选，项目索引

事件

Waterflow 事件

事件名	说明	参数
scrolltoupper	滚动到顶部时触发	(event: UniScrollToUpperEvent) => void
scrolltolower	滚动到底部时触发	(event: UniScrollToLowerEvent) => void
refresherrefresh	下拉刷新触发时调用	(event: UniRefresherEvent) => void
refresherrestore	下拉刷新复位时调用	(event: UniRefresherEvent) => void
refresherpulling	下拉刷新控件被下拉时调用	(event: UniRefresherEvent) => void

插槽

Waterflow 插槽

插槽名	说明
default	默认插槽，用于放置瀑布流的内容项
refresher	自定义下拉刷新元素
load-more	自定义加载更多元素

FlowItem 插槽

插槽名	说明	参数
default	默认插槽，用于放置单个项目的内容	-
content	内容插槽，用于放置单个项目的内容	`{measure}`把图片的load传给它，触发测量尺寸

主题定制

组件提供了下列CSS变量，可用于自定义样式。

变量名	默认值	说明
--l-waterflow-height	500px	瀑布流容器高度
--l-waterflow-width	100%	瀑布流容器宽度
--l-waterflow-gap	0px	瀑布流项目间隙（会被props中的gap覆盖）
--l-waterflow-padding-left	0px	瀑布流左侧内边距
--l-waterflow-padding-rgiht	0px	瀑布流右侧内边距
--l-waterflow-columns	2	瀑布流列数（会被props中的crossAxisCount覆盖）
--l-waterflow-bg-color	inherit	瀑布流背景颜色
--l-waterflow-anim-duration	50ms	瀑布流动画持续时间
--l-flow-item-width	auto	瀑布流项目宽度（由瀑布流组件自动计算）
--l-flow-item-top	0px	瀑布流项目顶部位置（由瀑布流组件自动计算）
--l-flow-item-left	0px	瀑布流项目左侧位置（由瀑布流组件自动计算）
--l-flow-item-anim-duration	0.5s	瀑布流项目动画持续时间

支持与赞赏

如果你觉得本插件解决了你的问题，可以考虑支持作者：

支付宝赞助	微信赞助

源代码

组件源码

LimeWaterflow 瀑布流组件 ​

基础功能 ​

文档链接 ​

安装方法 ​

代码演示 ​

基础使用 ​

使用内容插槽处理动态高度内容 ​

快速预览 ​

插件标签说明 ​

API文档 ​

Waterflow Props ​

FlowItem Props ​

事件 ​

Waterflow 事件 ​

插槽 ​

Waterflow 插槽 ​

FlowItem 插槽 ​

主题定制 ​

支持与赞赏 ​

源代码 ​

LimeWaterflow 瀑布流组件

基础功能

文档链接

安装方法

代码演示

基础使用

使用内容插槽处理动态高度内容

快速预览

插件标签说明

API文档

Waterflow Props

FlowItem Props

事件

Waterflow 事件

插槽

Waterflow 插槽

FlowItem 插槽

主题定制

支持与赞赏

源代码