跳到內容
開始使用

分頁

導覽 Pagination

分頁用在同一份列表分成很多頁的時候,例如新聞列表、搜尋結果,讓讀者切換到第幾頁,或往前、往後一頁。頁數多時,中間的頁碼會收成「…」,第一頁、最後一頁和目前頁碼的前後一頁一直看得到(見上方的預覽)。分頁元件只有這一排按鈕,換頁之後要顯示哪些內容,由網站自己處理。只有兩三組不同的內容要切換時,請改用「頁籤」。

部位說明
上一頁按鈕左邊的箭頭。在第一頁時變淡,不能按。螢幕閱讀器唸作「上一頁」。
頁碼每一頁一個按鈕,螢幕閱讀器唸作「第 3 頁」這樣的完整說法。
目前頁碼讀者現在所在的那一頁,用主題的主色當底,文字用和底色對比的顏色。
省略號頁數多時代替中間收起來的頁碼,只是提示,不能按。
下一頁按鈕右邊的箭頭。在最後一頁時變淡,不能按。螢幕閱讀器唸作「下一頁」。
焦點框用鍵盤選到任一個按鈕時出現的外框,讓不用滑鼠的人知道目前在哪裡。顏色跟著主題。
類型 說明
建議 把分頁放在列表的下方,讀者看完這一頁的內容後,自然就會看到下一頁的按鈕。
建議 每頁的筆數在同一個網站保持一致,讀者才能估計還有多少內容。
建議 手機上保持預設的「目前頁碼前後各一頁」。這一排按鈕不會換行,前後顯示的頁數越多,越容易超出窄畫面。
避免 只有一頁內容時,不要顯示分頁。
避免 不要用分頁切換不同類別的內容,例如「慈善」「醫療」;依分類篩選同一份列表請用「膠囊標籤」。

目前顯示:DefaultGreen Natural(示意)。在頁首的「主題」可以切換。 查看所有主題

  • 預設變體: 用元件本身的預設變體。
  • 和預設主題不同的地方: 沒有。這就是預設主題,其他主題沒有特別指定的地方都沿用它。
  • 預設變體: 主題不決定預設變體:用元件本身的預設變體(各網站自己的預設變體要等網站設定檔,還沒有實作)。
  • 和預設主題不同的地方: (以下都是示意值)只有這個元件用到的顏色:主色、品牌底色(襯在內容後的品牌色塊)、主色上的文字。其餘和預設主題一樣。 看完整的顏色對照

上方的大預覽會跟著頁首的「主題」和「色彩模式」一起變。

以下是給工程師的安裝與 API 說明,美編(設計)、網站的編輯和致遠(廠商)可以略過。

Storybook(給工程師逐一檢查元件狀態的工具網站,在本機用 pnpm run heroui:storybook 開啟)目前只收錄 HeroUI 的元件,還沒有 <tc-pagination> 的頁面;這一段的範例和 API 表就是它的說明。

<tc-pagination> 提供分頁導覽:上一頁、頁碼、下一頁。目前頁碼以品牌主色凸顯並標記 aria-current="page",頁數過多時以省略號收合。下方為可互動的真實元件:

頁數過多時,會依 sibling-count(目前頁碼兩側的頁數)與首/末頁收合中間範圍:

<link rel="stylesheet" href="@tzuchi/tokens/tokens.css" />
<script type="module" src="@tzuchi/components/cdn"></script>
<tc-pagination total="8" page="1"></tc-pagination>
<script>
document.querySelector('tc-pagination').addEventListener('tc-page-change', (e) => {
console.log('目前頁碼:', e.detail.page);
});
</script>
import { TcPagination } from '@tzuchi/react';
<TcPagination total={8} page={page} onTcPageChange={(e) => setPage(e.detail.page)} />;
事件名稱detail說明
tc-page-change{ page: number }頁碼改變時發出(會冒泡)。

下表自 Custom Elements Manifest 自動產生:

Attribute Type Default Description
total number 1 總頁數。
page number 1 目前頁碼(1 起算,會反映至屬性)。
sibling-count number 1 目前頁碼兩側固定顯示的頁數,預設 1。
aria-label-text string '分頁導覽' 導覽區域的無障礙標籤,套用至 <nav> 的 aria-label。
  • 外層為 <nav aria-label>,頁碼與上一頁/下一頁皆為原生 <button>,支援鍵盤 Enter / Space。
  • 目前頁碼標記 aria-current="page",每個頁碼具有 aria-label(如「第 3 頁」)。
  • 第一頁時停用「上一頁」、最後一頁時停用「下一頁」(透過原生 disabled,非 pointer-events:none)。
  • :focus-visible 焦點環使用 --tc-focus-ring-* token。