概觀
<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>
會產生一般的連結標籤,設定 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
屬性設定為接受兩個引數的函式參照:頁碼,以及包含兩個欄位的物件(link
和 page
),其中 page
是頁碼,link
是內部產生的連結。
link-gen
函式應傳回字串(用於 HREF)或 router to
物件。如果傳回值為物件,則永遠會產生 router 連結(如果偵測到 $router
)。如果傳回值為字串,則在使用預設方式產生標準連結,除非已設定 use-router
屬性。如果使用 to
位置物件,則 base-url
屬性將不會生效。
export default {
methods: {
linkGen(pageNum) {
return `/foo/page/${pageNum}`
},
linkGen(pageNum) {
return { path: `/foo/page/${pageNum}` }
},
linkGen(pageNum) {
return {
path: '/foo/',
query: { page: pageNum }
}
},
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>
提供頁面陣列
除了使用 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 {
pages1: ['?page=1', '?page=2', '?page=3'],
pages2: [
{ link: '?page=1', text: 'One' },
{ link: '?page=2', text: 'Two' },
{ link: '?page=3', text: 'Three' }
],
pages3: [
{ link: { query: { page: 1 } }, text: 'Page 1' },
{ link: { query: { page: 2 } }, text: 'Page 2' },
{ link: { query: { page: 3 } }, text: 'Page 3' }
]
}
}
}
</script>
自訂顯示
如要限制顯示的頁面按鈕的數目(包括省格符號,但排除上一個、下一個和最後一個按鈕),請使用 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">
<b-pagination-nav
number-of-pages="10"
base-url="#"
first-text="First"
prev-text="Prev"
next-text="Next"
last-text="Last"
></b-pagination-nav>
<b-pagination-nav
number-of-pages="10"
base-url="#"
first-text="⏮"
prev-text="⏪"
next-text="⏩"
last-text="⏭"
class="mt-4"
></b-pagination-nav>
<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>
插槽 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>
可選擇透過將 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>
圖形按鈕樣式
透過設定 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>
附註:圖形按鈕樣式需要 BootstrapVue 的自訂 CSS/SCSS。
對齊
預設情況下,分頁元件靠左對齊。透過將 align
屬性設定為適當的值,將對齊方式變更為 center
、right
(right
是 end
的別名)或 '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>
自動偵測目前頁面和 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-model
與 no-page-detect
道具手動控制哪個頁面是目前的頁面。
避免選擇某個頁面
您可以監聽提供選項以避免某個頁面被選取的 page-click
事件。此事件會傳送兩個參數
bvEvent
: BvEvent
物件。呼叫 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>
組件。