圖示按鈕
用法
章節連結:用法圖示按鈕是只有一個圖示、沒有文字的圓形按鈕,用在大家一看就懂的動作,例如返回、展開、搜尋、開啟選單,常放在導覽列、工具列這類空間很小的地方。淡底(tonal)是一般用法,實心(filled)用來強調;有 48px 和 64px 兩種大小。如果動作需要用文字才說得清楚,或是畫面上最重要的動作(例如送出、捐款),請改用有文字的「按鈕」。
組成
章節連結:組成| 部位 | 說明 |
|---|---|
| 圓形容器 | 按鈕的底色。淡底按鈕用淡淡的品牌底色,實心按鈕用主色;大小有 48px 和 64px 兩種。 |
| 圖示 | 必填。放在圓形中間的一個圖示,顏色跟著變體:淡底按鈕是主色圖示,實心按鈕的圖示用和主色對比清楚的顏色。 |
| 標籤 | 必填,但畫面上看不到。用一句話說出按下去會做什麼,例如「返回上一頁」;螢幕閱讀器會唸這段文字。 |
| 焦點框 | 用鍵盤選到按鈕時出現的外框,讓不用滑鼠的人知道目前在哪裡。 |
| 停用狀態 | 暫時不能按時整顆變淡。 |
該做與不該做
章節連結:該做與不該做| 類型 | 說明 |
|---|---|
| 建議 | 只用大家一看就懂的圖示,例如返回箭頭、放大鏡、三條線的選單。不確定讀者看不看得懂時,改用有文字的「按鈕」。 |
| 建議 | 每個圖示按鈕都要寫標籤,說出按下去會做什麼,例如「返回上一頁」「搜尋」。畫面上看不到,但螢幕閱讀器會唸出來。 |
| 建議 | 同一排的圖示按鈕用同一個大小;需要特別強調的那一個才用實心,其他用淡底。 |
| 避免 | 不要把畫面上最重要的動作(例如送出、立即捐款)只做成圖示按鈕;請用有文字的「按鈕」。 |
| 避免 | 不要在一個圖示按鈕裡放兩個圖示或加上文字。圓形裡只放得下一個圖示,需要文字時請用「按鈕」。 |
在目前主題下的樣子
章節連結:在目前主題下的樣子目前顯示:DefaultGreen Natural(示意)。在頁首的「主題」可以切換。 查看所有主題
- 預設變體: 用元件本身的預設變體。
- 和預設主題不同的地方: 沒有。這就是預設主題,其他主題沒有特別指定的地方都沿用它。
- 預設變體: 主題不決定預設變體:用元件本身的預設變體(各網站自己的預設變體要等網站設定檔,還沒有實作)。
- 和預設主題不同的地方: (以下都是示意值)只有這個元件用到的顏色:主色、主色(滑鼠移上時;連結文字也用它)、品牌底色(襯在內容後的品牌色塊)、品牌底色(滑鼠移上時)、主色上的文字、焦點框(用鍵盤選到時的外框)。其餘和預設主題一樣。 看完整的顏色對照
上方的大預覽會跟著頁首的「主題」和「色彩模式」一起變;這個元件還沒有淺色、深色並排的範例。
給工程師
章節連結:給工程師以下是給工程師的安裝與 API 說明,美編(設計)、網站的編輯和致遠(廠商)可以略過。
Storybook(給工程師逐一檢查元件狀態的工具網站,在本機用 pnpm run heroui:storybook 開啟)目前只收錄 HeroUI 的元件,還沒有 <tc-icon-button> 的頁面;這一段的範例和 API 表就是它的說明。
<tc-icon-button> 是以圓形容器包裹單一圖示的按鈕,提供 tonal / filled 兩種變體與 md(48px)/ lg(64px)兩種尺寸。label 為必填,會套用至內部 <button> 的 aria-label。下方為可互動的真實元件:
純 HTML
章節連結:純 HTML<link rel="stylesheet" href="@tzuchi/tokens/tokens.css" /><script type="module" src="@tzuchi/components/cdn"></script>
<tc-icon-button variant="tonal" label="返回"> <tc-icon name="arrow-left"></tc-icon></tc-icon-button>React
章節連結:Reactimport { TcIconButton } from '@tzuchi/react';
<TcIconButton variant="filled" size="lg" label="向下展開" onClick={handleExpand}> <TcIcon name="arrow-down" /></TcIconButton>;變體與尺寸
章節連結:變體與尺寸variant="tonal"(預設):品牌淺色底 + 品牌主色圖示。variant="filled":品牌主色底 + 對比文字色圖示。size="md"(預設,48px)/size="lg"(64px),對應--tc-size-control-*。
API
章節連結:API下表自 Custom Elements Manifest 自動產生:
| Attribute | Type | Default | Description |
|---|---|---|---|
variant | 'tonal' | 'filled' | 'tonal' | |
size | 'md' | 'lg' | 'md' | |
disabled | boolean | false | |
label | string | '' | 無障礙標籤,套用至內部 <button> 的 aria-label(必填)。 |
無障礙(Accessibility)
章節連結:無障礙(Accessibility)label為必填,會套用至內部原生<button>的aria-label,供螢幕報讀器辨識。- 內含原生
<button>,支援鍵盤 Enter / Space。 :focus-visible焦點環使用--tc-focus-ring-*token。disabled透過停用內部的原生控制項實作(非pointer-events:none)。