tudou-waterfall

一个高性能的 Vue 3 瀑布流组件，支持虚拟滚动、响应式布局和动态高度。

特性

• 🚀 虚拟滚动 - 只渲染可见区域的内容，大幅提升性能
• 📱 响应式布局 - 支持断点配置，自动适配不同屏幕尺寸
• 📏 动态高度 - 自动计算 item 高度，支持图片懒加载后的高度变化
• 🎯 TypeScript - 完整的类型支持
• 🪶 轻量级 - 零依赖（除 Vue 3 外）

安装

npm install tudou-waterfall
# 或
yarn add tudou-waterfall
# 或
pnpm add tudou-waterfall

使用

全局注册

import { createApp } from 'vue'
import TudouWaterfall from 'tudou-waterfall'
import 'tudou-waterfall/style.css'

const app = createApp(App)
app.use(TudouWaterfall)

局部导入

<script setup>
import { Waterfall } from 'tudou-waterfall'
import 'tudou-waterfall/style.css'

const items = [
  { id: 1, title: 'Item 1', image: 'https://example.com/1.jpg' },
  { id: 2, title: 'Item 2', image: 'https://example.com/2.jpg' },
  // ...
]
</script>

<template>
  <Waterfall :items="items" :cols="4" :gap="16">
    <template #default="{ item }">
      <div class="card">
        <img :src="item.image" :alt="item.title" />
        <h3>{{ item.title }}</h3>
      </div>
    </template>
  </Waterfall>
</template>

API

Props

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | items | any[] | [] | 数据列表（必填） | | cols | number | 0 | 列数，0 表示使用响应式断点 | | gap | number | 15 | 列间距（像素） | | estimatedHeight | number | 220 | 预估 item 高度，用于初始布局计算 | | overscan | number | 600 | 视口外额外渲染的像素范围 | | breakpoints | WaterfallBreakpoint[] | 见下表 | 响应式断点配置 | | defaultCols | number | 2 | 无断点匹配时的默认列数 |

默认断点配置

[
  { minWidth: 1400, cols: 9 },
  { minWidth: 1200, cols: 8 },
  { minWidth: 900,  cols: 7 },
  { minWidth: 700,  cols: 6 },
  { minWidth: 500,  cols: 5 },
]

事件

| 事件名 | 说明 | |--------|------| | reflow | 布局重新计算后触发 |

类型定义

interface WaterfallBreakpoint {
  minWidth: number
  cols: number
}

interface WaterfallProps {
  items: any[]
  cols?: number
  gap?: number
  estimatedHeight?: number
  overscan?: number
  breakpoints?: WaterfallBreakpoint[]
  defaultCols?: number
}

示例

固定列数

<Waterfall :items="items" :cols="6" :gap="15">
  <template #default="{ item }">
    <div class="item">{{ item.title }}</div>
  </template>
</Waterfall>

响应式布局

<Waterfall 
  :items="items" 
  :breakpoints="[
    { minWidth: 1600, cols: 6 },
    { minWidth: 1200, cols: 4 },
    { minWidth: 768, cols: 3 },
    { minWidth: 0, cols: 2 },
  ]"
  :defaultCols="2"
>
  <template #default="{ item }">
    <div class="item">{{ item.title }}</div>
  </template>
</Waterfall>

图片瀑布流

<script setup>
import { Waterfall } from 'tudou-waterfall'
import 'tudou-waterfall/style.css'

const images = [
  { id: 1, src: 'https://picsum.photos/300/400', title: 'Image 1' },
  { id: 2, src: 'https://picsum.photos/300/500', title: 'Image 2' },
  // ...
]
</script>

<template>
  <Waterfall :items="images" :cols="4" :gap="16">
    <template #default="{ item }">
      <div class="image-card">
        <img :src="item.src" :alt="item.title" loading="lazy" />
        <p>{{ item.title }}</p>
      </div>
    </template>
  </Waterfall>
</template>

<style>
.image-card {
  border-radius: 8px;
  overflow: hidden;
  background: #f5f5f5;
}

.image-card img {
  width: 100%;
  display: block;
}

.image-card p {
  padding: 8px;
  margin: 0;
}
</style>

注意事项

1. 必须导入样式文件：import 'tudou-waterfall/style.css'
2. item 高度：组件会自动监听 item 元素的高度变化，但建议设置合理的 estimatedHeight 以优化初始渲染
3. 唯一 key：items 数组中的每个 item 应该有一个唯一的标识字段（如 id），用于 Vue 的 key 绑定

相关链接

• GitHub 仓库
• 问题反馈

License

MIT