更新记录

1.0.0（2026-06-24） 下载此版本

1.0.0

• 首次发布 w-waterfall 瀑布流组件。
• 支持按真实列高自动分发与奇偶分列两种模式。
• 支持虚拟列表渲染能力、性能拉满。
• 支持列表追加、手动重排、列间距、行间距和外边距配置。
• 支持 fade-up、fade、zoom、none 四种入场动画配置。
• 支持通过 keyField 指定唯一字段，兼容点号路径如 goods.id。

平台兼容性

uni-app(3.7.12)

其他

ws-waterfall 瀑布流组件

ws-waterfall 是一个适用于 uni-app Vue3 的双列瀑布流组件。组件支持按真实列高自动分发，也支持奇偶分列；适合商品卡片、图片流、内容流等高度不固定的列表场景。

使用方式

插件导入后可通过 easycom 直接使用：

<template>
  <ws-waterfall
    ref="waterfallRef"
    :list="goodsList"
    key-field="goods.id"
    :column-gap="16"
    :row-gap="16"
    :padding="0"
    mode="auto"
    @layout-done="onLayoutDone"
  >
    <template #default="{ item, index, column }">
      <view class="goods-card">
        <image class="goods-card__image" :src="item.image" mode="widthFix" @load="waterfallRef?.reflow()" />
        <view class="goods-card__title">{{ item.title }}</view>
      </view>
    </template>
  </ws-waterfall>
</template>

<script setup lang="ts">
const waterfallRef = ref()

const goodsList = ref([
  {
    goods: { id: 1 },
    image: "/static/demo/goods-1.png",
    title: "商品标题"
  }
])

const onLayoutDone = () => {
  console.log("waterfall layout done")
}
</script>

虚拟列表

大数据量列表可开启虚拟渲染：

<ws-waterfall
  ref="waterfallRef"
  :list="goodsList"
  virtual
  :estimated-item-height="360"
  :overscan="800"
  key-field="goods.id"
>
  <template #default="{ item }">
    <goods-card :item="item" @image-load="waterfallRef?.reflow()" />
  </template>
</ws-waterfall>

虚拟模式基于页面滚动，不会创建内部 scroll-view。未测量卡片会先按 estimatedItemHeight 预估高度，可见卡片渲染后自动回填真实高度；图片异步加载导致高度变化时，建议调用 reflow()。

Props

Events

Slots

Expose

注意事项

• 当前组件使用 Vue3 <script setup>，适用于 uni-app Vue3 项目。
• auto 模式依赖 uni.createSelectorQuery() 测量列高，图片高度异步变化时建议在图片 load 后调用 reflow()。
• 虚拟模式适合大量数据列表，小数据列表可继续使用默认非虚拟模式。
• 组件不包含广告、不采集数据、不申请系统权限。