下拉選單
用法
章節連結:用法下拉選單讓讀者從一串選項裡選一個,例如地區、場次。平常只佔一行,點開後才在下方列出所有選項,選好後選單自動收起,框裡顯示選到的那一項。適合選項比較多、版面放不下的時候;如果只有少少幾個選項、希望讀者一眼看到全部,請改用「單選鈕」。需要讀者自己打字的,請用「輸入框」。
組成
章節連結:組成| 部位 | 說明 |
|---|---|
| 選單框 | 有框線的一格,顯示提示文字或已選的選項,右邊有向下的箭頭。點開時框的底色變深、箭頭轉向上。 |
| 提示文字 | 還沒選的時候顯示的淡色文字,例如「請選擇地區」。選好後換成主色的選項名稱。 |
| 選項清單 | 點開後在選單框下方出現,底色是淡淡的品牌色;目前選到的那一項底色比較深。 |
| 焦點框 | 用鍵盤選到選單時出現的外框。用鍵盤的方向鍵就能上下選擇、按 Enter 選定、按 Esc 關閉。 |
| 停用狀態 | 整格變淡,點了不會展開。 |
該做與不該做
章節連結:該做與不該做| 類型 | 說明 |
|---|---|
| 建議 | 提示文字寫出要選什麼,例如「請選擇地區」「請選擇場次」。 |
| 建議 | 下拉選單本身沒有標題。放在表單裡時,請在它上方另外寫一行標題,並請工程把標題和選單連在一起,讓螢幕閱讀器也唸得到。 |
| 建議 | 選項依讀者好找的順序排列,例如依地理位置、時間先後;選項名稱短而清楚,一看就能分辨。 |
| 避免 | 不要放太多選項。清單會一路往下長、不會出現捲軸,選項太多時長長一串會超出畫面。 |
| 避免 | 只有兩、三個選項時不要用下拉選單;用「單選鈕」把選項直接列出來,讀者不用多點一次。 |
| 避免 | 不要用下拉選單當作網站的導覽選單(選了就換頁)。它是表單裡用來選一個值的元件。 |
在目前主題下的樣子
章節連結:在目前主題下的樣子目前顯示:DefaultGreen Natural(示意)。在頁首的「主題」可以切換。 查看所有主題
- 預設變體: 用元件本身的預設變體。
- 和預設主題不同的地方: 沒有。這就是預設主題,其他主題沒有特別指定的地方都沿用它。
- 預設變體: 主題不決定預設變體:用元件本身的預設變體(各網站自己的預設變體要等網站設定檔,還沒有實作)。
- 和預設主題不同的地方: (以下都是示意值)只有這個元件用到的顏色:主色、品牌底色(襯在內容後的品牌色塊)、品牌底色(滑鼠移上時)。其餘和預設主題一樣。 看完整的顏色對照
上方的大預覽會跟著頁首的「主題」和「色彩模式」一起變;這個元件還沒有淺色、深色並排的範例。
給工程師
章節連結:給工程師以下是給工程師的安裝與 API 說明,美編(設計)、網站的編輯和致遠(廠商)可以略過。
Storybook(給工程師逐一檢查元件狀態的工具網站,在本機用 pnpm run heroui:storybook 開啟)目前只收錄 HeroUI 的元件,還沒有 <tc-dropdown> 的頁面;這一段的範例和 API 表就是它的說明。
<tc-dropdown> 是單選的 outlined 下拉選單(combobox / listbox)。選項可由 options property(物件陣列)或 options 屬性(JSON 字串)提供,因此純 HTML 與 React 皆可使用。下方為可互動的真實元件:
純 HTML
章節連結:純 HTML選項以 JSON 字串放入 options 屬性:
<link rel="stylesheet" href="@tzuchi/tokens/tokens.css" /><script type="module" src="@tzuchi/components/cdn"></script>
<tc-dropdown name="region" placeholder="請選擇地區" options='[{"value":"tw","label":"台灣"},{"value":"jp","label":"日本"}]'></tc-dropdown>React
章節連結:React選項以物件陣列 property 傳入:
import { TcDropdown } from '@tzuchi/react';
<TcDropdown name="region" placeholder="請選擇地區" options={[ { value: 'tw', label: '台灣' }, { value: 'jp', label: '日本' }, ]} onTcChange={(e) => console.log(e.detail.value)}/>;事件
章節連結:事件tc-change:選取值改變時觸發,detail: { value }(composed、bubbles)。
鍵盤操作
章節連結:鍵盤操作Enter/空白鍵/↓:展開選單。↓/↑:在選單中移動作用中選項。Home/End:跳到第一個 / 最後一個選項。Enter:選取作用中選項。Esc:關閉選單並將焦點移回觸發按鈕。- 點選選單外或按
Esc皆會關閉選單。
表單
章節連結:表單<tc-dropdown> 透過 Form-Associated Custom Elements(ElementInternals)參與表單:name / value 會被序列化到 FormData。
API
章節連結:API下表自 Custom Elements Manifest 自動產生:
| Attribute | Type | Default | Description |
|---|---|---|---|
value | string | '' | 目前選取選項的 value(反映為屬性)。 |
placeholder | string | '' | 未選取時顯示的提示文字。 |
disabled | boolean | false | 停用:停用內部原生按鈕(非 pointer-events:none)。 |
open | boolean | false | 選單是否展開(反映為屬性)。 |
name | string | '' | 表單欄位名稱。 |
options | TcDropdownOption[] | [] | 選項清單。可由 property 設定物件陣列,或由 HTML/React 以 JSON 字串屬性提供。 |
無障礙(Accessibility)
章節連結:無障礙(Accessibility)- 觸發按鈕為原生
<button>,標註role=combobox、aria-haspopup=listbox、aria-expanded、aria-controls。 - 選單為
role=listbox,選項為role=option並以aria-selected標示目前選取項。 :focus-visible焦點環使用--tc-focus-ring-*token。disabled透過停用內部原生按鈕實作(非pointer-events:none)。