跳到內容
開始使用

單選鈕

表單 Radio

捐款方式每月定期捐款單次捐款先了解,之後再決定每年捐款(尚未開放)

單選鈕讓讀者在幾個互斥的選項中選一個,例如捐款方式、衣服尺寸。所有選項同時列出來,讀者一眼就能比較;選了其中一個,原本選的就自動取消。選項很多、版面放不下時,請改用「下拉選單」;如果讀者可以同時選好幾個,就不要用單選鈕。

部位說明
圓鈕24px 的圓圈。沒選時是灰色外圈,選到時外圈變成主色,中間多一個主色的圓點。
選項文字必填。寫在圓鈕右邊;點文字也能選這個選項。
焦點框用鍵盤選到時出現的外框。用方向鍵可以在同一組選項之間移動並選取。
停用狀態整個選項變淡,不能選,也不能用鍵盤選到。

這個元件只有一個一個的選項,沒有整組的標題;整組上方的問題(例如「捐款方式」)要在網頁上另外寫。

類型 說明
建議 每組單選鈕上方寫一個問題或標題,例如「捐款方式」,讓讀者知道在選什麼。
建議 選項一個一行、由上往下排,比橫排容易看,也容易點。
建議 選項文字一句話說清楚,例如「每月定期捐款」;需要補充說明時,寫在整組的下方。
避免 不要只放一個單選鈕。單選鈕選了之後就不能再取消,讀者會沒辦法改回來。
避免 讀者可以同時選好幾個時,不要用單選鈕。

目前顯示:DefaultGreen Natural(示意)。在頁首的「主題」可以切換。 查看所有主題

  • 預設變體: 用元件本身的預設變體。
  • 和預設主題不同的地方: 沒有。這就是預設主題,其他主題沒有特別指定的地方都沿用它。
  • 預設變體: 主題不決定預設變體:用元件本身的預設變體(各網站自己的預設變體要等網站設定檔,還沒有實作)。
  • 和預設主題不同的地方: (以下都是示意值)只有這個元件用到的顏色:主色。其餘和預設主題一樣。 看完整的顏色對照

上方的大預覽會跟著頁首的「主題」和「色彩模式」一起變;這個元件還沒有淺色、深色並排的範例。

以下是給工程師的安裝與 API 說明,美編(設計)、網站的編輯和致遠(廠商)可以略過。

Storybook(給工程師逐一檢查元件狀態的工具網站,在本機用 pnpm run heroui:storybook 開啟)目前只收錄 HeroUI 的元件,還沒有 <tc-radio> 的頁面;這一段的範例和 API 表就是它的說明。

<tc-radio> 是 24×24 的單選圓鈕,提供外圈 ring 與選取時填滿的內點,並支援 form-associated 表單送出。同 name 的 <tc-radio> 互斥,僅能選取一個。下方為可互動的真實元件:

選項一選項二選項三停用選項
<link rel="stylesheet" href="@tzuchi/tokens/tokens.css" />
<script type="module" src="@tzuchi/components/cdn"></script>
<tc-radio name="color" value="red">紅</tc-radio>
<tc-radio name="color" value="blue">藍</tc-radio>
import { TcRadio } from '@tzuchi/react';
<TcRadio name="color" value="red" onTcChange={handleChange}>紅</TcRadio>;

同名的 <tc-radio> 互斥,選取後其它選項自動取消。tc-radio 透過 Form-Associated Custom Elements(ElementInternals)以 name / value 參與所屬 <form> 送出;未選取時不貢獻任何值。加上 required 時,群組未選取即為無效。

小中大

下表自 Custom Elements Manifest 自動產生:

Attribute Type Default Description
checked boolean false 是否選取(反映為屬性)。
value string '' 表單值,選取時提交。
name string '' 群組名稱(反映為屬性)。同名的 `<tc-radio>` 互斥。
disabled boolean false 停用(反映為屬性):無法選取且不可聚焦。
required boolean false 必填:群組內無任何選取時無效。
  • role="radio" 並同步 aria-checked / aria-disabled。
  • 鍵盤 Space / Enter 選取;方向鍵在同名群組內移動並選取。
  • Roving tabindex:群組內僅選取項(或第一個可用項)進入 Tab 順序。
  • 焦點環使用 --tc-focus-ring-* token。
  • disabled 透過停用內部的原生控制項實作(非 pointer-events:none),且不可聚焦。