X-Next

Appearance

Pagination 分页 ​

用于长列表和表格的数据分页浏览，可切换页码、调整每页条数或输入页码快速跳转。

何时使用 ​

  • 数据量较大，需要拆分为多个页面展示。
  • 表格、列表或搜索结果需要保留当前页、每页条数等浏览状态。
  • 需要在完整分页、简单分页和跳转输入之间按场景切换。

基础用法 ​

共 120 条
  • 1
  • 2
  • 3
  • 4
  • 5
  • 12
当前第 2 页
vue
<template>
  <x-pagination v-model:current="current" :total="120" show-total />
</template>

<script setup lang="ts">
import { ref } from 'vue';

const current = ref(2);
</script>

受控页码和事件 ​

共 240 条
  • 1
  • 2
  • 3
  • 4
  • 5
  • 24
10 条/页
当前：第 3 页，10 条/页
vue
<template>
  <x-pagination
    v-model:current="current"
    v-model:page-size="pageSize"
    :total="240"
    show-total
    show-page-size
    :page-size-options="[10, 20, 40]"
    @change="handleCurrentChange"
    @page-size-change="handlePageSizeChange"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue';

const current = ref(3);
const pageSize = ref(10);

const handleCurrentChange = (current: number) => {
  console.log('current:', current);
};

const handlePageSizeChange = (pageSize: number) => {
  console.log('pageSize:', pageSize);
};
</script>

每页条数 ​

  • 1
  • 3
  • 4
  • 5
  • 6
  • 7
  • 32
10 条/页
当前第 5 页，10 条/页
vue
<template>
  <x-pagination
    v-model:current="current"
    v-model:page-size="pageSize"
    :total="320"
    show-page-size
    :page-size-options="[10, 20, 50, 100]"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue';

const current = ref(5);
const pageSize = ref(10);
</script>

跳转输入 ​

  • 1
  • 2
  • 3
  • 4
  • 5
  • 18
跳转至页
输入页码后跳转到第 1 页
vue
<template>
  <x-pagination v-model:current="current" :total="180" show-jumper>
    <template #jumper-append>页</template>
  </x-pagination>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const current = ref(1);
</script>

简单模式 ​

/12
适合空间较窄的工具栏或弹层
vue
<template>
  <x-pagination v-model:current="current" :total="120" simple />
</template>

<script setup lang="ts">
import { ref } from 'vue';

const current = ref(4);
</script>

更多页码和边界 ​

  • 1
  • 16
  • 17
  • 18
  • 19
  • 20
  • 50
省略号可快速跨页跳转
单页时分页被隐藏
vue
<template>
  <x-pagination :total="500" :default-current="18" show-more />
  <x-pagination :total="8" hide-on-single-page />
</template>

尺寸和禁用 ​

共 120 条
  • 1
  • 2
  • 3
  • 4
  • 5
  • 12
10 条/页
跳转至
共 120 条
  • 1
  • 2
  • 3
  • 4
  • 5
  • 12
10 条/页
vue
<template>
  <x-radio-group v-model="size" type="button">
    <x-radio value="mini">Mini</x-radio>
    <x-radio value="small">Small</x-radio>
    <x-radio value="medium">Medium</x-radio>
    <x-radio value="large">Large</x-radio>
  </x-radio-group>
  <x-pagination :total="120" :size="size" show-total show-page-size show-jumper />
  <x-pagination :total="120" :default-current="3" disabled show-total show-page-size />
</template>

<script setup lang="ts">
import { ref } from 'vue';

const size = ref<'mini' | 'small' | 'medium' | 'large'>('medium');
</script>

自定义内容 ​

共 260 条记录
  • 上一页
  • P1
  • ...
  • P4
  • P5
  • P6
  • P7
  • P8
  • ...
  • P26
  • 下一页
到第页
vue
<template>
  <x-pagination v-model:current="current" :total="260" show-total show-jumper>
    <template #total="{ total }">共 {{ total }} 条记录</template>
    <template #page-item="{ page }">P{{ page }}</template>
    <template #page-item-step="{ type }">
      {{ type === 'previous' ? '上一页' : '下一页' }}
    </template>
    <template #page-item-ellipsis>...</template>
    <template #jumper-prepend>到第</template>
    <template #jumper-append>页</template>
  </x-pagination>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const current = ref(6);
</script>

使用说明 ​

  • 页码和每页条数会被限制在合法范围内；非法或清空的每页条数不会触发分页变更。
  • 页码项、上一页、下一页和省略跳转支持键盘聚焦，可使用 Enter 或 Space 触发。
  • 当 autoAdjust 为 true 时，改变每页条数或总页数减少会尽量保持数据位置连续，并自动修正当前页。

按需导入 ​

ts
import { Pagination } from 'x-next';

Props ​

参数说明类型默认值
total数据总数number必填
current当前页码numberundefined
defaultCurrent默认页码，非受控模式number1
pageSize每页条数numberundefined
defaultPageSize默认每页条数，非受控模式number10
disabled是否禁用booleanfalse
hideOnSinglePage单页时是否隐藏booleanfalse
simple是否为简单模式booleanfalse
showTotal是否显示总数booleanfalse
showMore是否显示更多按钮booleanfalse
showJumper是否显示跳转输入booleanfalse
showPageSize是否显示每页条数选择器booleanfalse
pageSizeOptions每页条数选项，建议使用正整数number[][10, 20, 30, 40, 50]
pageSizeProps每页条数选择器 PropsSelectProps-
size分页尺寸'mini' | 'small' | 'medium' | 'large'跟随全局配置
pageItemStyle页码按钮样式CSSProperties-
activePageItemStyle当前页码按钮样式CSSProperties-
baseSize显示省略的基础页码数number6
bufferSize当前页左右显示页码个数number2
autoAdjust改变每页条数或总页数时是否自动调整页码booleantrue

Events ​

事件名说明回调参数
update:current当前页码变化时触发current: number
update:pageSize每页条数变化时触发pageSize: number
change页码改变时触发current: number
page-size-change每页条数改变时触发pageSize: number

Slots ​

插槽名说明参数
page-item自定义页码按钮{ page }
page-item-step自定义上一页/下一页按钮{ type }
page-item-ellipsis自定义省略按钮-
total自定义总数内容{ total }
jumper-prepend自定义跳转输入前置内容-
jumper-append自定义跳转输入后置内容-