Vue3 Masonry Plus 瀑布流组件技术文档

1. 安装指南

1.1 环境要求

• Node.js 14.x 或更高版本
• Vue3 项目环境
• npm/yarn 包管理器

1.2 安装方式

通过npm安装

npm install vue3-masonry-plus

通过yarn安装

yarn add vue3-masonry-plus

本地开发环境搭建

cd demo
npm install
npm run dev

2. 项目使用说明

2.1 基本使用

在Vue组件中引入并使用瀑布流组件：

<template>
  <Waterfall
    :list="list"
    :width="200"
    :columns="4"
    :gutter="10"
    animation-effect="fadeIn"
  >
    <template #item="{ item }">
      <div class="card">
        <LazyImg :url="item.src" />
        <div class="info">
          <h3>{{ item.name }}</h3>
        </div>
      </div>
    </template>
  </Waterfall>
</template>

<script setup>
import { Waterfall, LazyImg } from 'vue3-masonry-plus'
import { ref } from 'vue'

const list = ref([
  { id: '1', src: 'image1.jpg', name: 'Image 1' },
  { id: '2', src: 'image2.jpg', name: 'Image 2' }
])
</script>

2.2 功能特性

1. 响应式布局：自动适配PC和移动端不同屏幕尺寸
2. 动画效果：支持animate.css的所有动画效果
3. 图片懒加载：内置高性能图片懒加载功能
4. 图片预览：支持点击图片查看大图
5. 高性能渲染：优化大量图片加载场景

3. API使用文档

3.1 Waterfall组件属性

属性名	类型	默认值	说明
list	Array	[]	数据源数组
width	Number	200	项目基础宽度(px)
columns	Number	3	瀑布流列数
gutter	Number	10	项目间距(px)
animationEffect	String	'fadeIn'	动画效果名称
animationDuration	Number	1000	动画持续时间(ms)
animationDelay	Number	300	动画延迟时间(ms)
lazyload	Boolean	true	是否启用图片懒加载

3.2 LazyImg组件属性

属性名	类型	默认值	说明
url	String	''	图片地址
previewSrcList	Array	[]	预览图片列表
previewIcon	String	''	自定义预览图标地址

3.3 组件方法

// 强制更新布局
waterfallRef.value?.renderer()

// 清空并重新加载
waterfallRef.value?.clearAndReload()

3.4 插槽使用

<template #item="{ item, index }">
  <!-- 自定义项目内容 -->
  <div class="custom-item">
    <img :src="item.src" />
    <p>{{ item.title }}</p>
  </div>
</template>

4. 项目安装方式详解

4.1 全局注册方式

import { createApp } from 'vue'
import App from './App.vue'
import MasonryPlus from 'vue3-masonry-plus'

const app = createApp(App)
app.use(MasonryPlus)
app.mount('#app')

4.2 局部组件注册方式

<script setup>
import { Waterfall, LazyImg } from 'vue3-masonry-plus'
</script>

4.3 样式配置

在项目中引入animate.css动画库(可选)：

import 'animate.css/animate.min.css'

4.4 注意事项

1. 确保图片地址有效且可访问
2. 合理设置列数和项目宽度以获得最佳效果
3. 大量数据建议配合分页加载使用
4. 动画效果需要额外引入animate.css