跳到內容
開始使用

下拉選單

表單 Dropdown

下拉選單讓讀者從一串選項裡選一個,例如地區、場次。平常只佔一行,點開後才在下方列出所有選項,選好後選單自動收起,框裡顯示選到的那一項。適合選項比較多、版面放不下的時候;如果只有少少幾個選項、希望讀者一眼看到全部,請改用「單選鈕」。需要讀者自己打字的,請用「輸入框」。

部位說明
選單框有框線的一格,顯示提示文字或已選的選項,右邊有向下的箭頭。點開時框的底色變深、箭頭轉向上。
提示文字還沒選的時候顯示的淡色文字,例如「請選擇地區」。選好後換成主色的選項名稱。
選項清單點開後在選單框下方出現,底色是淡淡的品牌色;目前選到的那一項底色比較深。
焦點框用鍵盤選到選單時出現的外框。用鍵盤的方向鍵就能上下選擇、按 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 皆可使用。下方為可互動的真實元件:

選項以 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>

選項以物件陣列 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。

下表自 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 字串屬性提供。
  • 觸發按鈕為原生 <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)。