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，请按照以下步骤操作：

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

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

2. 登录到 npm：

   npm login

3. 发布包：

   npm publish

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

   npm publish --access public

许可证

MIT