分頁
用法
章節連結:用法分頁用在同一份列表分成很多頁的時候,例如新聞列表、搜尋結果,讓讀者切換到第幾頁,或往前、往後一頁。頁數多時,中間的頁碼會收成「…」,第一頁、最後一頁和目前頁碼的前後一頁一直看得到(見上方的預覽)。分頁元件只有這一排按鈕,換頁之後要顯示哪些內容,由網站自己處理。只有兩三組不同的內容要切換時,請改用「頁籤」。
組成
章節連結:組成| 部位 | 說明 |
|---|---|
| 上一頁按鈕 | 左邊的箭頭。在第一頁時變淡,不能按。螢幕閱讀器唸作「上一頁」。 |
| 頁碼 | 每一頁一個按鈕,螢幕閱讀器唸作「第 3 頁」這樣的完整說法。 |
| 目前頁碼 | 讀者現在所在的那一頁,用主題的主色當底,文字用和底色對比的顏色。 |
| 省略號 | 頁數多時代替中間收起來的頁碼,只是提示,不能按。 |
| 下一頁按鈕 | 右邊的箭頭。在最後一頁時變淡,不能按。螢幕閱讀器唸作「下一頁」。 |
| 焦點框 | 用鍵盤選到任一個按鈕時出現的外框,讓不用滑鼠的人知道目前在哪裡。顏色跟著主題。 |
該做與不該做
章節連結:該做與不該做| 類型 | 說明 |
|---|---|
| 建議 | 把分頁放在列表的下方,讀者看完這一頁的內容後,自然就會看到下一頁的按鈕。 |
| 建議 | 每頁的筆數在同一個網站保持一致,讀者才能估計還有多少內容。 |
| 建議 | 手機上保持預設的「目前頁碼前後各一頁」。這一排按鈕不會換行,前後顯示的頁數越多,越容易超出窄畫面。 |
| 避免 | 只有一頁內容時,不要顯示分頁。 |
| 避免 | 不要用分頁切換不同類別的內容,例如「慈善」「醫療」;依分類篩選同一份列表請用「膠囊標籤」。 |
在目前主題下的樣子
章節連結:在目前主題下的樣子目前顯示:DefaultGreen Natural(示意)。在頁首的「主題」可以切換。 查看所有主題
- 預設變體: 用元件本身的預設變體。
- 和預設主題不同的地方: 沒有。這就是預設主題,其他主題沒有特別指定的地方都沿用它。
- 預設變體: 主題不決定預設變體:用元件本身的預設變體(各網站自己的預設變體要等網站設定檔,還沒有實作)。
- 和預設主題不同的地方: (以下都是示意值)只有這個元件用到的顏色:主色、品牌底色(襯在內容後的品牌色塊)、主色上的文字。其餘和預設主題一樣。 看完整的顏色對照
上方的大預覽會跟著頁首的「主題」和「色彩模式」一起變。
給工程師
章節連結:給工程師以下是給工程師的安裝與 API 說明,美編(設計)、網站的編輯和致遠(廠商)可以略過。
Storybook(給工程師逐一檢查元件狀態的工具網站,在本機用 pnpm run heroui:storybook 開啟)目前只收錄 HeroUI 的元件,還沒有 <tc-pagination> 的頁面;這一段的範例和 API 表就是它的說明。
<tc-pagination> 提供分頁導覽:上一頁、頁碼、下一頁。目前頁碼以品牌主色凸顯並標記 aria-current="page",頁數過多時以省略號收合。下方為可互動的真實元件:
頁數過多時,會依 sibling-count(目前頁碼兩側的頁數)與首/末頁收合中間範圍:
純 HTML
章節連結:純 HTML<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>React
章節連結:Reactimport { TcPagination } from '@tzuchi/react';
<TcPagination total={8} page={page} onTcPageChange={(e) => setPage(e.detail.page)} />;事件
章節連結:事件| 事件名稱 | detail | 說明 |
|---|---|---|
tc-page-change | { page: number } | 頁碼改變時發出(會冒泡)。 |
API
章節連結:API下表自 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。 |
無障礙(Accessibility)
章節連結:無障礙(Accessibility)- 外層為
<nav aria-label>,頁碼與上一頁/下一頁皆為原生<button>,支援鍵盤 Enter / Space。 - 目前頁碼標記
aria-current="page",每個頁碼具有aria-label(如「第 3 頁」)。 - 第一頁時停用「上一頁」、最後一頁時停用「下一頁」(透過原生
disabled,非pointer-events:none)。 :focus-visible焦點環使用--tc-focus-ring-*token。