---
url: /components/waterfall.md
---
# Waterfall 瀑布流

`EvWaterfall` 多列瀑布流：条目按「最短列优先」分发，列高随内容比例自动均衡。
与 [ImageWall 图片墙](./image-wall) 的分工——ImageWall 是统一画幅的均匀网格，
Waterfall 让每张图保持自己的高宽比，错落排布。
默认渲染图片卡，点击打开 [ImagePreview 图片预览](./image-preview) 灯箱（可关）；
`#item` 作用插槽可完全接管单元格，实现任意内容的瀑布流。

## 基础用法

```vue
<script setup>
const photos = [
  { src: '/images/ridge.jpg', alt: '山脊线' },
  { src: '/images/mist.jpg', alt: '雾中山林' },
  { src: '/images/forest.jpg', alt: '林间光', caption: '林间光' },
]
</script>

<template>
  <EvWaterfall :items="photos" :columns="3" />
</template>
```

## 列数与间距

```vue
<EvWaterfall :items="photos" :columns="4" :gap="10" :radius="8" />
```

## 标题蒙层与声明比例

```vue
<EvWaterfall
  :items="[
    { src: '/images/ridge.jpg', caption: '山脊线', ratio: 1.25 },
    { src: '/images/field.jpg', caption: '原野', ratio: 0.56 },
  ]"
/>
```

## 自定义内容瀑布流

```vue
<EvWaterfall :items="notes" :columns="3" :preview="false">
  <template #item="{ item }">
    <article class="note">
      <h3>{{ item.title }}</h3>
      <p>{{ item.text }}</p>
    </article>
  </template>
</EvWaterfall>
```

## API

### Props

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| items | 条目列表：url 字符串或 `{ src, alt, caption, ratio, width, height }`（ratio 为高/宽） | array | `[]` |
| columns | 列数 | number | `3` |
| gap | 间距（px，列距与行距同值） | number | `14` |
| radius | 圆角（px） | number | `12` |
| preview | 点击打开预览灯箱 | boolean | `true` |

### 事件

| 事件 | 说明 |
| --- | --- |
| select | 点击图片时触发，参数为 `(item, index)` |

### 插槽

| 插槽 | 说明 |
| --- | --- |
| item | 单元格内容，参数为 `{ item, index }`；使用后不再渲染默认图片卡 |