Waterfall 瀑布流
高性能 Masonry 布局组件。核心算法通过最短列平衡计算实现，支持图片预加载感知、加载状态、空视图及响应式断点。
基础用法
瀑布流内容卡片 #1
采用最短列平衡算法，视觉更均匀。
瀑布流内容卡片 #5
交错动画入场。
瀑布流内容卡片 #2
基础演示节点。
瀑布流内容卡片 #6
基础演示节点。
瀑布流内容卡片 #3
支持图片加载感知。
瀑布流内容卡片 #4
响应式自动对齐。
最短列平衡算法
交互状态
瀑布流内容卡片 #1
瀑布流内容卡片 #5
瀑布流内容卡片 #2
瀑布流内容卡片 #6
瀑布流内容卡片 #3
瀑布流内容卡片 #4
加载与空状态
在 Nuxt 中使用
Waterfall 组件完全支持 Nuxt 3/4 的 SSR 渲染。在 Nuxt 项目中使用时，组件会自动导入，无需手动注册。
瀑布流内容卡片 #1
瀑布流内容卡片 #5
瀑布流内容卡片 #2
瀑布流内容卡片 #6
瀑布流内容卡片 #3
瀑布流内容卡片 #4
Nuxt 中使用
SSR 注意事项：
- ✅ 完美支持首屏静态渲染，避免布局抖动
- ✅ 响应式列数在客户端激活后自动适配容器宽度
商用案例：电商分页模式
暂无数据
电商分页加载
商用案例：无限加载模式
暂无数据
无限加载流
API
Props
| 属性名 | 说明 | 类型 | 默认值 |
|---|---|---|---|
items | 数据源数组 | T[] | [] |
cols | 列数配置。支持数字或响应式对象 | number | WaterfallCols | 2 |
gap | 卡片之间的间距 (px) | number | 16 |
loading | 是否处于加载中状态 | boolean | false |
height-property | 用于平衡布局的高度字段名。若提供，则激活最短列平衡算法 | string | 'height' |
img-selector | 内部图片选择器。图片加载后会自动触发布局重计算 | string | 'img' |
animation | 是否开启节点入场动画 | boolean | true |
delay | 动画累加延迟基数 (ms) | number | 100 |
row-key | 节点唯一标识字段名 | string | 'id' |
responsive | 是否自动监听容器宽度变化并适配 | boolean | true |
WaterfallCols 类型定义
ts
interface WaterfallCols {
xs?: number // < 576px
sm?: number // >= 576px
md?: number // >= 768px
lg?: number // >= 992px
xl?: number // >= 1200px
}Slots
| 插槽名 | 说明 | 参数 |
|---|---|---|
default | 自定义节点渲染内容 | { item: T, index: number, column: number } |
loading | 自定义初始加载时的占位内容（通常用于骨架屏） | - |
empty | 自定义空数据状态展示内容 | - |
loading-overlay | 自定义刷新态（有旧数据时）的蒙层内容 | - |
Expose
| 方法名 | 说明 | 类型 |
|---|---|---|
layout | 手动触发布局重计算（如容器尺寸发生变化但未被感知时） | () => void |
主题变量
组件支持通过覆盖以下 CSS 变量来自定义局部样式：
| 变量名 | 说明 | 默认值 |
|---|---|---|
--yh-bg-color-page | 骨架屏节点的背景颜色 | var(--yh-bg-color-page) |
--yh-color-text-secondary | 空状态文字颜色 | var(--yh-text-color-secondary) |
--yh-color-primary | 刷新蒙层加载器的旋转主色 | var(--yh-color-primary) |
--yh-color-primary-light-8 | 刷新蒙层加载器的轨道底色 | var(--yh-color-primary-light-8) |