vue-waterfall-plus

Vue Waterfall Plus

一个响应式瀑布流组件，支持 Vue 3，具有懒加载、上拉加载更多和下拉刷新功能。

安装

npm install vue-waterfall-plus
# 或
yarn add vue-waterfall-plus
# 或
pnpm add vue-waterfall-plus

使用方法

全局注册

// main.js / main.ts
import { createApp } from 'vue'
import App from './App.vue'
import VueWaterfallPlus from 'vue-waterfall-plus'
// 导入样式
import 'vue-waterfall-plus/dist/style.css'

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

局部注册

<template>
  <WaterfallList
    :list="list"
    :loading="isLoading"
    :refreshing="isRefreshing"
    :has-more="hasMore"
    @load-more="loadMore"
    @refresh="refresh"
  />
</template>

<script setup>
import { ref } from 'vue'
import { WaterfallList } from 'vue-waterfall-plus'
// 导入样式
import 'vue-waterfall-plus/dist/style.css'

const list = ref([])
const isLoading = ref(false)
const isRefreshing = ref(false)
const hasMore = ref(true)
const page = ref(1)

async function loadMore() {
  if (isLoading.value) return
  isLoading.value = true
  
  try {
    // 模拟异步请求
    const newItems = await fetchData(page.value)
    list.value = [...list.value, ...newItems]
    page.value++
    hasMore.value = page.value < 5 // 示例：只有5页数据
  } finally {
    isLoading.value = false
  }
}

async function refresh() {
  if (isRefreshing.value) return
  isRefreshing.value = true
  
  try {
    // 模拟异步请求
    page.value = 1
    const newItems = await fetchData(page.value)
    list.value = newItems
    hasMore.value = true
  } finally {
    isRefreshing.value = false
  }
}

// 模拟数据获取
function fetchData(page) {
  return new Promise((resolve) => {
    setTimeout(() => {
      const items = Array(10).fill(0).map((_, index) => ({
        id: page * 100 + index,
        image: `https://picsum.photos/id/${page * 10 + index}/400/300`,
        text: `Item ${page * 10 + index}`,
        height: Math.floor(Math.random() * 200) + 200
      }))
      resolve(items)
    }, 1000)
  })
}

// 初始加载
loadMore()
</script>

使用插槽自定义内容

<template>
  <WaterfallList
    :list="list"
    :loading="isLoading"
    :has-more="hasMore"
    @load-more="loadMore"
  >
    <!-- 自定义每个项目 -->
    <template #item="{ item }">
      <div class="custom-item">
        <img :src="item.image" :alt="item.text" loading="lazy" />
        <div class="custom-content">
          <h3>{{ item.title }}</h3>
          <p>{{ item.description }}</p>
        </div>
      </div>
    </template>
    
    <!-- 自定义加载中状态 -->
    <template #loading>
      <div class="custom-loading">数据加载中...</div>
    </template>
    
    <!-- 自定义没有更多数据状态 -->
    <template #nomore>
      <div class="custom-nomore">已经到底啦~</div>
    </template>
  </WaterfallList>
</template>

API

Props

属性名	类型	默认值	说明
list	Array<WaterfallItem>	[]	瀑布流数据列表
loading	boolean	false	是否正在加载数据
refreshing	boolean	false	是否正在刷新数据
hasMore	boolean	true	是否还有更多数据
height	string	'100vh'	瀑布流容器高度
gap	number	12	项目之间的间距
padding	number	12	容器内边距
borderRadius	number	12	项目圆角大小
loadingText	string	'加载中...'	加载中文本
refreshText	string	'刷新中...'	刷新中文本
noMoreText	string	'没有更多了'	没有更多数据文本
loadingDistance	number	100	触发加载更多的距离

事件

事件名	参数	说明
load-more	-	触发加载更多数据
refresh	-	触发刷新数据
scroll	{ scrollTop: number, scrollLeft: number }	滚动事件

插槽

插槽名	插槽作用域	说明
item	{ item: WaterfallItem }	自定义每个项目的内容
loading	-	自定义加载中状态
refresh	-	自定义刷新中状态
nomore	-	自定义没有更多数据状态

类型定义

interface WaterfallItem {
  id: number | string;
  image: string;
  text: string;
  height: number;
  [key: string]: number | string | boolean | undefined | null;
}

发布到 npm

如果你想将此组件发布到 npm，请按照以下步骤操作：

• 更新 package.json 中的个人信息：

  • name: 确保包名称唯一
  • author: 添加你的名字和邮箱
  • repository: 更新为你的 GitHub 仓库地址
  • homepage: 更新为你的项目主页

• 登录到 npm：

  npm login
  

• 发布包：

  npm publish
  

• 如果你想发布到私有仓库或使用范围包，可以这样：

  npm publish --access public
  

许可证

MIT