分頁導覽

用於頁面導航,提供快速的第一頁、上一頁、下一頁、最後一頁等按鈕,支援一般連結或路由連結。

概觀

<b-pagination-nav> 是一個自訂的輸入元件,提供頁面導覽。透過 number-of-pages prop 設定要顯示的總頁數。頁碼從 1 開始,最大到 number-of-pages

b-pagination-nav 會嘗試自動偵測哪個頁面連結應為目前的頁面按鈕,會根據目前頁面的網址(透過 $route 偵測,如果沒偵測到 $router,就會使用瀏覽器的位置網址)

請注意: <b-pagination-nav> 用於導覽至新的頁面網址。如果是控制頁內元件的頁面導航(像是表格或列表的頁面導航),請改用 <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 prop 是 '/'。頁碼數量會透過 number-of-pages prop 指定。頁碼從 1 開始,最大到 number-of-pages

要產生頁面連結作為 ​​<router link>​​ 組件(或如果偵測到 ​​Nuxt.js​​ 的話就作為 ​​<nuxt-link>​​),請設定 use-router 屬性。HREF 接著會成為 router 連結的 to 屬性。或者,也可以選擇使用連結產生器函式來傳回 router 連結的 to 位置 物件。

如果你的應用程式中沒有偵測到 $router<b-pagination-nav> 將會備援成一般的 <a> 元素,並且任何 to 位置物件都將會轉換成標準 URL(如果可行的話)。

支援以下特定於 router 連結的屬性

  • active-class
  • exact
  • exact-active-class
  • prefetch<nuxt-link> 獨有的屬性)
  • no-prefetch<nuxt-link> 獨有的屬性)

有關上述屬性的詳情,請參閱 Router Link Support 參考部分。

如果你需要更細緻地控制所產生的連結 URL 或 <router-link> to 屬性,你可以將 link-gen 屬性設定為接受兩個引數的函式參照:頁碼,以及包含兩個欄位的物件(linkpage),其中 page 是頁碼,link 是內部產生的連結。

link-gen 函式應傳回字串(用於 HREF)或 router to 物件。如果傳回值為物件,則永遠會產生 router 連結(如果偵測到 $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 路徑)
  • query
  • hash(如果使用,必須包括開頭的 #

不支援轉換 name 路由和 params

頁碼產生

預設情況下,<b-pagination-nav> 會在頁面連結的按鈕中呈現頁碼(1-N)。你可以透過提供 page-gen 屬性的函式參照來覆寫此行為。函式參照應接受單一引數,即頁碼(1-N)。page-gen 函式應傳回字串。

注意:所產生頁碼字串中的 HTML 內容受支援。對於基本 HTML,你可以使用作用於scoped slot 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 -->

提供頁面陣列

除了使用 number-of-pages 自動產生頁面連結外,也可以透過 pages 屬性傳遞一個連結陣列。當 pages 屬性擁有一個長度為 1 或更大的陣列時,它將會被用來產生頁面連結。

陣列可以有兩種格式

  • 字串陣列,其中每個項目均為一個連結。此模式中,頁面按鈕編號將會自動設定為 1 至陣列中的項目數。
  • 物件陣列,陣列中每一個物件具有兩個欄位: link(必要)和 text(選擇性)。link 可以是一個指定連結的字串或 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 屬性來指定希望顯示的頁面按鈕數目(包括省格符號,如果顯示)。預設 limit5。支援的最小值是 3。當 limit 被設定為 3 時,在實用目上是不會顯示省格符號指示器的。

透過設定 hide-goto-end-buttons 屬性,可以選擇性隱藏 firstlast 按鈕。

透過設定 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-textprev-textnext-textlast-text 可選擇限定範圍。插槽 ellipsis-text 沒有限定範圍。

可供 page 插槽使用的限定範圍變數屬性

屬性 類型 描述
page 數字 頁碼(從 1numberOfPages
index 數字 頁碼(索引從 0numberOfPages -1
active 布林值 若頁面為目前活動頁面
disabled 布林值 若頁面按鈕已停用
content 字串 預設內容,或 page-gen 函式的結果

可供 first-textprev-textnext-textlast-text 插槽使用的限定範圍變數屬性

屬性 類型 描述
page 數字 頁碼(從 1numberOfPages
index 數字 頁碼(索引從 0numberOfPages -1
disabled 布林值 若頁面按鈕已停用

前往第一/最後按鈕類型

如果您希望有按鈕顯示第一個和最後一個頁碼並前往相應的頁面,請使用 first-numberlast-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 屬性設定為適當的值,將對齊方式變更為 centerrightrightend 的別名)或 'fill'。

<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> 會根據頁面的目前網址或 $route(如果偵測到路由器),嘗試自動偵測哪個頁面按鈕應為目前活動頁面。如果它無法偵測到頁面,則沒有任何頁碼按鈕會處於目前活動狀態,且在點選頁面按鈕之前,第一個、前一個、下一個和最後一個按鈕將處於停用狀態。

(根據 input 事件更新,並與 value 屬性關聯)v-model 具有選擇性支援。最初將 v-model 設定為 null(預設值)將觸發自動偵測目前活動頁面,並隨後更新為目前頁碼(索引從 1 到頁面數量)。如果您最初將 v-model 設定為 1 或更大值,則不會執行自動頁面偵測(直到使用者點選頁面按鈕後),而且由 v-model 指定的頁面將會設為 active

若要停用自動偵測目前活動頁面,請將 no-page-detect 屬性設定為 true

注意:自動頁面偵測需要迴圈所有可能的頁面連結,直到偵測到一個符合的結果。對於較大的 number-of-pages,這項檢查可能會花費一些時間,因此您可能需要透過 v-modelno-page-detect 道具手動控制哪個頁面是目前的頁面。

避免選擇某個頁面

您可以監聽提供選項以避免某個頁面被選取的 page-click 事件。此事件會傳送兩個參數

  • bvEventBvEvent 物件。呼叫 bvEvent.preventDefault() 以取消選取頁面
  • page:要選取的頁碼(從 1 開始)

基於輔助功能的考量,當使用 page-click 事件來避免頁面被選取時,您應該提供一些方法來通知使用者為何無法選取該頁面。建議使用 disabled 屬性於 <b-pagination-nav> 組件中,而非使用 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 狀態,且套用 active 樣式
active-class
字串<router-link> prop:設定鏈結 active 時套用的 active CSS 類別。通常你會想要將此設定為類別名稱「active」
align
字串'left'頁面按鈕的對齊方式:'start'(或 'left')、'center'、'end'(或 'right')或 'fill'
append
布林值false<router-link> prop:設定 append prop 會將相對路徑永遠附加到當前路徑
aria-label
字串'Pagination'要放入分頁控制項 'aria-label' 屬性的值
base-url
字串'/'自動產生頁面連結時要使用的基本 URL
disabled
布林值false如果設定為 `true`,會停用組件的功能,並將其置於停用狀態
ellipsis-class
v2.3.0+
ArrayObjectString套用至『省略符號』佔位符的類別
ellipsis-text
字串'…'要放入省略符號佔位符的內容
exact
布林值false<router-link> prop:預設啟用包含比對模式。設定此 prop 會強制模式與路由完全比對
exact-active-class
字串<router-link> prop:設定鏈結 active 時套用的 active CSS 類別,且須完全比對路由。通常你會想要將此設定為類別名稱「active」
exact-path
布林值false<router-link> prop:允許僅使用 URL 的路徑區段進行比對,實際上會忽略查詢字串和雜湊區段
exact-path-active-class
字串<router-link> prop:設定鏈結 active 時套用的 active CSS 類別,且須完全比對路徑。通常你會想要將此設定為類別名稱「active」
first-class
v2.3.0+
ArrayObjectString套用至「前往第一頁」按鈕的類別
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
字串'Go to first page'要放入前往第一頁按鈕的 'aria-label' 屬性的值
label-last-page
字串'Go to last page'要放入前往最後一頁按鈕的 'aria-label' 屬性的值
label-next-page
字串'Go to next page'要放入前往下一頁按鈕的 'aria-label' 屬性的值
label-page
FunctionString'Go to page'要放入前往第 N 頁按鈕的 'aria-label' 屬性的值。頁碼會自動加到前面
label-prev-page
字串'Go to previous page'要放入前往上一頁按鈕的 'aria-label' 屬性的值
last-class
v2.3.0+
ArrayObjectString套用至「前往最後一頁」按鈕的類別
last-number
v2.3.0+
布林值false顯示最後一頁的頁碼,而非顯示前往最後一頁按鈕
last-text
字串'»'要放入前往最後一頁按鈕的內容
limit
NumberString5顯示按鈕的最大數量(包括省略符號,但不包括按鈕分隔符號)
link-gen
函式連結產生函式。請參閱文件以取得詳細資訊
next-class
v2.3.0+
ArrayObjectString要套用至「前往下紐頁面」按鈕的類別
next-text
字串'›'要放置在前往下紐頁面按鈕中的內容
no-page-detect
布林值false停用自動偵測目前頁面
no-prefetch
布林值false<nuxt-link> 屬性:為了提升 Nuxt.js 應用程式的回應性,當連結會顯示在視窗中時,Nuxt.js 會自動預先讀取使用程式碼分割的頁面。設定 `no-prefetch` 會針對特定連結停用此功能
number-of-pages
NumberString1總頁數
page-class
v2.3.0+
ArrayObjectString要套用至「前往第 # 頁」按鈕的類別
page-gen
函式頁碼產生函式。請參閱文件以取得詳細資訊
pages
陣列頁碼和連結陣列
pills
v2.1.0+
布林值false套用圓形樣式至分頁按鈕
prefetch
v2.15.0+
布林值null<nuxt-link> 屬性:為了提升 Nuxt.js 應用程式的回應性,當連結會顯示在視窗中時,Nuxt.js 會自動預先讀取使用程式碼分割的頁面。將 `prefetch` 設定為 `true` 或 `false` 會覆寫 `router.prefetchLinks` 的預設值
prev-class
v2.3.0+
ArrayObjectString要套用至「前往上一頁面」按鈕的類別
prev-text
字串'‹'要放置在前往上一頁面按鈕中的內容
rel
字串null<b-link> 屬性:設定呈示連結的 `rel` 屬性
replace
布林值false<router-link> 屬性:設定 replace 屬性會在按一下時呼叫 `router.replace()` 而非 `router.push()`,因此導覽不會留下歷史記錄
router-component-name
v2.15.0+
字串<b-link> 屬性:BootstrapVue 會在 `<router-link>` 和 `<nuxt-link>` 之間自動偵測。如果您想使用基於 `<router-link>` 的第三方連結元件,請將此屬性設定為元件名稱。例如,如果您使用 Gridsome,可將它設定為 'g-link'(請注意,只會傳遞 `<router-link>` 特有的屬性至元件)
size
字串呈示按鈕的大小:'sm'、'md'(預設)或 'lg'
target
字串'_self'<b-link> 屬性:設定呈示連結的 `target` 屬性
to
Object字串<router-link> 屬性:表示連結的目標路由。按一下時,to 屬性的值會在內部傳遞至 `router.push()`,因此值可以是字串或位置描述物件
use-router
布林值false自動產生頁面連結時,呈示路由連結而非連結
value
v-model
Boolean數字字串null目前的頁碼,從 1 開始

<b-pagination-nav> 支援產生 <router-link><nuxt-link> 元件(如果使用 Nuxt.js)。有關路由連結(或 nuxt 連結)特有屬性的更多詳細資料,請參閱 路由支援 參考區段。

v-model

屬性
事件
valueinput

外框

名稱
有範圍
描述
ellipsis-text '...' 指示內容。沒有範圍
first-text 「前往第一頁」按鈕的內容。可選擇範圍
last-text 「前往最後一頁」按鈕的內容。可選擇範圍
next-text 「前往下紐頁」按鈕的內容。可選擇範圍
page 頁碼按鈕的內容。總是會有範圍
prev-text 「前往上一頁」按鈕的內容。可選擇範圍

事件

事件
參數
描述
change
  1. page - 已選的頁碼(從 `1` 開始)
透過使用者互動變更頁數時發出
input
  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)