更新记录

0.0.5（2025-07-22）

  • feat: 优化结构

0.0.4（2025-07-04）

  • feat: 兼容uniappx

0.0.3（2023-05-22）

  • chore: 不支持vue2
查看更多

平台兼容性

uni-app(4.53)

Vue2 Vue3 Chrome Safari app-vue app-nvue Android iOS 鸿蒙
√ √ √ √ √ - 5.1 √ √
微信小程序 支付宝小程序 抖音小程序 百度小程序 快手小程序 京东小程序 鸿蒙元服务 QQ小程序 飞书小程序 快应用-华为 快应用-联盟
√ - - - - - - - - - -

uni-app x(4.71)

Chrome Safari Android iOS 鸿蒙 微信小程序
√ √ 5.1 √ √ √

lime-waterflow 瀑布流组件

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

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

基础功能

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

文档链接

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

安装方法

  1. 在uni-app插件市场中搜索并导入lime-waterflow
  2. 首次导入可能需要重新编译

代码演示

基础使用

 <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 事件，以便准确计算布局位置：

  <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-***80-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=10075136***2&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=262285159***&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/***81088257_***18230529.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)

快速预览

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

<!-- 代码位于 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变量，可用于自定义样式。

Waterflow 组件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 瀑布流动画持续时间

FlowItem 组件CSS变量

变量名 默认值 说明
--l-flow-item-width auto 瀑布流项目宽度（由瀑布流组件自动计算）
--l-flow-item-top 0px 瀑布流项目顶部位置（由瀑布流组件自动计算）
--l-flow-item-left 0px 瀑布流项目左侧位置（由瀑布流组件自动计算）
--l-flow-item-anim-duration 0.5s 瀑布流项目动画持续时间

支持与赞赏

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

隐私、权限声明

1. 本插件需要申请的系统权限列表：

无

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明：

无

3. 本插件是否包含广告，如包含需详细说明广告表达方式、展示频率：

无

评论列表 撰写评论 向官方投诉

暂无用户评论。