輸入框
用法
章節連結:用法輸入框讓讀者輸入一行文字,例如姓名、電話、電子郵件。框的上方是標題,說明要填什麼;下方可以放一行說明,填錯時改顯示錯誤訊息。如果讀者是要搜尋網站的內容,請改用「搜尋列」;如果答案只有幾個固定的選項,請改用「下拉選單」或「單選鈕」,讀者不用自己打字,也不會打錯。
組成
章節連結:組成| 部位 | 說明 |
|---|---|
| 標題 | 框上方的文字,說明要填什麼。必填的欄位會在標題後面加一個紅色星號。 |
| 輸入框 | 有框線的區域,讀者在這裡打字。滑鼠移上去或選到時框線變色;選到時外面還多一圈柔光。 |
| 提示文字 | 可省略。框內的淡色文字,例如「請輸入姓名」;讀者一開始打字就消失。 |
| 前後附加內容 | 可省略。放在框內前面或後面的小圖示或單位,例如「元」。 |
| 說明文字 | 可省略。框下方的一行淡色文字,補充怎麼填。 |
| 錯誤訊息 | 填錯時取代說明文字,以紅色顯示,框線也變成紅色。 |
| 停用、唯讀狀態 | 停用時整個框變淡、不能輸入;唯讀時看起來和平常一樣,但內容不能修改。 |
該做與不該做
章節連結:該做與不該做| 類型 | 說明 |
|---|---|
| 建議 | 每個輸入框都寫標題,例如「電子郵件」。不要只靠框內的提示文字:讀者一開始打字,提示就不見了。 |
| 建議 | 錯誤訊息寫出怎麼改,例如「請輸入完整的電子郵件,例如 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 與表單驗證。下方為可互動的真實元件:
純 HTML
章節連結:純 HTML<link rel="stylesheet" href="@tzuchi/tokens/tokens.css" /><script type="module" src="@tzuchi/components/cdn"></script>
<tc-input name="keyword" label="關鍵字" placeholder="請輸入關鍵字"></tc-input>React
章節連結:Reactimport { 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 會回報驗證狀態。
API
章節連結:API下表自 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 | '' |
無障礙(Accessibility)
章節連結:無障礙(Accessibility)- 內含原生
<input>,label透過for/id與輸入框關聯。 delegatesFocus讓點擊label自動聚焦輸入框。helper-text/error-text透過aria-describedby關聯;invalid時設定aria-invalid="true"。disabled透過停用內部的原生控制項實作(非pointer-events:none)。