Pagination 分页
数据量大、需要分页加载时使用。可以显示总条数、每页条数的选择、页码和跳转输入框,显示哪些部分、按什么顺序由 layout 决定。
引入
import { NsPagination } from '@ns/ui'
基础用法
total 是数据总条数,当前页用 v-model:current-page 绑定,每页条数用 v-model:page-size 绑定。不写 layout 时全部显示:总条数、每页条数、上一页、页码、下一页、跳转。
<script setup lang="ts">
import { ref } from 'vue'
import { NsPagination } from '@ns/ui'
const currentPage = ref(1)
const pageSize = ref(10)
</script>
<template>
<NsPagination v-model:current-page="currentPage" v-model:page-size="pageSize" :total="100" />
<p style="margin-top: 12px">当前页:{{ currentPage }},每页条数:{{ pageSize }}</p>
</template>
布局
layout 是用逗号隔开的字符串,可以用的项有 6 个:
total:共多少条。sizes:每页条数的下拉框。prev、next:上一页、下一页按钮。pager:页码。jumper:“前往 [ ] 页”的跳转输入框,按回车或失去焦点时跳转。
写了哪些就显示哪些,显示的顺序和书写的顺序一致。下面每一行上方是这一行用的 layout,几个分页共用同一个当前页:
<script setup lang="ts">
import { ref } from 'vue'
import { NsPagination, NsSpace } from '@ns/ui'
const currentPage = ref(1)
</script>
<template>
<NsSpace direction="vertical" fill>
<div>
<div class="demo-label">prev, pager, next</div>
<NsPagination v-model:current-page="currentPage" :total="100" layout="prev, pager, next" />
</div>
<div>
<div class="demo-label">total, prev, pager, next</div>
<NsPagination
v-model:current-page="currentPage"
:total="100"
layout="total, prev, pager, next"
/>
</div>
<div>
<div class="demo-label">sizes, prev, pager, next</div>
<NsPagination
v-model:current-page="currentPage"
:total="100"
layout="sizes, prev, pager, next"
/>
</div>
<div>
<div class="demo-label">prev, pager, next, jumper</div>
<NsPagination
v-model:current-page="currentPage"
:total="100"
layout="prev, pager, next, jumper"
/>
</div>
<div>
<div class="demo-label">prev, next(简洁模式)</div>
<NsPagination v-model:current-page="currentPage" :total="100" layout="prev, next" />
</div>
<div>
<div class="demo-label">pager(只有页码)</div>
<NsPagination v-model:current-page="currentPage" :total="100" layout="pager" />
</div>
<div>
<div class="demo-label">jumper, prev, pager, next, total(顺序跟着书写顺序走)</div>
<NsPagination
v-model:current-page="currentPage"
:total="100"
layout="jumper, prev, pager, next, total"
/>
</div>
</NsSpace>
</template>
<style scoped>
.demo-label {
margin-bottom: 4px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
页数很多时
总页数不超过 7 时页码全部显示。超过 7 时固定显示 7 个页码按钮:首页和末页一直显示,中间显示当前页附近的几页,其余的折叠成省略号。省略号只出现在确实有页码被折叠的一侧:当前页靠前时只有右边有,靠后时只有左边有,在中间时两边都有。
点下面的按钮跳到不同位置,看省略号的变化:
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsPagination, NsSpace } from '@ns/ui'
const currentPage = ref(50)
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<NsButton size="small" @click="currentPage = 1">第 1 页(只有右边折叠)</NsButton>
<NsButton size="small" @click="currentPage = 50">第 50 页(两边都折叠)</NsButton>
<NsButton size="small" @click="currentPage = 100">第 100 页(只有左边折叠)</NsButton>
</NsSpace>
<NsPagination v-model:current-page="currentPage" :total="1000" layout="prev, pager, next" />
<NsPagination :total="70" layout="prev, pager, next" />
</NsSpace>
</template>
第二个分页只有 7 页,页码全部显示,不折叠。
每页条数
layout 里有 sizes 时显示每页条数的下拉框,选项由 page-sizes 指定。改变每页条数后,如果当前页超出了新的总页数,会自动回到最后一页:下面第一个分页现在在第 10 页,改成每页 100 条后只有 3 页,当前页变成 3。
当前的每页条数不在 page-sizes 里时,下拉框里会自动补上这一项,例如第二个分页每页 15 条。
<script setup lang="ts">
import { ref } from 'vue'
import { NsPagination, NsSpace } from '@ns/ui'
const currentPage = ref(10)
const pageSize = ref(20)
const message = ref('')
const handleSizeChange = (size: number) => {
message.value = `size-change:每页条数改成了 ${size}`
}
const otherPage = ref(1)
const otherSize = ref(15)
</script>
<template>
<NsSpace direction="vertical" fill>
<NsPagination
v-model:current-page="currentPage"
v-model:page-size="pageSize"
:total="235"
:page-sizes="[20, 50, 100]"
layout="total, sizes, prev, pager, next"
@size-change="handleSizeChange"
/>
<p>当前第 {{ currentPage }} 页,每页 {{ pageSize }} 条。{{ message }}</p>
<NsPagination
v-model:current-page="otherPage"
v-model:page-size="otherSize"
:total="235"
:page-sizes="[10, 20, 50]"
layout="sizes, prev, pager, next"
/>
</NsSpace>
</template>
带背景色
background 让页码按钮和上一页、下一页带上浅色底,悬停时变成主色底、白字(不带底色时悬停只有文字和边框变成主色)。可以和任意 layout 搭配。
<script setup lang="ts">
import { ref } from 'vue'
import { NsPagination, NsSpace } from '@ns/ui'
const currentPage = ref(3)
</script>
<template>
<NsSpace direction="vertical" fill>
<div>
<div class="demo-label">不带背景色</div>
<NsPagination v-model:current-page="currentPage" :total="100" layout="prev, pager, next" />
</div>
<div>
<div class="demo-label">background</div>
<NsPagination
v-model:current-page="currentPage"
:total="100"
background
layout="prev, pager, next"
/>
</div>
<div>
<div class="demo-label">background + 完整布局</div>
<NsPagination v-model:current-page="currentPage" :total="100" background />
</div>
</NsSpace>
</template>
<style scoped>
.demo-label {
margin-bottom: 4px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
不同尺寸
size 有 large、default、small 三种。页码、上一页、下一页的高度分别是 40、32、24px,和同尺寸的按钮一样高;字号是 16、14、12px,圆角是 8、6、4px。每页条数下拉框、跳转输入框、总条数和“前往”“页”这些文字也跟着变。不写 size 时跟随 ConfigProvider,都没有时是 default。
下面前三行是完整布局,后三行是带背景色的页码:
<script setup lang="ts">
import { ref } from 'vue'
import { NsPagination, NsSpace } from '@ns/ui'
const currentPage = ref(1)
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">large</span>
<NsPagination v-model:current-page="currentPage" :total="100" size="large" />
</NsSpace>
<NsSpace wrap>
<span class="row-label">default</span>
<NsPagination v-model:current-page="currentPage" :total="100" />
</NsSpace>
<NsSpace wrap>
<span class="row-label">small</span>
<NsPagination v-model:current-page="currentPage" :total="100" size="small" />
</NsSpace>
<NsSpace wrap>
<span class="row-label">large</span>
<NsPagination
v-model:current-page="currentPage"
:total="100"
size="large"
background
layout="prev, pager, next"
/>
</NsSpace>
<NsSpace wrap>
<span class="row-label">default</span>
<NsPagination
v-model:current-page="currentPage"
:total="100"
background
layout="prev, pager, next"
/>
</NsSpace>
<NsSpace wrap>
<span class="row-label">small</span>
<NsPagination
v-model:current-page="currentPage"
:total="100"
size="small"
background
layout="prev, pager, next"
/>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 56px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
原来的 small 属性已不推荐,请改用 size="small"。它还能用,写 small 等同于 size="small";同时写了 size 时以 size 为准。
禁用
disabled 为 true 时整个分页不能操作:页码、上一页、下一页、每页条数下拉框和跳转框都变成禁用样式,页码按钮也不能用 Tab 聚焦。
<template>
<NsSpace direction="vertical" fill>
<NsPagination :current-page="3" :total="100" disabled />
<NsPagination :current-page="3" :total="100" background disabled layout="prev, pager, next" />
</NsSpace>
</template>
只有一页时隐藏
hide-on-single-page 为 true 时,总页数只有一页就不渲染分页。下面每页 10 条,总条数是 5 时只有一页,分页不显示。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsPagination, NsSpace } from '@ns/ui'
const currentPage = ref(1)
const total = ref(5)
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsButton @click="total = total > 10 ? 5 : 50">切换总条数(现在 {{ total }})</NsButton>
<NsPagination
v-model:current-page="currentPage"
:total="total"
hide-on-single-page
layout="total, prev, pager, next"
/>
</NsSpace>
</template>
监听翻页
用户翻页时触发 change,参数是新的页码;改每页条数时触发 size-change。一般在这里请求新一页的数据。下面用定时器模拟请求,事件按触发顺序列出来:
<script setup lang="ts">
import { ref } from 'vue'
import { NsPagination, NsSpace } from '@ns/ui'
const currentPage = ref(1)
const pageSize = ref(10)
const status = ref('点页码、上一页、下一页,或者改每页条数试试')
const events = ref<string[]>([])
const record = (text: string) => {
events.value = [text, ...events.value].slice(0, 5)
}
const loadData = () => {
status.value = `正在请求第 ${currentPage.value} 页,每页 ${pageSize.value} 条……`
const page = currentPage.value
window.setTimeout(() => {
if (page === currentPage.value) status.value = `已加载第 ${page} 页`
}, 500)
}
const handleChange = (page: number) => {
record(`change:${page}`)
loadData()
}
const handleSizeChange = (size: number) => {
record(`size-change:${size}`)
currentPage.value = 1
loadData()
}
</script>
<template>
<NsSpace direction="vertical" fill>
<NsPagination
v-model:current-page="currentPage"
v-model:page-size="pageSize"
:total="200"
@change="handleChange"
@size-change="handleSizeChange"
/>
<p>{{ status }}</p>
<p v-if="events.length">最近的事件:{{ events.join(',') }}</p>
</NsSpace>
</template>
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| total | number | 0 | 数据总条数。小于等于 0 时按只有一页处理 |
| currentPage | number | 1 | 当前页码,支持 v-model:current-page |
| pageSize | number | 10 | 每页条数,支持 v-model:page-size。小于等于 0 时按只有一页处理 |
| pageSizes | number[] | [10, 20, 30, 40, 50, 100] | 每页条数下拉框的选项。当前的 pageSize 不在里面时会自动补进去 |
| layout | string | 'total, sizes, prev, pager, next, jumper' | 显示哪些部分和它们的顺序,用逗号隔开。可用的项:total、sizes、prev、pager、next、jumper |
| background | boolean | false | 页码按钮和上一页、下一页是否带底色 |
| disabled | boolean | false | 是否禁用 |
| size | 'large' | 'default' | 'small' | - | 尺寸,页码按钮高 40 / 32 / 24px。不写时跟随 ConfigProvider,都没有时是 'default' |
| small | boolean | false | 已不推荐,请用 size="small"。是否用小尺寸,同时写了 size 时以 size 为准 |
| hideOnSinglePage | boolean | false | 只有一页时是否隐藏整个分页 |
Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| update:currentPage | (value: number) | 当前页变化时触发,v-model:current-page 用的就是它。除了用户翻页,当前页因为总页数变少被拉回最后一页时也会触发 |
| update:pageSize | (value: number) | 用户改变每页条数时触发,v-model:page-size 用的就是它 |
| change | (currentPage: number) | 用户翻页时触发(点页码、上一页、下一页,或在跳转框里输入页码) |
| size-change | (pageSize: number) | 用户改变每页条数时触发 |
类型
import type { PaginationProps, PaginationLayoutItem, PaginationSize } from '@ns/ui'
type PaginationLayoutItem = 'total' | 'sizes' | 'prev' | 'pager' | 'next' | 'jumper'
type PaginationSize = 'large' | 'default' | 'small'
interface PaginationProps {
total: number
pageSize?: number
currentPage?: number
pageSizes?: number[]
layout?: string
background?: boolean
disabled?: boolean
size?: PaginationSize
/** @deprecated 用 size="small" */
small?: boolean
hideOnSinglePage?: boolean
}
另外还导出了 PaginationEmits。
注意事项
- 当前页因为总页数变少而被拉回最后一页时(
total变小、pageSize变大),只触发update:currentPage,不触发change。用v-model:current-page绑定的值会跟着变;如果只监听change来请求数据,这种情况要自己处理,例如在size-change里重新请求。 - 用户改变每页条数时,事件的顺序是
update:currentPage(当前页超出范围时才有)、update:pageSize、size-change。 - 组件自己记着当前页和每页条数,不绑定
v-model也能点。但这时外面拿不到最新的值,要靠change、size-change事件。 layout里写了不认识的项会被忽略。- 跳转框在按回车或失去焦点时跳转,输入的页码超出范围时按第一页或最后一页处理,小数向下取整。
- 页码按钮可以用 Tab 键聚焦,按回车或空格翻页。
- 每页条数的下拉框用的是
NsSelect,跳转框用的是NsInputNumber,它们的高度比页码按钮略高。
优化点
- [ ] 被动修正当前页时是否也触发
change,需要统一约定 - [x] 支持
large尺寸:size="large" - [ ] 支持自定义“共 x 条”“条/页”“前往”等文字
- [ ] 支持自定义显示的页码按钮数量
- [ ] 支持点省略号快速向前、向后翻几页
- [ ] 支持自定义页码按钮样式
- [ ] 支持无限滚动模式
- [x] 支持简化模式(仅显示上一页/下一页):
layout="prev, next" - [ ] 支持只显示“当前页 / 总页数”的简化模式