报告问题编辑此页面

分页导航

快速的第一页、上一页、下一页、最后一页和页面按钮，用于基于导航的分页，支持常规链接或路由器链接。

概述

<b-pagination-nav> 是一个自定义输入组件，提供导航分页。使用 number-of-pages 属性设置总页数。页码从 1 到 number-of-pages 索引。

b-pagination-nav 将尝试自动检测哪个页面链接是活动页面按钮，具体取决于当前页面的 URL（通过 $route 检测或如果没有检测到 $router，则通过浏览器位置 URL）。

注意： <b-pagination-nav> 用于导航到新的页面 URL。对于控制页面组件分页（例如表格或列表分页），请使用 <b-pagination> 组件。

<template>
  <div class="overflow-auto">
    <b-pagination-nav :link-gen="linkGen" :number-of-pages="10" use-router></b-pagination-nav>
  </div>
</template>

<script>
  export default {
    methods: {
      linkGen(pageNum) {
        return pageNum === 1 ? '?' : `?page=${pageNum}`
      }
    }
  }
</script>

<!-- b-pagination-nav-lead.vue -->

页面链接和数字生成

默认情况下，<b-pagination-nav> 生成普通链接标签，将 HREF 属性设置为 base-url 与页码连接。 base-url 属性的默认值为“/”。页数通过 number-of-pages 属性指定。页码为 1 到 number-of-pages 之间的数字。

要将页面链接生成为 <router link> 组件（或在检测到 Nuxt.js 时为 <nuxt-link>），请设置 use-router 属性。然后，HREF 将变为路由器链接的 to 属性。或者，选择使用链接生成器函数来返回路由器链接 to 位置 对象。

如果在你的应用中未检测到 $router，<b-pagination-nav> 将回退到常规 <a> 元素，并且任何 to 位置对象都将转换为标准 URL（如果可能）。

支持以下路由器链接特定属性

  • active-class
  • exact
  • exact-active-class
  • prefetch (<nuxt-link> 特定属性)
  • no-prefetch (<nuxt-link> 特定属性)

有关上述属性的详细信息，请参阅 路由器链接支持 参考部分。

如果你需要对生成的链接 URL 或 <router-link> to 属性进行更精细的控制，你可以将 link-gen 属性设置为一个函数引用，该引用接收两个参数：页码，以及包含两个字段（link 和 page）的对象，其中 page 为页码，link 为内部生成的链接。

link-gen 函数应返回一个字符串（用于 HREF）或一个路由器 to 对象。如果返回值是一个对象，那么将始终生成一个路由器链接（如果检测到 $router）。如果返回值是一个字符串，则默认生成一个标准链接，除非设置了 use-router 属性。如果使用了 to 位置对象，那么 base-url 属性将不起作用。

export default {
  methods: {
    // For regular HREF (or string `to` prop if `use-router` is set)
    linkGen(pageNum) {
      return `/foo/page/${pageNum}`
    },

    // Returning a router-link `to` object
    linkGen(pageNum) {
      return { path: `/foo/page/${pageNum}` }
    },

    // Returning a router-link `to` object with query parameters
    linkGen(pageNum) {
      return {
        path: '/foo/',
        query: { page: pageNum }
      }
    },

    // Returning a router-link `to` object with named route and parameters
    linkGen(pageNum) {
      return {
        name: 'posts',
        params: { post: pageNum }
      }
    }
  }
}

注意：当从 to 位置对象回退到标准链接时（当没有可用的 $router 时），仅使用以下位置属性来生成 URL

  • path（如果没有提供，则默认为页面的当前 URL 路径）
  • 查询
  • hash（如果使用，必须包括前导 #）

不支持 name 路由和 params 的转换。

页码生成

默认情况下，<b-pagination-nav> 在页面链接按钮中呈现页码（1-N）。你可以通过向 page-gen 属性提供函数引用来覆盖此行为。函数引用应接受一个参数，该参数是一个页码（1-N）。page-gen 函数应返回一个字符串。

注意：不支持生成页码字符串中的 HTML 内容。对于基本的 HTML，你可以使用作用域槽 page 来进行更精细的格式化。

示例：使用链接数组生成分页

<template>
  <div class="overflow-auto">
    <b-pagination-nav
      :link-gen="linkGen"
      :page-gen="pageGen"
      :number-of-pages="links.length"
    ></b-pagination-nav>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        links: ['#foo', '#bar', '#baz', '#faz']
      }
    },
    methods: {
      linkGen(pageNum) {
        return this.links[pageNum - 1]
      },
      pageGen(pageNum) {
        return this.links[pageNum - 1].slice(1)
      }
    }
  }
</script>

<!-- b-pagination-nav-links.vue -->

提供页面数组

你可以通过 pages 属性传递链接数组，而不是使用 number-of-pages 自动生成页面链接。当 pages 属性具有长度为 1 或更大的数组时，它将用于生成页面链接。

该数组可以采用两种格式之一

  • 字符串数组，其中每个条目都是一个链接。在此模式下，页面按钮编号将自动设置为 1 到数组中条目的数量。
  • 对象数组，其中每个对象有两个字段：link（必需）和 text（可选）。链接可以是指定链接的字符串，也可以是 to 位置对象。 text 将是页面链接按钮的内容。如果省略 text，则页面按钮内容将默认为页面编号。

当提供字符串链接时，<b-pagination-nav> 将使用常规 <a> 元素，除非设置了 use-router 属性。当链接（在对象数组形式中）是 to 位置对象时，将自动生成路由器链接（如果检测到 $router）。

使用数组格式，链接字符串（和/或位置对象）将按原样使用，并且将忽略 base-url 属性。

<template>
  <b-pagination-nav :pages="pages1" use-router></b-pagination-nav>
  <b-pagination-nav :pages="pages2" use-router></b-pagination-nav>
  <b-pagination-nav :pages="pages3" use-router></b-pagination-nav>
</template>

<script>
export default {
  data() {
    return {
      // Simple array of strings
      pages1: ['?page=1', '?page=2', '?page=3'],
      // Array of objects with string links
      pages2: [
        { link: '?page=1', text: 'One' },
        { link: '?page=2', text: 'Two' },
        { link: '?page=3', text: 'Three' }
      ],
      // Array of objects with router `to` locations
      pages3: [
        { link: { query: { page: 1 } }, text: 'Page 1' },
        { link: { query: { page: 2 } }, text: 'Page 2' },
        { link: { query: { page: 3 } }, text: 'Page 3' }
      ]
    }
  }
}
</script>

<!-- pagination-nav-array.vue -->

自定义外观

限制显示的按钮数量

要限制显示的页面按钮数量（包括省略号，但不包括第一个、上一个、下一个和最后一个按钮），请使用 limit 属性指定所需的页面按钮数量（包括省略号，如果显示）。默认 limit 为 5。支持的最小值为 3。当 limit 设置为 3 时，出于实际目的，不会显示省略号指示符。

可以通过设置 hide-goto-end-buttons 属性来选择隐藏 first 和 last 按钮。

可以通过设置 hide-ellipsis 属性来选择禁用 ellipsis 的显示。

小屏幕支持

在较小的屏幕（即移动设备）上，一些 <b-pagination-nav> 按钮将被隐藏，以最大程度地减少分页界面换行到多行的可能性

  • 省略号指示符将隐藏在 xs 及更小的屏幕上。
  • 页面编号按钮在 xs 及更小的屏幕上最多只能显示 3 个。

这确保了最多只能看到 3 个页码按钮，以及转到第一页、上一页、下一页和最后一页按钮。

按钮内容

<b-pagination-nav> 支持多个属性/插槽，允许您自定义外观。所有 *-text 属性都是纯文本，并且会去除 HTML，但您可以使用它们同名的插槽对应项。

有关所有可用插槽的完整列表，请参阅下面的 插槽 部分。

<template>
  <div class="overflow-auto">
    <!-- Use text in props -->
    <b-pagination-nav
      number-of-pages="10"
      base-url="#"
      first-text="First"
      prev-text="Prev"
      next-text="Next"
      last-text="Last"
    ></b-pagination-nav>

    <!-- Use emojis in props -->
    <b-pagination-nav
      number-of-pages="10"
      base-url="#"
      first-text="⏮"
      prev-text="⏪"
      next-text="⏩"
      last-text="⏭"
      class="mt-4"
    ></b-pagination-nav>

    <!-- Use HTML and sub-components in slots -->
    <b-pagination-nav
      number-of-pages="10"
      base-url="#"
      class="mt-4"
    >
      <template #first-text><span class="text-success">First</span></template>
      <template #prev-text><span class="text-danger">Prev</span></template>
      <template #next-text><span class="text-warning">Next</span></template>
      <template #last-text><span class="text-info">Last</span></template>
      <template #ellipsis-text>
        <b-spinner small type="grow"></b-spinner>
        <b-spinner small type="grow"></b-spinner>
        <b-spinner small type="grow"></b-spinner>
      </template>
      <template #page="{ page, active }">
        <b v-if="active">{{ page }}</b>
        <i v-else>{{ page }}</i>
      </template>
    </b-pagination-nav>
  </div>
</template>

<!-- b-pagination-nav-appearance.vue -->

插槽 page 始终具有作用域，而插槽 first-text、prev-text、next-text 和 last-text 是可选作用域。插槽 ellipsis-text 没有作用域。

插槽 page 可用的作用域变量属性

属性 类型 说明
page 数字 页码（从 1 到 numberOfPages）
index 数字 页码（从 0 到 numberOfPages -1 索引）
active 布尔值 如果该页是活动页
disabled 布尔值 如果页按钮已禁用
content 字符串 默认内容，或 page-gen 函数的结果

插槽 first-text、prev-text、next-text 和 last-text 可用的作用域变量属性

属性 类型 说明
page 数字 页码（从 1 到 numberOfPages）
index 数字 页码（从 0 到 numberOfPages -1 索引）
disabled 布尔值 如果页按钮已禁用

转到第一页/最后一页按钮类型

如果您希望使用第一页和最后一页的按钮转到相应页面，请使用 first-number 和 last-number 属性。

<template>
  <div class="overflow-auto">
    <div>
      <h6>Goto first button number</h6>
      <b-pagination-nav
        v-model="currentPage"
        :number-of-pages="pages"
        base-url="#"
        first-number
      ></b-pagination-nav>
    </div>

    <div class="mt-3">
      <h6>Goto last button number</h6>
      <b-pagination-nav
        v-model="currentPage"
        :number-of-pages="pages"
        base-url="#"
        last-number
      ></b-pagination-nav>
    </div>

    <div class="mt-3">
      <h6>Goto first and last button number</h6>
      <b-pagination-nav
        v-model="currentPage"
        :number-of-pages="pages"
        base-url="#"
        first-number
        last-number
      ></b-pagination-nav>
    </div>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        pages: 100,
        currentPage: 5
      }
    }
  }
</script>

<!-- b-pagination-nav-goto-first-last-number.vue -->

按钮大小

通过将 size 属性设置为 'sm'（用于较小的按钮）或 'lg'（用于较大的按钮）来选择性地更改默认按钮大小。

<template>
  <div class="overflow-auto">
    <div>
      <h6>Small</h6>
      <b-pagination-nav size="sm" number-of-pages="10" base-url="#"></b-pagination-nav>
    </div>

    <div class="mt-3">
      <h6>Default</h6>
      <b-pagination-nav number-of-pages="10" base-url="#"></b-pagination-nav>
    </div>

    <div class="mt-3">
      <h6>Large</h6>
      <b-pagination-nav size="lg" number-of-pages="10" base-url="#"></b-pagination-nav>
    </div>
  </div>
</template>

<!-- b-pagination-nav-size.vue -->

药丸样式

通过设置 pills 属性，轻松切换到药丸样式按钮

<template>
  <div class="overflow-auto">
    <div>
      <h6>Small Pills</h6>
      <b-pagination-nav pills size="sm" number-of-pages="10" base-url="#"></b-pagination-nav>
    </div>

    <div class="mt-3">
      <h6>Default Pills</h6>
      <b-pagination-nav pills number-of-pages="10" base-url="#"></b-pagination-nav>
    </div>

    <div class="mt-3">
      <h6>Large Pills</h6>
      <b-pagination-nav pills size="lg" number-of-pages="10" base-url="#"></b-pagination-nav>
    </div>
  </div>
</template>

<!-- b-pagination-nav-pills.vue -->

注意：药丸样式需要 BootstrapVue 的自定义 CSS/SCSS。

对齐

默认情况下，分页组件左对齐。通过将 align 属性设置为相应的值，可以将对齐方式更改为 center、right（right 是 end 的别名）或“填充”。

<template>
  <div class="overflow-auto">
    <div>
      <h6>Left alignment (default)</h6>
      <b-pagination-nav number-of-pages="10" base-url="#"></b-pagination-nav>
    </div>

    <div class="mt-3">
      <h6 class="text-center">Center alignment</h6>
      <b-pagination-nav number-of-pages="10" base-url="#" align="center"></b-pagination-nav>
    </div>

    <div class="mt-3">
      <h6 class="text-right">Right (end) alignment</h6>
      <b-pagination-nav number-of-pages="10" base-url="#" align="right"></b-pagination-nav>
    </div>

    <div class="mt-3">
      <h6 class="text-center">Fill alignment</h6>
      <b-pagination-nav number-of-pages="10" base-url="#" align="fill"></b-pagination-nav>
    </div>
  </div>
</template>

<!-- b-pagination-nav-alignment.vue -->

自动当前页检测和 v-model 支持

<b-pagination-nav> 将尝试根据页面的当前 URL 或 $route（如果检测到路由器）自动检测哪个页面按钮应该处于活动状态。在无法检测到页面时，将没有页面编号按钮处于活动状态，并且第一个、上一个、下一个和最后一个按钮将处于禁用状态，直到单击页面按钮。

v-model 是可选支持的（由 input 事件更新，并绑定到 value 属性）。最初将 v-model 设置为 null（默认值）将触发自动活动页面检测，随后将使用当前页码（从 1 到页面数）进行更新。如果你最初将 v-model 设置为 1 或更大的值，则不会发生自动页面检测（直到用户单击页面按钮后），并且由 v-model 指定的页面将被设置为 active。

要禁用自动活动页面检测，请将 no-page-detect 属性设置为 true。

注意：自动页面检测需要循环遍历所有可能的页面链接，直到检测到匹配项。对于较大的 number-of-pages，此检查可能需要一些时间，因此你可能希望通过 v-model 和 no-page-detect 属性手动控制哪个页面处于活动状态。

防止选择页面

你可以监听 page-click 事件，该事件提供了一个选项来防止选择页面。该事件带有两个参数

  • bvEvent：BvEvent 对象。调用 bvEvent.preventDefault() 取消页面选择
  • page：要选择的页码（从 1 开始）

出于无障碍原因，当使用 page-click 事件来防止选择页面时，你应该提供一些通知方式，向用户说明为什么无法选择该页面。建议对 <b-pagination-nav> 组件使用 disabled 属性，而不是使用 page-click 事件（因为 disabled 对屏幕阅读器用户来说更直观）。

无障碍

<b-pagination-nav> 组件提供了许多功能来支持辅助技术用户，例如 aria- 属性和键盘导航。

ARIA 标签

<b-pagination-nav> 提供了各种 *-label-* 属性，用于设置组件内各种元素的 aria-label 属性，这将帮助辅助技术用户。

属性 aria-label 内容默认值
label-first-page "转到第一页"
label-prev-page "转到上一页"
label-next-page "转到下一页"
label-last-page "转到最后一页"
label-page "转到第"，后面加上页码
aria-label "分页"，应用于外部分页容器

label-page 可选择接受一个函数来生成 aria-label。该函数传递一个参数，即页码（从 1 到页数索引）。

你可以通过将属性设置为一个空字符串 ('') 来删除任何标签，但除非按钮文本的内容以文字方式传达其目的，否则不建议这样做。

键盘导航

<b-pagination-nav> 支持标准 Tab 键导航。

另请参阅

请参阅 路由器支持 参考页面，了解路由器链接特定的属性。

对于组件（例如 <b-table>）或分页列表的分页控制，请使用 <b-pagination> 组件。

组件参考

<b-pagination-nav>

查看源代码

属性

所有属性默认值均可 全局配置。

属性
(点击按升序排序)
类型
(点击按升序排序)
默认值
说明
active
布尔值false设置为 `true` 时，将组件置于活动状态并使用活动样式
active-class
字符串<router-link> 属性：配置链接处于活动状态时应用的活动 CSS 类。通常，您会希望将其设置为类名“active”
align
字符串'left'页面按钮的对齐方式：“start”（或“left”）、“center”、“end”（或“right”）或“fill”
append
布尔值false<router-link> 属性：设置 append 属性始终将相对路径附加到当前路径
aria-label
字符串'Pagination'要置于分页控件的“aria-label”属性中的值
base-url
字符串'/'自动生成页面链接时要使用的基本 URL
disabled
布尔值false当设置为 `true` 时，将禁用组件的功能并将其置于禁用状态
ellipsis-class
v2.3.0+ 		Array 或 Object 或 String要应用于“省略号”占位符的类
ellipsis-text
字符串'…'要置于省略号占位符中的内容
exact
布尔值false<router-link> 属性：默认活动类匹配行为是包含匹配。设置此属性会强制模式与路由完全匹配
exact-active-class
字符串<router-link> 属性：配置链接在使用完全匹配时处于活动状态时应用的活动 CSS 类。通常，您会希望将其设置为类名“active”
exact-path
布尔值false<router-link> 属性：允许仅使用 URL 的路径部分进行匹配，有效地忽略查询和哈希部分
exact-path-active-class
字符串<router-link> 属性：配置链接在使用完全路径匹配时处于活动状态时应用的活动 CSS 类。通常，您会希望将其设置为类名“active”
first-class
v2.3.0+ 		Array 或 Object 或 String应用于“转到第一页”按钮的类
first-number
v2.3.0+ 		布尔值false显示第一页页码，而不是“转到第一页”按钮
first-text
字符串'«'放置在“转到第一页”按钮中的内容
hide-ellipsis
布尔值false不显示省略号按钮
hide-goto-end-buttons
布尔值false隐藏“转到第一页”和“转到最后一页”按钮
href
字符串<b-link> prop：表示标准 a 链接的链接目标 URL
label-first-page
字符串'转到第一页'放置在“转到第一页”按钮的 'aria-label' 属性中的值
label-last-page
字符串'转到最后一页'放置在“转到最后一页”按钮的 'aria-label' 属性中的值
label-next-page
字符串'转到下一页'放置在“转到下一页”按钮的 'aria-label' 属性中的值
label-page
函数或 字符串'转到页面'放置在“转到页面”按钮的 'aria-label' 属性中的值。页码将自动添加在前面
label-prev-page
字符串'转到上一页'放置在“转到上一页”按钮的 'aria-label' 属性中的值
last-class
v2.3.0+ 		Array 或 Object 或 String应用于“转到最后一页”按钮的类
last-number
v2.3.0+ 		布尔值false显示最后一页页码，而不是“转到最后一页”按钮
last-text
字符串'»'放置在“转到最后一页”按钮中的内容
limit
数字或 字符串5要显示的最大按钮数（包括省略号，如果显示，但不包括书挡按钮）
link-gen
函数链接生成器函数。有关详细信息，请参阅文档
next-class
v2.3.0+ 		Array 或 Object 或 String应用于“转到下一页”按钮的类
next-text
字符串'›'放置在“转到下一页”按钮中的内容
no-page-detect
布尔值false禁用自动检测当前页
no-prefetch
布尔值false<nuxt-link> prop：为了提高 Nuxt.js 应用程序的响应能力，当链接将在视口中显示时，Nuxt.js 将自动预取代码拆分的页面。为特定链接设置 `no-prefetch` 将禁用此功能
number-of-pages
数字或 字符串1总页数
page-class
v2.3.0+ 		Array 或 Object 或 String应用于“转到第 # 页”按钮的类
page-gen
函数页码生成器函数。有关详细信息，请参阅文档
pages
数组页码和链接数组
pills
v2.1.0+ 		布尔值false将药丸样式应用于分页按钮
预取
v2.15.0+ 		布尔值null<nuxt-link> prop：为了提高 Nuxt.js 应用程序的响应能力，当链接将在视口中显示时，Nuxt.js 将自动预取代码拆分的页面。将 `prefetch` 设置为 `true` 或 `false` 将覆盖 `router.prefetchLinks` 的默认值
prev-class
v2.3.0+ 		Array 或 Object 或 String应用于“转到上一页”按钮的类
prev-text
字符串'‹'放置在转到上一页按钮中的内容
rel
字符串null<b-link> prop：设置呈现的链接上的 `rel` 属性
replace
布尔值false<router-link> prop：设置 replace prop 将在单击时调用 `router.replace()` 而不是 `router.push()`，因此导航不会留下历史记录
router-component-name
v2.15.0+ 		字符串<b-link> prop：BootstrapVue 在 `<router-link>` 和 `<nuxt-link>` 之间自动检测。在希望使用基于 `<router-link>` 的第三方链接组件的情况下，将此 prop 设置为组件名称。例如，如果使用 Gridsome，则将其设置为“g-link”（注意仅将 `<router-link>` 特定的 prop 传递给组件）
size
字符串呈现的按钮的大小：“sm”、“md”（默认）或“lg”
target
字符串'_self'<b-link> prop：设置呈现的链接上的 `target` 属性
to
对象 或 字符串<router-link> prop：表示链接的目标路由。单击时，to prop 的值将在内部传递给 `router.push()`，因此该值可以是字符串或位置描述符对象
use-router
布尔值false在自动生成页面链接时呈现路由链接而不是链接
value
v-model 		布尔值 或 数字 或 字符串null当前页码，从 1 开始

<b-pagination-nav> 支持生成 <router-link> 或 <nuxt-link> 组件（如果使用 Nuxt.js）。有关路由链接（或 nuxt 链接）特定 prop 的更多详细信息，请参阅 路由支持 参考部分。

v-model

属性
事件
value输入

插槽

名称
范围
说明
ellipsis-text 否“...” 指示器内容。无范围
first-text “转到第一页”按钮内容。可选范围
last-text “转到最后一页”按钮内容。可选范围
next-text “转到下一页”按钮内容。可选范围
page 页码按钮内容。始终有范围
prev-text “转到上一页”按钮内容。可选范围

事件

事件
参数
说明
更改
  1. page - 选定的页码（从 `1` 开始）
当页面通过用户交互更改时发出
输入
  1. page - 选定的页码（从 `1` 开始），如果没有找到页面，则为 `null`
当页面通过用户交互或以编程方式更改时发出
page-click v2.17.0+
  1. bvEvent - `BvEvent` 对象。调用 `bvEvent.preventDefault()` 以取消页面选择
  2. page - 要选择的页码（从 `1` 开始）
当单击页面按钮时发出。可取消

导入单个组件

你可以通过以下命名导出将单个组件导入到你的项目中

组件
命名导出
导入路径
<b-pagination-nav>BPaginationNavbootstrap-vue

示例

import { BPaginationNav } from 'bootstrap-vue'
Vue.component('b-pagination-nav', BPaginationNav)

作为 Vue.js 插件导入

此插件包含上面列出的所有单个组件。插件还包括任何组件别名。

命名导出
导入路径
PaginationNavPluginbootstrap-vue

示例

import { PaginationNavPlugin } from 'bootstrap-vue'
Vue.use(PaginationNavPlugin)