上手指南
Hooks 列表
后期规划
上手指南
Hooks 列表
后期规划
简体中文

usePagingList

Tags:
ProUtilities
DepCollect
这个 Hook 自 v1.7.0 版本起可用。

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

拥有以下特性：

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

场景

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

演示

源码
Name:
Gender:
Color:
No data
No selected
Total:
10
Current:
1 - 5
Page Size:

用法

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

// 传入一个接受 page, pageSize 分页参数的函数，它需要返回一个数据列表
// 在这个函数里面使用 setTotal 来设置数据总数，以便分页器能够正确显示总数
const { form, pagination, selection, list, refresh, loading } = usePagingList(
  {
    fetcher: async (payload) => {
      const { page, pageSize, form, setTotal } = payload
      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 UsePagingListOptions<Item, FormState extends object> {
  /**
   * 数据获取函数
   */
  fetcher?: UsePagingListFetcher<Item, FormState>
  /**
   * `useForm` 的配置项，参考 useForm 文档
   *
   * @defaultValue undefined
   */
  form?: UseFormOptions<FormState>
  /**
   * `useQuery` 的配置项，参考 `useQuery` 文档
   *
   * @defaultValue undefined
   */
  query?: Omit<UseQueryOptions<UsePagingListFetcher<Item, FormState>>, 'initialParams' | 'initialData'>
  /**
   * `usePagination` 的配置项，参考 `usePagination` 文档
   *
   * @defaultValue undefined
   */
  pagination?: UsePaginationOptions<Item[]>
  /**
   * 立即查询的表单字段，当表单字段变化时，会自动触发查询
   *
   * @defaultValue []
   */
  immediateQueryKeys?: (keyof FormState)[]
}

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

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

返回值

export interface UsePagingListReturns<Item, FormState extends object>
  extends Pick<
    UseQueryReturns<any, any>,
    'loading' | 'params' | 'error' | 'initializing' | 'refreshing' | 'loadingSlow'
  > {
  /**
   * list data
   */
  list: Item[]
  /**
   * form state
   */
  form: UseFormReturns<FormState>
  /**
   * refresh query
   */
  refresh: () => void
  /**
   * selection state
   */
  selection: UseMultiSelectReturnsState<Item> & UseMultiSelectReturnsActions<Item>
  /**
   * pagination state
   */
  pagination: UsePaginationReturnsState<Item[]> & UsePaginationReturnsActions
}