@vascent/react-waterfall-virtual-list NPM

# VirtualWaterFall 虚拟瀑布流组件

一个高性能的虚拟化瀑布流布局组件，支持动态高度计算、滚动加载和自定义渲染，适用于图片/卡片类数据的高性能渲染场景。

## 特性
- 🚀 **虚拟滚动** - 仅渲染可视区域内的元素，超大数据量也能流畅运行
- 📐 **自适应布局** - 自动根据容器宽度计算列宽，响应式布局
- 🧮 **动态高度** - 支持同步/异步计算卡片高度
- ♾️ **无限滚动** - 滚动到底部自动触发数据加载
- 🎨 **高度定制** - 可自定义卡片样式、加载状态和渲染逻辑

## 安装
```bash
npm install @vascent/react-waterfall-virtual-list

快速开始

import { VirtualWaterFall } from '@vascent/react-waterfall-virtual-list'

const App = () => {
  const [data, setData] = useState<BaseInfo[]>([])

  // 加载更多数据
  const loadMore = useCallback(() => {
    fetchData().then(newData => setData(prev => [...prev, ...newData]))
  }, [])

  return (
    <VirtualWaterFall
      list={data}
      columns={4}
      gap={8}
      cardClass="custom-card"
      reachBottom={loadMore}
      calcCardHeight={async (width, imgHeight, item) => {
        // 自定义高度计算逻辑
        return await calculateDynamicHeight(item)
      }}
      renderItem={({ item }) => (
        <div style={item.style}>
          <img 
            src={item.imageUrl}
            height={item.style.imageHeight}
          />
          <h3>{item.title}</h3>
        </div>
      )}
      renderLoading={() => <div>Loading...</div>}
    />
  )
}

API 文档

Props

属性	类型	必填	默认值	说明
list	`T[]`	是	-	数据源数组，元素需继承 BaseInfo
columns	number	否	5	瀑布流列数
gap	number	否	10	卡片间距（单位：px）
scrollSpeedFactor	number	否	0.3	滚动速度因子，影响滚动过程中的白屏，默认为 0.3，值越大滚动越快
cardClass	string	否	-	卡片容器类名
reachBottom	() => void	否	-	滚动到底部回调函数
calcCardHeight	`(cardWidth: number, imageHeight: number, item: T) => Promise<number>`	否	-	异步计算卡片高度函数
renderItem	`({ item: T & { style: PositionType } }) => JSX.Element`	否	-	自定义卡片渲染函数
renderLoading	`() => JSX.Element \\| null`	否	-	自定义加载状态组件

类型定义

type BaseInfo = {
  id: string
  width: number   // 原始图片/卡片宽度
  height: number  // 原始图片/卡片高度
}

type PositionType = {
  x: number       // X轴位置
  y: number       // Y轴位置
  width: number   // 实际渲染宽度
  height: number  // 实际渲染高度
  imageHeight: number // 图片显示高度
}

注意事项

数据项要求：每个数据项必须包含 id, width, height 属性
图片预处理：建议预先获取图片原始尺寸，或在加载完成后触发重新布局
性能优化：大数据量时建议配合防抖使用 reachBottom
高度计算：当使用异步 calcCardHeight 时，请确保返回 Promise
滚动体验：容器需要具有明确的高度（通过外部 CSS 设置）

工作原理

布局计算：根据容器宽度和列数计算每列宽度
位置分配：始终将新元素添加到当前高度最小的列
滚动优化：自定义滚动处理实现平滑滚动体验

开发建议

// 推荐的数据结构示例
interface CardData extends BaseInfo {
  imageUrl: string
  title: string
  // 其他自定义字段...
}

// 推荐的高度计算模式
const calcHeight = async (width, imgHeight, item) => {
  const textHeight = await measureTextHeight(item.description, width)
  return imgHeight + textHeight + 20 // 总高度 = 图片高度 + 文字高度 + 边距
}