useVirtualList Hook 使用说明

功能概述

useVirtualList 是一个高性能的虚拟列表分页 Hook，专为大数据量列表渲染优化设计，支持无限滚动、分页加载和防抖刷新等功能。

基础用法

const { dataSource, loading, refresh } = useVirtualList(
    async ({ offset, limit }) => {
        const res = await fetch(`/api/data?offset=${offset}&limit=${limit}`);
        return {
            dataSource: res.data,
            total: res.totalCount,
        };
    },
    [dependency], // 依赖项
);

核心 API

输入参数

参数	类型	必填	说明
server	(params: IServerParams) => Promise>	是	数据获取函数
deps	DependencyList	否	依赖项数组
option	IInfoOption	否	配置选项

配置选项 (IInfoOption)

interface IInfoOption<T> {
    isReady?: boolean; // 是否准备就绪（默认true）
    dataSource?: T[]; // 初始数据（默认[]）
    current?: number; // 初始页码（默认1）
    pageSize?: number; // 初始每页条数（默认PAGE_SIZE）
}

服务端参数 (IServerParams)

interface IServerParams {
    offset: number; // 数据偏移量
    limit: number; // 每页条数
    current: number; // 当前页码
}

服务端返回值 (IInfoBack)

interface IInfoBack<T> {
    dataSource: T[]; // 数据列表
    total: number; // 总条数
}

返回值

属性	类型	说明
dataSource	T[]	当前数据列表
loading	boolean	加载状态
isFirstComplete	boolean	是否完成首次加载
paginationProps	{ current, pageSize, total }	分页信息
refresh	(reset?: boolean) => Promise	刷新函数
debounceRefresh	(reset?: boolean) => void	防抖刷新函数
setDataSource	(data: T[]) => void	手动设置数据源
setTotal	(total: number) => void	手动设置总数

高级用法

无限滚动列表

const { dataSource, loading, refresh } = useVirtualList(fetchData);

<List data={dataSource} onScrollToBottom={() => !loading && refresh()} renderItem={/*...*/} />;

条件触发加载

const { debounceRefresh } = useVirtualList(fetchData, [searchQuery]);

// 搜索条件变化时防抖刷新
useEffect(() => {
    debounceRefresh(true);
}, [searchQuery]);

手动控制数据

const { setDataSource, setTotal } = useVirtualList(fetchData);

const handleAddItem = newItem => {
    setDataSource(prev => [...prev, newItem]);
    setTotal(prev => prev + 1);
};