Skip to content

vue3 瀑布流插件,支持 PC 和移动端,支持 animate 的所有动画效果,支持图片懒加载

Notifications You must be signed in to change notification settings

heikaimu/vue3-waterfall-plugin

Repository files navigation

Vue3 瀑布流组件

Vue3瀑布流插件支持PC和移动端,包含Animate的各种动画效果以及图片懒加载功能。

安装

npm install vue-waterfall-plugin-next

使用

import { LazyImg, Waterfall } from 'vue-waterfall-plugin-next'
import 'vue-waterfall-plugin-next/dist/style.css'

// 数据
data: {
  list: [
    {
      src: "xxxx.jpg",
      ...
    }
    ...
  ]
}
<Waterfall :list="list">
  <!-- v2.6.0之前版本插槽数据获取 -->
  <!-- <template #item="{ item, url, index }"> -->
  <!-- 新版插槽数据获取 -->
  <template #default="{ item, url, index }">
    <div class="card">
      <LazyImg :url="url" />
      <p class="text">这是具体内容</p>
    </div>
  </template>
</Waterfall>

Props 参数

参数名 类型 默认值 描述
list Array [] 列表数据
rowKey String id 数据唯一的字段,比如列表里面的id, 如果要删除卡片,该字段为必填
imgSelector String src 图片字段选择器,如果层级较深,使用 xxx.xxx.xxx 方式
width Number 200 卡片在 PC 上的宽度, 与breakpoints一样可以确定卡片的宽度以及每行个数, 但breakpoints优先级高于width
breakpoints Object {
1200:{rowPerView:3},
800:{rowPerView:2},
500:{rowPerView:1}
}
类似css的@media, 定义不同容器宽度下每行卡片个数,主要用于对移动端的适配
gutter Number 10 卡片之间的间隙
hasAroundGutter Boolean true 容器四周是否有 gutter 边距
posDuration Number 300 卡片移动到正确位置的动画时间
animationPrefix String animate__animated 详情见下文《动画样式》
animationEffect String fadeIn 卡片入场动画,默认只有 fadeIn,引入 animation.css 后可使用其他动画
animationDuration Number 1000 卡片入场动画执行时间(单位毫秒),该动画时间只影响卡片重拍的时间,一般情况都不用修改,如果想要修改飞入动画的执行时间,见下文
animationDelay Number 300 卡片入场动画延迟(单位毫秒)
animationCancel Boolean false 取消动画,开启后,所有动画属性都不生效
backgroundColor String #ffffff 背景颜色
loadProps Object loadProps 懒加载图片组件的属性设置,详情见下文《懒加载属性》
lazyload Boolean true 是否开启懒加载
crossOrigin Boolean true 图片加载是否开启跨域
delay Number 300 布局刷新的防抖时间,默认 300ms 内没有再次触发才刷新布局。(图片加载完成;容器大小、listwidthgutterhasAroundGutter变化时均会触发刷新)
align String center 卡片的对齐方式,可选值为:left,center,right

WaterfallList 方法

方法名字 返回值类型 描述
afterRender 本次卡片坐标计算完成并且移动到了对应位置(列表渲染的过程可能会多次触发,比如有一张图片加载完成就会重新计算位置)

LazyImg 方法

方法名字 返回值类型 描述
load string img标签的load函数
success string 图片加载成功
error string 图片加载失败

强制更新

<Waterfall ref="waterfall"></Waterfall>

const waterfall = ref(null)
waterfall.value.renderer()

WaterFall组件向外暴露了一个renderer函数,可以直接调用,该方法可以主动重绘列表,使用其他懒加载图片组件的回调函数里可以调用这个renderer来重绘。

动画样式

首先需要明白,这里的动画指的是数据插入时的动画,比如第一次加载数据已经加载更多的时候的一个插入动画。 想要使用动画必须引入animate.css或者定义一个动画className

  1. 如果引入了animate.css,并且版本是4.x.x及以上,可以不作任何处理
  2. 如果引入了animate.css,并且是老版本则需要将animationPrefix设置为animated
  3. 如果不想引入animate.css,想使用插件默认的fadeIn效果,需要手动加入下面的样式
.animate__animated {
  animation-fill-mode: both;
  animation-duration: 1s;
}

animation-duration 决定了卡片的飞入动画执行时间!!!如果引入了animate.css并且想改变飞入动画的时间,则需要手动去修改animation-duration的值。

断点详细配置

breakpoints默认值,当此属性生效时,width失效

breakpoints: {
  1200: {
    // when wrapper width < 1200
    rowPerView: 3,
  },
  800: {
    // when wrapper width < 800
    rowPerView: 2,
  },
  500: {
    // when wrapper width < 500
    rowPerView: 1,
  },
}

懒加载属性

import loading from 'assets/loading.png'
import error from 'assets/error.png'
loadProps: {
  loading,
  error,
  ratioCalculator: (width, height) => {
    // 我设置了最小宽高比
    const minRatio = 3 / 4;
    const maxRatio = 4 / 3;
    // 获取当前图片的比例
    const curRatio = width / height;
    // 如果当前图片比列不在此范围内,我们取最小或者最大值
    if (curRatio < minRatio) {
      return minRatio;
    } else if (curRatio > maxRatio) {
      return maxRatio;
    } else {
      return curRatio;
    }
  }
}
  1. loading 是图片加载时候的等待图
  2. error 是图片加载失败后的占位图
  3. ratioCalculator 是一个设置懒加载图片展示比列的方法,当我们不自定义的时候,懒加载最终出来的图比列就是图片本身,但是有时候我们的图片尺寸可能长宽比较极限,这样出来样式不太美观,我们都可以用这个方法按照我们的想法进行设置。

自定义懒加载图片样式

.lazy__img[lazy=loading] {
  padding: 5em 0;
  width: 48px;
}

.lazy__img[lazy=loaded] {
  width: 100%;
}

.lazy__img[lazy=error] {
  padding: 5em 0;
  width: 48px;
}

About

vue3 瀑布流插件,支持 PC 和移动端,支持 animate 的所有动画效果,支持图片懒加载

Topics

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published