頁籤
用法
章節連結:用法頁籤讓讀者在同一個地方切換幾組同一層級的內容,例如「總覽」「最新消息」,不用離開這一頁,一次只看一組。它有兩種版面:寬版(web,預設)的頁籤依文字長短排成一列;窄版(mobile)的頁籤平分整列的寬度,適合手機上的少數幾個頁籤。頁籤元件只有上面這一排頁籤,下面要換成哪一組內容,由網站自己處理。要前往另一個頁面請用「導覽列」或「連結」;同一份列表分成很多頁時請用「分頁」;依分類篩選同一份列表(例如只看「慈善」的消息)請用「膠囊標籤」,頁籤用在切換不同的內容區塊。
組成
章節連結:組成| 部位 | 說明 |
|---|---|
| 頁籤列 | 一排頁籤,下方有一條分隔線。寬版依文字長短排列;窄版每個頁籤一樣寬,撐滿整列。 |
| 頁籤文字 | 必填。每個頁籤的名稱,只排一行,不會換行。螢幕閱讀器會唸出這段文字,也會說出它是不是目前選中的頁籤。 |
| 前置圖示 | 可省略。放在文字前面的小圖示,用來補充文字,不能取代文字。 |
| 選取底線 | 目前選中的頁籤,文字變粗、改用主題的主色,下方加一條主色底線。 |
| 停用狀態 | 暫時不能選的頁籤會變淡,點了不會切換。 |
| 焦點框 | 用鍵盤選到頁籤時出現的外框。用左右方向鍵切換頁籤,Home、End 鍵跳到第一個、最後一個。顏色跟著主題。 |
該做與不該做
章節連結:該做與不該做| 類型 | 說明 |
|---|---|
| 建議 | 頁籤名稱寫短,例如「總覽」「最新消息」。頁籤不會換行,也不會自動捲動,太多或太長時會超出畫面。 |
| 建議 | 每個頁籤放同一層級、可以任意切換的內容,讀者先看哪一個都可以。 |
| 建議 | 手機上用窄版(mobile),而且只放少數幾個頁籤,每個頁籤的文字才放得下。 |
| 建議 | 預先選好讀者最常看的頁籤。沒有指定時,元件會自動選第一個可以選的頁籤。 |
| 避免 | 不要用頁籤做「第一步、第二步」這種要照順序完成的流程,也不要用頁籤換到另一個頁面。 |
| 避免 | 不要留下一直都不能選的頁籤;用不到就拿掉,暫時不能選時最好在附近說明原因。 |
在目前主題下的樣子
章節連結:在目前主題下的樣子目前顯示:DefaultGreen Natural(示意)。在頁首的「主題」可以切換。 查看所有主題
- 預設變體: 用元件本身的預設變體。
- 和預設主題不同的地方: 沒有。這就是預設主題,其他主題沒有特別指定的地方都沿用它。
- 預設變體: 主題不決定預設變體:用元件本身的預設變體(各網站自己的預設變體要等網站設定檔,還沒有實作)。
- 和預設主題不同的地方: (以下都是示意值)只有這個元件用到的顏色:主色、品牌底色(襯在內容後的品牌色塊)、焦點框(用鍵盤選到時的外框)。其餘和預設主題一樣。 看完整的顏色對照
上方的大預覽會跟著頁首的「主題」和「色彩模式」一起變。
給工程師
章節連結:給工程師以下是給工程師的安裝與 API 說明,美編(設計)、網站的編輯和致遠(廠商)可以略過。
Storybook(給工程師逐一檢查元件狀態的工具網站,在本機用 pnpm run heroui:storybook 開啟)目前只收錄 HeroUI 的元件,還沒有 <tc-tabs> 的頁面;這一段的範例和 API 表就是它的說明。
<tc-tabs> 是頁籤容器,內含多個 <tc-tab>,管理選取狀態、roving tabindex 與鍵盤瀏覽(方向鍵切換、Home / End 跳至首末)。下方為可互動的真實元件:
版面變體
章節連結:版面變體variant="mobile" 時頁籤等寬撐滿容器:
純 HTML
章節連結:純 HTML<link rel="stylesheet" href="@tzuchi/tokens/tokens.css" /><script type="module" src="@tzuchi/components/cdn"></script>
<tc-tabs value="overview"> <tc-tab value="overview">總覽</tc-tab> <tc-tab value="news">最新消息</tc-tab></tc-tabs>切換時會發出 tc-tab-change 事件(composed、bubbles),detail.value 為新選取的值:
document.querySelector('tc-tabs').addEventListener('tc-tab-change', (e) => { console.log(e.detail.value);});React
章節連結:Reactimport { TcTabs, TcTab } from '@tzuchi/react';
<TcTabs value="overview" onTcTabChange={(e) => setTab(e.detail.value)}> <TcTab value="overview">總覽</TcTab> <TcTab value="news">最新消息</TcTab></TcTabs>;API
章節連結:API下表自 Custom Elements Manifest 自動產生:
<tc-tabs>
章節連結:<tc-tabs>| Attribute | Type | Default | Description |
|---|---|---|---|
variant | 'web' | 'mobile' | 'web' | 版面變體:`web`(水平、桌機)或 `mobile`(等寬、行動)。 |
value | string | '' | 目前選取頁籤的 value。設定時會同步更新子頁籤的選取狀態。 |
<tc-tab>
章節連結:<tc-tab>| Attribute | Type | Default | Description |
|---|---|---|---|
value | string | '' | 頁籤值(必填),由 `<tc-tabs>` 用來判斷選取狀態。 |
disabled | boolean | false | 停用:以 `aria-disabled` 表示,仍可被鍵盤瀏覽(roving tabindex),但無法選取。 |
selected | boolean | false | 是否為目前選取的頁籤(由 `<tc-tabs>` 管理)。 |
無障礙(Accessibility)
章節連結:無障礙(Accessibility)<tc-tabs>為role="tablist",<tc-tab>為role="tab"。- 鍵盤瀏覽:方向鍵切換頁籤、Home / End 跳至首末,採 roving tabindex(僅選取項在 Tab 順序中)。
disabled以aria-disabled表示,仍可被方向鍵掠過但不會被選取(非pointer-events:none)。- 選取狀態以
aria-selected反映,選取頁籤顯示品牌主色底線指示。