更新记录

1.0.3（2026-09-02） 下载此版本

重构

1.0.2（2024-11-20） 下载此版本

1. 优化dom问题判断

1.0.1（2024-11-18） 下载此版本

1. 优化

平台兼容性

uni-app

其他

SL-Waterfall 瀑布流组件

适用于 uni-app（H5 / 各端小程序）的瀑布流组件。支持网络图片（无需预知宽高）、多列布局、左列不低于右列、渐进渲染、触底加载、返回顶部、空状态。

特性

• 网络图片自适应：通过 <image> 的 @load 事件获取真实宽高，无需 uni.getImageInfo，规避 H5 跨域与小程序域名白名单问题

• 多列布局：可配置列数、列间距、行间距

• 左列不低于右列：分配后做批末修正，保证累计高度非递增，避免右列空白

• 渐进渲染：已渲染的 item 永不删除，滚动时无抖动；DOM 量随用户浏览量增长，可控

• 组件内滚动：基于 scroll-view，不依赖页面级生命周期，触底/返回顶部均由组件自身实现

• H5 / 小程序通用：无平台特有 API 依赖

字段说明（Props）

事件说明（Events）

方法说明（通过 ref 调用）

this.$refs.waterfall.scrollToTop();

插槽说明（Slots）

示例

基础用法

<template>
  <sl-waterfall
    :list="list"
    :column-count="2"
    image-key="image"
    @itemtap="onItemTap"
    @scrolltolower="loadMore"
  />
</template>

<script>
export default {
  data() {
    return { list: [] };
  },
  methods: {
    loadMore() {
      // 追加数据到 this.list
    },
    onItemTap(item) {
      uni.showToast({ title: item.title, icon: 'none' });
    }
  }
};
</script>

完整示例（自定义插槽 + 触底加载 + 返回顶部 + 空状态）

<template>
  <view class="page">
    <sl-waterfall
      ref="waterfall"
      :list="list"
      :column-count="2"
      :column-gap="16"
      :row-gap="16"
      :padding="16"
      height="100vh"
      :enable-virtual="true"
      :lower-threshold="80"
      :back-top-threshold="600"
      image-key="image"
      @itemtap="onItemTap"
      @scrolltolower="loadMore"
    >
      <!-- 自定义 item 底部内容 -->
      <template v-slot:item="{ item }">
        <view class="card-footer">
          <text class="card-title">{{ item.title }}</text>
          <text class="card-author">{{ item.author }}</text>
        </view>
      </template>

      <!-- 自定义返回顶部按钮 -->
      <template v-slot:backtop>
        <view class="custom-backtop">
          <text>顶部</text>
        </view>
      </template>

      <!-- 自定义空数据 -->
      <template v-slot:empty>
        <view class="custom-empty">
          <text>📭 还没有内容</text>
        </view>
      </template>

      <!-- 触底加载状态 -->
      <template v-slot:footer>
        <view class="load-more">
          <text v-if="loading">加载中…</text>
          <text v-else-if="noMore">没有更多了</text>
        </view>
      </template>
    </sl-waterfall>
  </view>
</template>

<script>
export default {
  data() {
    return {
      list: [],
      page: 1,
      loading: false,
      noMore: false
    };
  },
  onLoad() {
    this.loadMore();
  },
  methods: {
    loadMore() {
      if (this.loading || this.noMore) return;
      this.loading = true;
      // 模拟请求
      const next = [];
      for (let i = 0; i < 8; i++) {
        const seed = (this.page - 1) * 8 + i + 1;
        next.push({
          image: `https://picsum.photos/seed/${seed}/400/${300 + (seed % 5) * 80}`,
          title: '标题' + seed,
          author: '作者'
        });
      }
      setTimeout(() => {
        this.list = this.list.concat(next);
        this.page++;
        this.loading = false;
      }, 300);
    },
    onItemTap(item) {
      uni.showToast({ title: item.title, icon: 'none' });
    }
  }
};
</script>

多列布局

<sl-waterfall :list="list" :column-count="3" :column-gap="12" :row-gap="12" />

关闭渐进渲染（数据量小时）

<sl-waterfall :list="list" :enable-virtual="false" />

调用返回顶部

<sl-waterfall ref="waterfall" :list="list" />

<script>
export default {
  methods: {
    backToTop() {
      this.$refs.waterfall.scrollToTop();
    }
  }
};
</script>

注意事项

1. 小程序图片域名：网络图片需在 小程序后台 → 开发管理 → 服务器域名 加入合法域名（开发期可在开发者工具勾选「不校验合法域名」）；H5 无此限制。

2. easycom 配置：若目录结构为 components/SL-WX-Compent-Waterfall/index.vue（目录名与文件名不一致），需在 pages.json 配置自定义 easycom 规则：

   "easycom": {
    "custom": {
      "^sl-waterfall": "@/components/SL-WX-Compent-Waterfall/index.vue"
    }
   }

3. height 必须为确定值：scroll-view 需明确高度才能滚动，如 100vh、600rpx，不能用 auto。
4. 渐进渲染与虚拟列表区别：本组件用渐进渲染（已渲染永不删除），滚动时无 DOM 删除 → 无抖动，DOM 量随浏览量增长。如需固定 DOM 数量可自行改为虚拟列表方案。