QXS-BNS

Appearance

本页导航

usePagination ​

usePagination 是一个对齐 Element Plus 分页字段命名的 Vue 3 Composition API Hook，用来统一维护页码、每页条数、总数和排序状态。

分页 Hook 预览 ​

先把 usePagination 接到一个真实的表格和分页器上，再去看参数和迁移说明。
这样你能先确认它到底返回哪些状态、事件处理器和请求参数。

loading

基础用法 ​

ts
import { usePagination } from '@qxs-bns/hooks'
vue
<script setup lang="ts">
import { usePagination } from '@qxs-bns/hooks'

const { pagination, getParams, handlePagination } = usePagination({
  currentPage: 1,
  pageSize: 20,
  total: 1000,
  pageSizes: [10, 20, 50, 100],
  layout: 'total, sizes, prev, pager, next, jumper',
})

const handlers = handlePagination(() => {
  const params = getParams()
  fetchData(params)
})

async function fetchData(params: { pageNo: number, pageSize: number }) {
  console.log(params)
}
</script>

说明 ​

字段命名对齐 Element Plus

currentPage、pageSize、pageSizes、layout 这些字段与 Element Plus el-pagination 的命名保持一致，接表格页时不需要再做一层映射。

getParams() 的输出格式

虽然输入字段对齐了 Element Plus，但 getParams() 最终返回的是业务侧常见的 { pageNo, pageSize }，而不是 { currentPage, pageSize }。

旧字段仍可用，但会警告

page 和 sizes 仍然兼容，但调用时会打印废弃提示。新代码请直接使用 currentPage 和 pageSizes。

常见场景 ​

带排序的分页 ​

ts
const { pagination, getParams, handlePagination } = usePagination({
  currentPage: 1,
  pageSize: 20,
  total: 0,
  pageSizes: [10, 20, 50, 100],
  layout: 'total, sizes, prev, pager, next',
})

const handlers = handlePagination(loadData)

async function loadData() {
  const params = getParams()
  const response = await fetchTableData(params)
  pagination.value.total = response.total
}

自定义分页布局 ​

ts
const { pagination } = usePagination({
  currentPage: 1,
  pageSize: 50,
  total: 200,
  pageSizes: [20, 50, 100, 200],
  layout: 'total, prev, pager, next, jumper',
})

API ​

参数 ​

NameDescriptionTypeDefault
currentPage当前页数number1
pageSize每页条数number10
total总条目数number0
pageSizes每页条数可选项number[][10, 20, 50, 100]
layout分页布局字符串string'total, sizes, prev, pager, next'
sort排序字段和列信息Pagination['sort'] | nullnull
order排序方向string | nullnull

兼容参数 ​

NameReplacementStatus
pagecurrentPagedeprecated
sizespageSizesdeprecated

返回值 ​

NameDescriptionType
pagination分页响应式状态Ref<PaginationParams>
getParams获取请求参数，返回 { pageNo, pageSize, sort?, order? }() => Pagination
handlePagination生成分页事件处理器(getData: () => void) => PaginationHandlers
getLegacyParams生成旧格式参数 { page, size, total, sizes, ... }() => LegacyPaginationParams

分页事件处理器 ​

NameDescriptionType
onSizeChange修改每页条数并触发回调(size: number) => void
onCurrentChange修改当前页并触发回调(page: number) => void
onSortChange修改排序字段并触发回调(prop: Pagination['sort'], order: string) => void

迁移 ​

从旧参数迁移 ​

ts
// 旧写法
usePagination({
  page: 1,
  sizes: [10, 20],
})

// 新写法
usePagination({
  currentPage: 1,
  pageSizes: [10, 20],
})

模板里也要同步改字段 ​

vue
<!-- 旧写法 -->
<span>第 {{ pagination.page }} 页</span>

<!-- 新写法 -->
<span>第 {{ pagination.currentPage }} 页</span>

常见问题 ​

为什么 onSortChange 最后写入的是 asc / desc？ ​

Hook 会把 Element Plus 常见的 ascending / descending 归一成更适合接口层的 asc / desc。

什么时候还需要 getLegacyParams()？ ​

只有当你还在对接旧接口或旧页面，必须拿到 { page, size, sizes } 这类字段时才需要。
新页面直接使用 getParams() 即可。