Vue3 瀑布流组件
一个基于Vue3的瀑布流组件，支持PC和移动端，支持animate动画效果，内置图片懒加载功能。
预览
运行项目
cd demo
# 安装依赖
npm install
# 运行项目
npm run dev
特性
- 🚀 基于Vue3和TypeScript开发
- 📱 响应式布局，支持PC和移动端
- 🎨 支持animate.css的所有动画效果
- 🖼️ 内置图片懒加载功能
- 🔄 自动计算布局
- ⚡ 高性能，支持大量图片加载
- 🔍 支持图片预览功能
安装
npm install vue3-masonry-plus
# or
yarn add vue3-masonry-plus
基本使用
<template>
<Waterfall
ref="waterfallRef"
:list="list"
:width="200"
:columns="4"
:gutter="10"
animation-effect="fadeIn"
:animation-duration="1000"
:animation-delay="300"
background-color="#f5f5f5"
>
<template #item="{ item }">
<div class="card">
<LazyImg :url="item.src" :preview-src-list="[item.src]" :preview-icon="previewIcon" />
<div class="info">
<h3>{{ item.name }}</h3>
</div>
</div>
</template>
</Waterfall>
</template>
<script setup lang="ts">
import { Waterfall, LazyImg } from 'vue3-masonry-plus'
import { ref } from 'vue'
const waterfallRef = ref()
const previewIcon = 'path/to/preview-icon.png' // 自定义预览图标
const list = [
{ id: '1', src: 'image1.jpg', name: 'Image 1' },
{ id: '2', src: 'image2.jpg', name: 'Image 2' },
// ...
]
// 强制更新瀑布流布局
const forceUpdate = () => {
waterfallRef.value?.renderer()
}
// 清空并重新加载数据
const clearAndReload = () => {
waterfallRef.value?.clearAndReload()
}
</script>
组件属性
Waterfall 组件
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| list | Array | [] | 瀑布流数据列表 |
| rowKey | String | 'id' | 列表项的唯一标识 |
| imgSelector | String | 'src' | 图片地址在数据项中的属性名 |
| width | Number | 200 | 卡片的基础宽度 |
| columns | Number | 3 | 瀑布流列数 |
| gutter | Number | 10 | 卡片之间的间距 |
| hasAroundGutter | Boolean | true | 是否启用外围间距 |
| animationPrefix | String | 'animate__animated' | 动画类名前缀 |
| animationEffect | String | 'fadeIn' | 动画效果名称 |
| animationDuration | Number | 1000 | 动画持续时间(ms) |
| animationDelay | Number | 300 | 动画延迟时间(ms) |
| backgroundColor | String | '#fff' | 容器背景色 |
| lazyload | Boolean | true | 是否启用图片懒加载 |
| loadProps | Object | {} | 懒加载配置项 |
| crossOrigin | Boolean | true | 是否启用跨域加载 |
| delay | Number | 300 | 布局更新延迟时间(ms) |
LazyImg 组件
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| url | String | '' | 图片地址 |
| loading | String | - | 加载中显示的图片地址 |
| errorImg | String | - | 加载失败显示的图片地址 |
| previewSrcList | Array | [] | 开启图片预览功能的图片列表 |
| previewIcon | String | '' | 自定义预览图标的图片地址 |
| hideOnClickModal | Boolean | false | 是否可以通过点击遮罩层关闭预览 |
插槽
Waterfall 组件
| 插槽名 | 说明 | 作用域参数 |
|---|---|---|
| item | 自定义列表项内容 | { item: 列表项数据, index: 索引, url: 图片地址 } |
事件
Waterfall 组件
| 方法名 | 说明 | 参数 |
|---|---|---|
| renderer | 强制更新瀑布流布局，用于在数据变化后手动触发重新计算和渲染 | 无 |
| clearAndReload | 清空当前数据并重新加载渲染，用于解决特定场景下的布局问题 | 无 |
注意事项
- 确保提供的图片地址是有效的
- 建议设置合适的基础宽度和间距，以获得最佳的视觉效果
- 动画效果基于animate.css，使用前需要引入相应的样式文件
- 图片预览功能基于element-plus的ElImage组件，支持查看大图和图片切换
License
MIT
项目架构
架构图
目录结构
lib/
├── assets/ # 静态资源文件
│ ├── loadError.png # 图片加载错误占位图
│ └── loading.gif # 图片加载中占位图
├── components/ # 组件目录
│ ├── LazyImg.vue # 图片懒加载组件
│ └── Waterfall.vue # 瀑布流主组件
├── types/ # TypeScript类型定义
│ ├── images.d.ts # 图片相关类型
│ ├── jsx.d.ts # JSX类型声明
│ ├── lazy.d.ts # 懒加载相关类型
│ ├── shims-vue.d.ts # Vue组件类型声明
│ ├── util.d.ts # 工具函数类型
│ └── waterfall.d.ts # 瀑布流组件类型
├── use/ # 组合式函数目录
│ ├── index.ts # 组合式函数入口
│ ├── useCalculateCols.ts # 列数计算逻辑
│ └── useLayout.ts # 布局计算逻辑
└── utils/ # 工具函数目录
├── Lazy.ts # 懒加载核心实现
├── dom.ts # DOM操作相关
├── itemWidth.ts # 项目宽度计算
├── loader.ts # 资源加载器
└── util.ts # 通用工具函数
keywords
vue3 typescript waterfall masonry 瀑布流 懒加载 图片预览 响应式 动画效果