圖示
用法
章節連結:用法圖示是搭配文字使用的小圖形,例如搜尋框前面的放大鏡、日期旁邊的月曆,讓讀者更快認出這是什麼。目前有 11 個內建圖示,三種大小,顏色會跟著旁邊的文字。圖示本身不能按;要讓讀者按下去做事,請用「圖示按鈕」或在「按鈕」裡放圖示。
組成
章節連結:組成| 部位 | 說明 |
|---|---|
| 圖形 | 從 11 個內建圖示選一個:搜尋、關閉、選單、加號、打勾、上下左右箭頭、月曆、信件。 |
| 大小 | 小 sm、中 md(預設)、大 lg 三種;和一般文字並排時通常用小的。 |
| 顏色 | 沒有自己的顏色,跟著它所在位置的文字顏色,所以會隨主題和色彩模式一起變。 |
| 替代文字 | 可省略。沒有寫時,圖示只是裝飾,螢幕閱讀器會略過;寫了,螢幕閱讀器會唸出這段文字。 |
該做與不該做
章節連結:該做與不該做| 類型 | 說明 |
|---|---|
| 建議 | 圖示旁邊盡量配上文字,例如放大鏡加「搜尋」,不是每個讀者都認得每個圖形。 |
| 建議 | 圖示單獨出現、又帶著意思時(例如只用一個信件圖示代表「聯絡我們」),請寫替代文字。旁邊已經有同樣意思的文字時,就不用寫。 |
| 建議 | 同一排或同一組的圖示用同一種大小。 |
| 避免 | 不要只靠圖示的顏色表達意思(例如只用紅色表示錯誤);請同時用文字說明。 |
| 避免 | 不要把圖示當成按鈕:它不能用鍵盤選到。要讓讀者按,請用「圖示按鈕」。 |
| 避免 | 不要自己找外部網站的圖示放進來;需要新的圖示,請美編(設計)和工程一起加進內建圖示。 |
在目前主題下的樣子
章節連結:在目前主題下的樣子目前顯示:DefaultGreen Natural(示意)。在頁首的「主題」可以切換。 查看所有主題
- 預設變體: 用元件本身的預設變體。
- 和預設主題不同的地方: 沒有。這就是預設主題,其他主題沒有特別指定的地方都沿用它。
- 預設變體: 主題不決定預設變體:用元件本身的預設變體(各網站自己的預設變體要等網站設定檔,還沒有實作)。
- 和預設主題不同的地方: 沒有。這個元件本身沒有顏色,主題不會改變它。
圖示的形狀和大小目前所有主題都一樣,顏色跟著文字;上方預覽會跟著頁首的「主題」和「色彩模式」一起變。
給工程師
章節連結:給工程師以下是給工程師的安裝與 API 說明,美編(設計)、網站的編輯和致遠(廠商)可以略過。
Storybook(給工程師逐一檢查元件狀態的工具網站,在本機用 pnpm run heroui:storybook 開啟)目前只收錄 HeroUI 的元件,還沒有 <tc-icon> 的頁面;這一段的範例和 API 表就是它的說明。
<tc-icon> 從內建圖示登錄表渲染內嵌 SVG,依 size 對應 --tc-size-icon-* token,並以 currentColor 繼承周圍文字色。下方為可互動的真實元件:
尺寸
章節連結:尺寸size 提供 sm(20px)、md(32px,預設)、lg(40px):
顏色
章節連結:顏色圖示以 currentColor 繪製,因此繼承父層的文字色:
純 HTML
章節連結:純 HTML<link rel="stylesheet" href="@tzuchi/tokens/tokens.css" /><script type="module" src="@tzuchi/components/cdn"></script>
<!-- 裝飾性圖示(對輔助技術隱藏) --><tc-icon name="search"></tc-icon>
<!-- 具語意的圖示(提供 label 後 role=img + aria-label) --><tc-icon name="mail" label="收件匣"></tc-icon>React
章節連結:Reactimport { TcIcon } from '@tzuchi/react';
<TcIcon name="search" size="md" />;可用圖示
章節連結:可用圖示search、close、menu、plus、check、chevron-down、chevron-up、chevron-left、chevron-right、calendar、mail。
API
章節連結:API下表自 Custom Elements Manifest 自動產生:
| Attribute | Type | Default | Description |
|---|---|---|---|
name | TcIconName | '' | '' | Registry key of the icon to render. |
size | 'sm' | 'md' | 'lg' | 'md' | Visual size; maps to the `--tc-size-icon-*` tokens. |
label | string | '' | Accessible name. When set, the icon is exposed as `role="img"` with this label; otherwise it is decorative and hidden from assistive tech. |
無障礙(Accessibility)
章節連結:無障礙(Accessibility)- 未設定
label時,圖示視為裝飾性,套用aria-hidden="true",不會被螢幕報讀。 - 設定
label後,內部<svg>取得role="img"與aria-label,並含<title>。 focusable="false"避免 IE/舊版瀏覽器將 SVG 加入 Tab 順序。