Pagination

分页栏组件

项目状态

版本更新内容请访问 Changelog

如果您的项目正在使用 vue 2.x 版本生态，请使用 v-page 2.x 版本

安装

将 v-page 组件安装到项目中

npm

npm i v-page

yarn

yarn add v-page

pnpm

pnpm add v-page

全局安装插件

import { createApp } from 'vue'
import App from './app.vue'
import { PaginationBar } from 'v-page'

const app = createApp(App)
// globally install component
app.use(PaginationBar, {
  // globally config options
})
app.mount('#app')

可在全局安装组件时设置的属性

• info
• pageSizeMenu
• language
• align
• border
• pageNumber
• first
• last

当然，您也可以仅在需要使用的地方引用组件，这也是更加推荐的使用方式。这更有利于代码拆分打包，起到更好的按需引用效果

<template>
  <PaginationBar />
</template>

<script setup>
import { PaginationBar } from 'v-page'
</script>

在页面中应用组件

一个分页栏的典型用法

template

<div
  v-for="item in list"
  :key="item.key"
  v-text="item.name"
/>
<PaginationBar
  language="cn"
  v-model="pageNumber"
  :total-row="totalRow"
  @change="change"
>
  <PaginationPageSizeOptions />
  <PaginationInfo />
  <PaginationFirstPage />
  <PaginationPreviousPage />
  <PaginationPageNumbers />
  <PaginationNextPage />
  <PaginationLastPage />
</PaginationBar>

ts

import { ref } from 'vue'
import {
  PaginationBar,
  PaginationPageSizeOptions,
  PaginationInfo,
  PaginationPanel,
  PaginationPageNumbers,
  PaginationFirstPage,
  PaginationPreviousPage,
  PaginationNextPage,
  PaginationLastPage
} from 'v-page'
import type { PageInfo } from 'v-page'

const pageNumber = ref<number>(3)
const totalRow = ref<number>(100)
const list = ref<unknown[]>([])
// respond for pagination change
function change (data: PageInfo): void {
  console.log(data) // { pageNumber: 1, pageSize: 10, totalPage: 10 }

  const params = {
    pageNumber: data.pageNumber,
    pageSize: data.pageSize,
    ...
  }
  // do some http request for example
  axios.post('some-api-address', params).then(resp => {
    // fetch new data and update data list and `totalRow` variable
    list.value = resp.list || []
    totalRow.value = resp.totalRow
  })
}

实例

快速应用

最常用的分页栏应用

• 每页记录数102050100
• 第 0/3 页(共21条记录)
• 首页
• «
• 1
• 2
• 3
• »
• 尾页

分页事件 change 响应数据

Event data logs

<PaginationBar
  align="center"
  :total-row="21"
  @change="change"
>
  <PaginationPageSizeOptions />
  <PaginationInfo />
  <PaginationFirstPage />
  <PaginationPreviousPage />
  <PaginationPageNumbers />
  <PaginationNextPage />
  <PaginationLastPage />
</PaginationBar>

画廊数据展示模式实例

画廊数据格展示方式示例

• 每页记录数102050100
• 第 0/9 页(共88条记录)
• 首页
• «
• 1
• 2
• 3
• 4
• 5
• »
• 尾页

template

<div>
  <div
    v-for="item in listGallery"
    :key="item"
    v-text=item
  />
</div>
<PaginationBar
  align="center"
  :total-row="88"
  @change="change"
>
  ...
</PaginationBar>

js

import { ref } from 'vue'

const srcList = Array(88).fill(0).map((val, index) => index + 1)
const listGallery = ref([])

function change ({ pageNumber, pageSize }) {
  const start = pageSize * (pageNumber - 1)
  const end = (start + pageSize) > srcList.length
    ? srcList.length
    : start + pageSize
  listGallery.value = srcList.filter((val, index) => {
    return index >= start && index < end
  })
}

分页操作

几个实例展示分页码的操作方式

• 每页记录数102050100
• 第 0/6 页(共58条记录)
• 首页
• «
• 1
• 2
• 3
• 4
• 5
• »
• 尾页

template

<div>
  <input type="text" v-model="inputPageNumber" />
  <button type="button" @click="goToInputPage" >go</button>
  <button
    type="button"
    @click="pageNumber++"
  >pageNumber + 1</button>
</div>

<PaginationBar v-model="pageNumber" >
  ...
</PaginationBar>

js

import { ref } from 'vue'

const pageNumber = ref(3)
const inputPageNumber = ref('2')

function goToInputPage () {
  if (!inputPageNumber.value) return

  const newPageNumber = Number(inputPageNumber.value)

  if (window.isNaN(newPageNumber)) {
    inputPageNumber.value = ''
    return
  }
  pageNumber.value = newPageNumber
}

每页记录数

pageSize 指定了每页记录数，pageSizeMenu 提供了可供用户快速选择的每页记录数列表

• 每页记录数10202550100
• 第 0/4 页(共100条记录)
• 首页
• «
• 1
• 2
• 3
• 4
• »
• 尾页

template

<PaginationBar
  v-model:page-size="pageSize"
  :total-row="100"
>
  ...
</PaginationBar>

js

import { ref } from 'vue'

const pageSize = ref(25)

当 pageSizeMenu 所提供值列表没有与 pageSize 值匹配的项目时，则该值将自动添加进 pageSizeMenu 列表中，并选中该值

对齐方向

Alignment direction leftcenterright

• 每页记录数102050100
• 第 0/3 页(共28条记录)
• 首页
• «
• 1
• 2
• 3
• »
• 尾页

<PaginationBar align="left" />

风格样式

分页栏的风格样式

• 每页记录数102050100
• 第 0/3 页(共28条记录)
• 首页
• «
• 1
• 2
• 3
• »
• 尾页

• 每页记录数102050100
• 第 0/3 页(共28条记录)
• 首页
• «
• 1
• 2
• 3
• »
• 尾页

<PaginationBar border />
<PaginationBar circle />

启用与禁用

Disabled

• 每页记录数102050100
• 第 0/3 页(共28条记录)
• 首页
• «
• 1
• 2
• 3
• »
• 尾页

• 每页记录数102050100
• 第 0/3 页(共28条记录)
• 首页
• «
• 1
• 2
• 3
• »
• 尾页

<PaginationBar :disabled="true" />

布局排列

v-page 可以视情况使用分页栏的组件模块，以及对排列顺序进行调整，以适应不同的布局需求

• 首页
• «
• 1
• 2
• 3
• »
• 尾页
• 第 0/3 页(共28条记录)
• 每页记录数102050100

• «
• 每页记录数102050100
• 第 0/3 页(共28条记录)
• »

<PaginationBar>
  <PaginationFirstPage />
  <PaginationPreviousPage />
  <PaginationPageNumbers />
  <PaginationNextPage />
  <PaginationLastPage />
  <PaginationInfo />
  <PaginationPageSizeOptions />
</PaginationBar>
<PaginationBar>
  <PaginationPreviousPage />
  <PaginationPageSizeOptions />
  <PaginationInfo />
  <PaginationNextPage />
</PaginationBar>

插槽

v-page 提供了作用域插槽，输出分页栏核心状态数据，方便进行功能定制

• «
• page: 0

  pageSize: 10

  totalPage: 3

  totalRow: 28

  isFirst: false

  isLast: false
• »

<PaginationBar
  border
  align="left"
  :total-row="28"
>
  <template #default="{
    pageNumber, pageSize, totalPage,
    totalRow, isFirst, isLast
  }">
    <PaginationPreviousPage />
    <PaginationPanel>
      <div>
        <div>page: <span v-text="pageNumber" /></div>
        <div>pageSize: <span v-text="pageSize" /></div>
        <div>totalPage: <span v-text="totalPage" /></div>
        <div>totalRow: <span v-text="totalRow" /></div>
        <div>isFirst: <span v-text="isFirst" /></div>
        <div>isLast: <span v-text="isLast" /></div>
      </div>
    </PaginationPanel>
    <PaginationNextPage />
  </template>
</PaginationBar>

自定义内容通过 PaginationPanel 组件包裹，以保证分页栏的样式一致性

显示全部数据选项

在 每页记录数 栏增加显示全部数据的选项，用于设置数据展示栏显示全部数据，不进行分页。选择该项目后，change 事件的响应数据如下

{
  pageNumber: 1,
  pageSize: 0,
  totalPage: 1
}

• 每页记录数102050100全部
• 第 0/3 页(共28条记录)
• 首页
• «
• 1
• 2
• 3
• »
• 尾页

<PaginationBar :total-row="28" display-all />

Props

v-page 的设置参数

interface PaginationProps {
  /**
   * 默认页/当前页
   * @default 1
   */
  modelValue?: number
  /**
   * 每页数据记录数
   * @default 10
   */
  pageSize?: number
  /**
   * 总记录数
   */
  totalRow: number
  /**
   * 组件语言
   * @default `en`
   * 
   * 完整语言清单
   * `cn` 简体中文
   * `en` English
   * `de` German
   * `pt` Portuguese
   * `jp` Japanese
   */
  language?: 'cn' | 'en' | 'de' | 'jp' | 'pt'
  /**
   * 每页数据记录数列表，仅在 `pageSizeOptions` 为 `true` 时生效
   * @default [10, 20, 50, 100]
   */
  pageSizeMenu?: number[]
  /**
   * 分页栏对齐方向
   * @default `right`
   */
  align?: 'left' | 'right' | 'center'
  /**
   * 禁用分页栏组件
   * @default false
   */
  disabled?: boolean
  /**
   * 显示边框样式
   * @default true
   */
  border?: boolean
  /**
   * 圆形按钮风格
   * @default false
   */
  circle?: boolean
  /**
   * 在每页记录数列表中增加显示所有数据记录项目
   * @default false
   */
  displayAll?: boolean
  /**
   * 在只有一页数据时，隐藏分页栏
   * @default false
   */
  hideOnSinglePage?: boolean
}

事件

组件各类操作的响应事件

change

分页栏操作发生数据变更时，触发的响应事件

change: (data: PageInfo) => void

interface PageInfo {
  // 当前分页号
  pageNumber: number
  // 每页显示记录数
  pageSize: number
  // 总页数
  totalPage: number
}
// 可直接使用组件提供类型描述
import type { PageInfo } from 'v-page'

update:modelValue

当前页变更时，触发的响应事件

`update:modelValue`: (value: number) => void

update:pageSize

每页记录数变更时，触发的响应事件

`update:pageSize`: (value: number) => void