跳到內容
開始使用

頁籤

導覽 Tabs

總覽最新消息影音列表地圖我的

頁籤讓讀者在同一個地方切換幾組同一層級的內容,例如「總覽」「最新消息」,不用離開這一頁,一次只看一組。它有兩種版面:寬版(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" 時頁籤等寬撐滿容器:

列表地圖我的
<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);
});
import { TcTabs, TcTab } from '@tzuchi/react';
<TcTabs value="overview" onTcTabChange={(e) => setTab(e.detail.value)}>
<TcTab value="overview">總覽</TcTab>
<TcTab value="news">最新消息</TcTab>
</TcTabs>;

下表自 Custom Elements Manifest 自動產生:

Attribute Type Default Description
variant 'web' | 'mobile' 'web' 版面變體:`web`(水平、桌機)或 `mobile`(等寬、行動)。
value string '' 目前選取頁籤的 value。設定時會同步更新子頁籤的選取狀態。
Attribute Type Default Description
value string '' 頁籤值(必填),由 `<tc-tabs>` 用來判斷選取狀態。
disabled boolean false 停用:以 `aria-disabled` 表示,仍可被鍵盤瀏覽(roving tabindex),但無法選取。
selected boolean false 是否為目前選取的頁籤(由 `<tc-tabs>` 管理)。
  • <tc-tabs> 為 role="tablist",<tc-tab> 為 role="tab"。
  • 鍵盤瀏覽:方向鍵切換頁籤、Home / End 跳至首末,採 roving tabindex(僅選取項在 Tab 順序中)。
  • disabled 以 aria-disabled 表示,仍可被方向鍵掠過但不會被選取(非 pointer-events:none)。
  • 選取狀態以 aria-selected 反映,選取頁籤顯示品牌主色底線指示。