跳到內容
開始使用

輸入框

表單 Input

輸入框讓讀者輸入一行文字,例如姓名、電話、電子郵件。框的上方是標題,說明要填什麼;下方可以放一行說明,填錯時改顯示錯誤訊息。如果讀者是要搜尋網站的內容,請改用「搜尋列」;如果答案只有幾個固定的選項,請改用「下拉選單」或「單選鈕」,讀者不用自己打字,也不會打錯。

部位說明
標題框上方的文字,說明要填什麼。必填的欄位會在標題後面加一個紅色星號。
輸入框有框線的區域,讀者在這裡打字。滑鼠移上去或選到時框線變色;選到時外面還多一圈柔光。
提示文字可省略。框內的淡色文字,例如「請輸入姓名」;讀者一開始打字就消失。
前後附加內容可省略。放在框內前面或後面的小圖示或單位,例如「元」。
說明文字可省略。框下方的一行淡色文字,補充怎麼填。
錯誤訊息填錯時取代說明文字,以紅色顯示,框線也變成紅色。
停用、唯讀狀態停用時整個框變淡、不能輸入;唯讀時看起來和平常一樣,但內容不能修改。
類型 說明
建議 每個輸入框都寫標題,例如「電子郵件」。不要只靠框內的提示文字:讀者一開始打字,提示就不見了。
建議 錯誤訊息寫出怎麼改,例如「請輸入完整的電子郵件,例如 name@example.com」,不要只寫「格式錯誤」。錯誤不能只靠紅色表示,文字要說得清楚。
建議 必填的欄位標題後面會出現紅色星號;在表單開頭寫一次「標示 * 的欄位必填」,讓讀者知道星號的意思。
建議 框的寬度配合要填的內容:電話、郵遞區號可以短一點,地址、電子郵件長一點。
避免 只給讀者看、不能修改的資料不要用停用的輸入框;停用的框顏色很淡,不容易看清楚。請用唯讀,或直接寫成一般文字。

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

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

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

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

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

<tc-input> 是 form-associated 的文字輸入欄位,內含原生 <input>,支援 label、helper-text、error-text 與表單驗證。下方為可互動的真實元件:

<link rel="stylesheet" href="@tzuchi/tokens/tokens.css" />
<script type="module" src="@tzuchi/components/cdn"></script>
<tc-input name="keyword" label="關鍵字" placeholder="請輸入關鍵字"></tc-input>
import { TcInput } from '@tzuchi/react';
<TcInput
name="keyword"
label="關鍵字"
placeholder="請輸入關鍵字"
onTcInput={(e) => console.log(e.detail.value)}
/>;
  • tc-input:每次鍵入時觸發,detail: { value }。
  • tc-change:內部 <input> change 時觸發,detail: { value }。

<tc-input> 透過 Form-Associated Custom Elements(ElementInternals)參與表單:name / value 會被序列化到 FormData,required、invalid 會回報驗證狀態。

搜尋

下表自 Custom Elements Manifest 自動產生:

Attribute Type Default Description
value string ''
placeholder string ''
type 'text' | 'email' | 'password' | 'number' | 'search' | 'tel' 'text'
name string ''
disabled boolean false
readonly boolean false
required boolean false
invalid boolean false
label string ''
helper-text string ''
error-text string ''
  • 內含原生 <input>,label 透過 for / id 與輸入框關聯。
  • delegatesFocus 讓點擊 label 自動聚焦輸入框。
  • helper-text / error-text 透過 aria-describedby 關聯;invalid 時設定 aria-invalid="true"。
  • disabled 透過停用內部的原生控制項實作(非 pointer-events:none)。