更新记录

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

• 初始发布版本
• 支持 H5、微信小程序
• 支持 Vue 2、Vue 3
• 支持异步图片自动回流
• 支持下拉刷新和触底加载更多

平台兼容性

uni-app(5.0)

其他

hello-waterfall-flow

支持 H5、微信小程序、Vue 2、Vue 3 的 uni-app 瀑布流组件。

特点：

• 基于真实容器宽度计算列宽
• 支持异步图片高度自动回流，拿来即可用
• 支持下拉刷新、触底加载更多
• 支持 Vue 2 / Vue 3
• 提供 relayout、scrollToTop、scrollToIndex、getLayout 方法

重要说明

• 当前插件 ID 使用的是占位值 hello-waterfall-flow
• 发布前请把 uni_modules/hello-waterfall-flow 目录名和 package.json 里的 id 改成你的真实插件 ID
• 按官方要求，插件 ID 应采用 作者ID-插件英文名 格式

兼容性

安装方式

1. 插件市场导入

导入插件后，组件位于：

uni_modules/hello-waterfall-flow/components/waterfall-flow/waterfall-flow.vue

2. 页面内引入

<script>
import WaterfallFlow from '@/uni_modules/hello-waterfall-flow/components/waterfall-flow/waterfall-flow.vue'

export default {
  components: { WaterfallFlow }
}
</script>

基础示例

<template>
  <waterfall-flow
    ref="wf"
    :data="list"
    :num-columns="2"
    :column-gap="10"
    :row-gap="10"
    :padding-left="10"
    :padding-right="10"
    :estimated-height="220"
    :loading="loading"
    :has-more="hasMore"
    :enable-refresh="true"
    :refreshing="refreshing"
    height="100vh"
    @loadmore="loadMore"
    @refresh="onRefresh"
  >
    <template #header>
      <view class="header">推荐</view>
    </template>

    <template #item="{ item, index, column }">
      <view class="card">
        <image class="card-img" :src="item.img" mode="widthFix" lazy-load />
        <view class="card-body">
          <text class="card-title">{{ index + 1 }}. {{ item.title }}</text>
          <text class="card-column">列: {{ column + 1 }}</text>
        </view>
      </view>
    </template>
  </waterfall-flow>
</template>

<script>
import WaterfallFlow from '@/uni_modules/hello-waterfall-flow/components/waterfall-flow/waterfall-flow.vue'

export default {
  components: { WaterfallFlow },

  data () {
    return {
      list: [],
      loading: false,
      hasMore: true,
      refreshing: false,
      page: 1
    }
  },

  onLoad () {
    this.loadMore()
  },

  methods: {
    loadMore () {
      if (this.loading || !this.hasMore) return
      this.loading = true

      this.fetchPage(this.page).then(arr => {
        this.list = this.list.concat(arr)
        this.page++
        this.loading = false
        if (arr.length < 10) this.hasMore = false
      }).catch(() => {
        this.loading = false
      })
    },

    onRefresh () {
      this.refreshing = true
      this.page = 1
      this.hasMore = true

      this.fetchPage(1).then(arr => {
        this.list = arr
        this.page = 2
        this.refreshing = false
      }).catch(() => {
        this.refreshing = false
      })
    },

    fetchPage (page) {
      return new Promise(resolve => {
        setTimeout(() => {
          var arr = []
          var base = (page - 1) * 10
          var i
          for (i = 0; i < 10; i++) {
            arr.push({
              id: 'card-' + (base + i),
              title: '卡片 ' + (base + i + 1),
              img: 'https://picsum.photos/300/' + (180 + (i % 5) * 40) + '?t=' + (base + i)
            })
          }
          resolve(arr)
        }, 300)
      })
    }
  }
}
</script>

Props

布局数值类参数单位均为 px。

Slots

header

顶部插槽。

item

卡片插槽，参数如下：

footer

底部插槽。

Events

Methods

通过 ref 调用。

relayout()

手动重新测量并重排。

大多数普通图片场景不需要主动调用。只有在卡片高度发生更晚的二次变化时，例如折叠展开、富文本二次渲染、字体加载后高度变化，才建议手动调用。

scrollToTop()

滚动到顶部。

scrollToIndex(index)

滚动到指定项。

getLayout()

返回当前布局信息：

{
  bodyHeight: 3200,
  positions: [
    { top: 0, left: 10, width: 172.5, height: 240 }
  ],
  itemWidth: 172.5,
  containerWidth: 375
}

使用建议

1. 尽量提供稳定 key

推荐：

<waterfall-flow
  :data="list"
  :key-extractor="item => item.id"
/>

2. estimatedHeight 尽量接近平均卡片高度

它不会影响最终正确性，但会影响首屏重排跳动程度。

3. height 需要明确

组件内部使用 scroll-view，因此请给一个明确高度，例如：

<waterfall-flow height="100vh" />

发布前检查

• 修改 package.json.id
• 修改 package.json.displayName
• 补充 package.json.repository
• 补充 package.json.author
• 补充 dcloudext.contact.qq
• 在 HBuilderX 中右键 uni_modules/hello-waterfall-flow 检查是否可以正常发布

示例工程

当前工程示例页：

• @/pages/index/index.vue