usePagingList

Tags:

ProUtilities

DepCollect

这个 Hook 自 v1.7.0 版本起可用。

一个用来处理分页列表的 Hook，集成了 useQuery、useForm、useMultiSelect、usePagination 等的功能。

拥有以下特性：

基于 useQuery，内置了众多数据请求功能，可按需开启
使用 useForm 自动管理表单状态，提供诸多状态和生命周期，自动请求等
使用 usePagination 自动管理分页状态，提供分页事件和操作，内置状态监听，自动重请求
使用 useMultiSelect 针对列表数据进行多选，支持全选、反选、清空等

场景

usePagingList = useQuery 特性 + 分页状态与管理 + 表单查询（可选） + 多选操作（可选）

演示

用法

const {
  form, pagination, selection,
  list, refresh, loading
} = usePagingList(options)

// 传入一个接受 page, pageSize 分页参数的函数，它需要返回一个数据列表
// 在这个函数里面使用 setTotal 来设置数据总数，以便分页器能够正确显示总数
const { form, pagination, selection, list, refresh, loading } = usePagingList(
  {
    fetcher: async (params) => {
      const { page, pageSize, form } = params
      const { list, total } = await fetchPaginationList({ page, pageSize })
      setTotal(total)
      return list
    }.
    // 传入 useQuery 的配置项，如 refreshInterval 进行定时刷新
    query: { refreshInterval: 3_000 },
    // 传入 useForm 的配置项，如 initialValues 进行表单初始化
    form: { initialValues: { name: '', select: '' } },
    // 传入 usePagination 的配置项，如设置默认页码和每页显示数量
    pagination: { page: 1, pageSize: 10 },
    // 声明立即查询的表单字段，当表单字段变化时，会自动触发查询
    immediateQueryKeys: ['select'],
  },
)

源码

点击下方链接跳转 GitHub 查看源代码。

🪝 Hook 🎨 Demo 📄 Document

API

const {
  form, pagination, selection,
  list, refresh, loading
} = usePagingList(options)

配置项 Options

export interface UsePagingListFetcherParams<FormState extends object, Data> {
  /**
   * 上次请求的数据
   */
  previousData: Data | undefined
  /**
   * 当前页码
   */
  page: number
  /**
   * 每页显示数量
   */
  pageSize: number
  /**
   * 表单状态
   */
  form: FormState
  /**
   * 设置数据总数
   */
  setTotal: ReactSetState<number>
}

export type UsePagingListFetcher<FormState extends object, Data> = (
  params: UsePagingListFetcherParams<FormState, Data>,
) => Promise<Data>

export interface UsePagingListOptions<Fetcher extends AnyFunc, FormState extends object> {
  /**
   * 数据获取函数
   */
  fetcher?: Fetcher
  /**
   * `useForm` 的配置项，参考 useForm 文档
   *
   * @defaultValue undefined
   */
  form?: UseFormOptions<FormState>
  /**
   * `useQuery` 的配置项，参考 `useQuery` 文档
   *
   * @defaultValue undefined
   */
  query?: Omit<UseQueryOptions<Fetcher>, 'initialParams' | 'initialData'>
  /**
   * `usePagination` 的配置项，参考 `usePagination` 文档
   *
   * @defaultValue undefined
   */
  pagination?: UsePaginationOptions<ReturnType<Fetcher>>
  /**
   * 立即查询的表单字段，当表单字段变化时，会自动触发查询
   *
   * @defaultValue []
   */
  immediateQueryKeys?: (keyof FormState)[]
}

返回值

export interface UsePagingListReturns<
  Item,
  FormState extends object,
  Data extends Item[],
  Fetcher extends UsePagingListFetcher<FormState, Data>,
> {
  /**
   * 是否正在加载
   */
  loading: boolean
  /**
   * 数据列表
   */
  list: Data
  /**
   * form 实例，参考 useForm 文档
   */
  form: UseFormReturns<FormState>
  /**
   * 使用上次请求参数（表单状态等），刷新数据
   */
  refresh: () => void
  /**
   * 选中状态和操作，参考 useMultiSelect 文档
   */
  selection: UseMultiSelectReturnsState<Item> & UseMultiSelectReturns<Item>
  /**
   * 分页状态和操作，参考 usePagination 文档
   */
  pagination: UsePaginationReturnsState<Data> & UsePaginationReturnsActions
}

#usePagingList

#场景

#演示

#用法

#源码

#API

#配置项 Options

#返回值

usePagingList

场景

演示

用法

源码

API

配置项 Options

返回值