TextField文字欄位

文字欄位元件讓使用者能在頁面中輸入文字，通常用於表單和對話框。

使用方法

按需引入元件：

import 'mdui/components/text-field.js';

按需引入元件的 TypeScript 型別：

import type { TextField } from 'mdui/components/text-field.js';

使用範例：

<mdui-text-field label="Text Field"></mdui-text-field>

範例

樣式

透過 variant 屬性設定文字欄位的樣式。

<mdui-text-field variant="filled" label="Text Field"></mdui-text-field>

<br/><br/>

<mdui-text-field variant="outlined" label="Text Field"></mdui-text-field>

原始碼

輔助文字

透過 label 屬性設定文字欄位上方的標籤文字。

<mdui-text-field label="Text Field"></mdui-text-field>

原始碼

透過 placeholder 屬性設定無值時的佔位文字。

<mdui-text-field label="Text Field" placeholder="Placeholder"></mdui-text-field>

原始碼

透過 helper 屬性設定文字欄位底部的輔助文字。你也可以使用 helper slot 來設定輔助文字。加上 helper-on-focus 屬性則僅在輸入框聚焦時顯示輔助文字。

Supporting text

<mdui-text-field label="Text Field" helper="Supporting text"></mdui-text-field>

<mdui-text-field label="Text Field">
  <span slot="helper" style="color: blue">Supporting text</span>
</mdui-text-field>

<mdui-text-field label="Text Field" helper="Supporting text" helper-on-focus></mdui-text-field>

原始碼

可清空

加上 clearable 屬性後，當文字欄位有值時，會在右側加上清空按鈕。

<mdui-text-field clearable label="Text Field" value="Input Text"></mdui-text-field>

原始碼

文字靠右對齊

加上 end-aligned 屬性可以使文字靠右對齊。

<mdui-text-field end-aligned label="Text Field" value="Input Text"></mdui-text-field>

原始碼

前後文字及圖示

透過設定 icon 和 end-icon 屬性，即可在文字欄位的左側和右側加入 Material Icons 圖示。也可以透過 icon 和 end-icon slot 在文字欄位的左側和右側加入元素。

<mdui-text-field icon="search" end-icon="mic" label="Text Field"></mdui-text-field>

<br/><br/>

<mdui-text-field label="Text Field">
  <mdui-button-icon slot="icon" icon="search"></mdui-button-icon>
  <mdui-button-icon slot="end-icon" icon="mic"></mdui-button-icon>
</mdui-text-field>

原始碼

透過設定 prefix 和 suffix 屬性，可以在文字欄位的左側和右側加入文字。也可以透過 prefix 和 suffix slot 在文字欄位的左側和右側加入文字元素。這些文字只有在文字欄位聚焦或有值時才會顯示。

$ /100

<mdui-text-field prefix="$" suffix="/100" label="Text Field"></mdui-text-field>

<br/><br/>

<mdui-text-field label="Text Field">
  <span slot="prefix" style="color: blue">$</span>
  <span slot="suffix" style="color: blue">/100</span>
</mdui-text-field>

原始碼

唯讀模式

加上 readonly 屬性，可以將文字欄位設定為唯讀模式。

<mdui-text-field readonly label="Text Field" value="Input Text"></mdui-text-field>

原始碼

停用狀態

加上 disabled 屬性即可停用文字欄位。

<mdui-text-field disabled label="Text Field" value="Input Text"></mdui-text-field>

原始碼

多行文字欄位

透過 rows 屬性，可以設定多行文字欄位的行數。

<mdui-text-field rows="3" label="Text Field"></mdui-text-field>

原始碼

也可以加上 autosize 屬性，使文字欄位能根據輸入內容的長度自動調整高度。透過 min-rows 和 max-rows 屬性，可以指定自動調整高度時的最小行數和最大行數。

<mdui-text-field autosize label="Text Field"></mdui-text-field>

<br/><br/>

<mdui-text-field autosize min-rows="2" max-rows="5" label="Text Field"></mdui-text-field>

原始碼

字數統計

當透過 maxlength 屬性設定了最大字數時，可以加上 counter 屬性在文字欄位下方顯示字數統計。

<mdui-text-field maxlength="20" counter label="Text Field"></mdui-text-field>

原始碼

密碼欄位

當 type="password" 時，加上 toggle-password 屬性可以在文字欄位右側加入切換密碼可見性的按鈕。

<mdui-text-field type="password" toggle-password label="Text Field"></mdui-text-field>

原始碼

API

屬性

HTML 屬性	JavaScript 屬性	型別	預設值
`variant`	`variant`	`'filled' \| 'outlined'`	`'filled'`
文字欄位的形狀。預設為 `filled`。可選值包括： `filled`：帶背景色的文字欄位，視覺效果較強 `outlined`：帶邊框的文字欄位，視覺效果較弱
`type`	`type`	`'text' \| 'number' \| 'password' \| 'url' \| 'email' \| 'search' \| 'tel' \| 'hidden' \| 'date' \| 'datetime-local' \| 'month' \| 'time' \| 'week'`	`'text'`
文字欄位輸入類型。預設為 `text`。可選值包括： `text`：預設值。文字欄位 `number`：只能輸入數字。支援虛擬鍵盤的裝置上會顯示數字鍵盤 `password`：用於輸入密碼，其值會被遮蓋 `url`：用於輸入 URL，會驗證 URL 格式。在支援虛擬鍵盤的裝置上有相應的鍵盤 `email`：用於輸入郵件地址，會驗證郵件格式。在支援虛擬鍵盤的裝置上有相應的鍵盤 `search`：用於搜尋框。支援虛擬鍵盤的裝置上的 Enter 圖示會變成搜尋圖示 `tel`：用於輸入電話號碼。支援虛擬鍵盤的裝置上會顯示電話數字鍵盤 `hidden`：隱藏該控制項，但其值仍會送出到伺服器 `date`：輸入日期的控制項（年、月、日，不包括時間）。在支援的瀏覽器啟用時開啟日期選擇器或年月日的數字滾輪 `datetime-local`：輸入日期和時間的控制項，不包括時區。在支援的瀏覽器啟用時開啟日期選擇器或年月日的數字滾輪 `month`：輸入年和月的控制項，沒有時區 `time`：用於輸入時間的控制項，不包括時區 `week`：用於輸入以年和週數組成的日期，不帶時區
`name`	`name`	`string`	`''`
文字欄位名稱，將與表單資料一起送出
`value`	`value`	`string`	`''`
文字欄位的值，將與表單資料一起送出
	`defaultValue`	`string`	`''`
預設值。在重設表單時，將重設為該預設值。該屬性只能透過 JavaScript 屬性設定
`label`	`label`	`string`	-
標籤文字
`placeholder`	`placeholder`	`string`	-
佔位符文字
`helper`	`helper`	`string`	-
文字欄位底部的說明文字。也可以透過 `slot="helper"` 設定
`helper-on-focus`	`helperOnFocus`	`boolean`	`false`
是否僅在取得焦點時，顯示底部的說明文字
`clearable`	`clearable`	`boolean`	`false`
是否可清空文字欄位內容
`clear-icon`	`clearIcon`	`string`	-
可清空文字欄位時，顯示在文字欄位右側的清空按鈕的 Material Icons 圖示名。也可以透過 `slot="clear-icon"` 設定
`end-aligned`	`endAligned`	`boolean`	`false`
是否將文字右對齊
`prefix`	`prefix`	`string`	-
文字欄位的前綴文字。只在文字欄位聚焦或有值時顯示。也可以透過 `slot="prefix"` 設定
`suffix`	`suffix`	`string`	-
文字欄位的後綴文字。只在文字欄位聚焦或有值時顯示。也可以透過 `slot="suffix"` 設定
`icon`	`icon`	`string`	-
文字欄位的前綴圖示的 Material Icons 圖示名。也可以透過 `slot="icon"` 設定
`end-icon`	`endIcon`	`string`	-
文字欄位的後綴圖示的 Material Icons 圖示名。也可以透過 `slot="end-icon"` 設定
`error-icon`	`errorIcon`	`string`	-
表單欄位驗證失敗時，顯示在文字欄位右側的 Material Icons 圖示名。也可以透過 `slot="error-icon"` 設定
`form`	`form`	`string`	-
關聯的 `<form>` 元素。此屬性值應為同一頁面中的一個 `<form>` 元素的 `id`。若未指定此屬性，則該元素必須是 `<form>` 元素的子元素。透過此屬性，你可以將元素放置在頁面的任何位置，而不僅僅是 `<form>` 元素的子元素。
`readonly`	`readonly`	`boolean`	`false`
是否為唯讀模式
`disabled`	`disabled`	`boolean`	`false`
是否停用輸入框
`required`	`required`	`boolean`	`false`
送出表單時，是否必須填寫該欄位
`rows`	`rows`	`number`	-
文字欄位的固定顯示行數
`autosize`	`autosize`	`boolean`	`false`
是否根據輸入內容自動調整文字欄位高度
`min-rows`	`minRows`	`number`	-
`autosize` 為 `true` 時，文字欄位的最小行數
`max-rows`	`maxRows`	`number`	-
`autosize` 為 `true` 時，文字欄位的最大行數
`minlength`	`minlength`	`number`	-
允許輸入的最小字元數
`maxlength`	`maxlength`	`number`	-
允許輸入的最大字元數
`counter`	`counter`	`boolean`	`false`
是否顯示字數統計，只在 `maxlength` 被指定時有效
`min`	`min`	`number`	-
當 `type` 為 `number` 時，允許輸入的最小數值
`max`	`max`	`number`	-
當 `type` 為 `number` 時，允許輸入的最大數值
`step`	`step`	`number`	-
`type` 為 `number` 時，數值增減的步長
`pattern`	`pattern`	`string`	-
用於表單驗證的正規表示式
`toggle-password`	`togglePassword`	`boolean`	`false`
`type` 為 `password` 時，設定此屬性會新增一個切換按鈕，用於在明文和密文之間切換
`show-password-icon`	`showPasswordIcon`	`string`	-
密碼切換按鈕的 Material Icons 圖示，當密碼為明文時顯示。也可以透過 `slot="show-password-icon"` 設定
`hide-password-icon`	`hidePasswordIcon`	`string`	-
密碼切換按鈕的 Material Icons 圖示，當密碼為密文時顯示。也可以透過 `slot="hide-password-icon"` 設定
`autocapitalize`	`autocapitalize`	`'none' \| 'sentences' \| 'words' \| 'characters'`	-
iOS 的非標準屬性，用於控制文字首字母是否自動大寫。在 iOS5 及以後的版本上有效。可選值包括： `none`：停用首字母大寫 `sentences`：句子首字母大寫 `words`：單字首字母大寫 `characters`：所有字母大寫
`autocorrect`	`autocorrect`	`string`	-
`input` 元素的 `autocorrect` 屬性
`autocomplete`	`autocomplete`	`string`	-
`input` 元素的 `autocomplete` 屬性
`enterkeyhint`	`enterkeyhint`	`'enter' \| 'done' \| 'go' \| 'next' \| 'previous' \| 'search' \| 'send'`	-
`input` 元素的 `enterkeyhint` 屬性，用於客製化虛擬鍵盤上的 Enter 鍵的顯示文字或圖示。具體顯示效果取決於使用者使用的裝置和語言。可選值包括： `enter`：插入新行 `done`：完成輸入，關閉虛擬鍵盤 `go`：前往輸入文字的目標 `next`：移動到下一個輸入項 `previous`：移動到上一個輸入項 `search`：前往搜尋結果 `send`：傳送文字資訊
`spellcheck`	`spellcheck`	`boolean`	`false`
是否啟用拼字檢查
`inputmode`	`inputmode`	`'none' \| 'text' \| 'decimal' \| 'numeric' \| 'tel' \| 'search' \| 'email' \| 'url'`	-
`input` 元素的 `inputmode` 屬性，用於客製化虛擬鍵盤的類型。可選值包括： `none`：無虛擬鍵盤。在需要實作自己的鍵盤輸入控制項時很有用 `text`：標準文字輸入鍵盤 `decimal`：小數輸入鍵盤，除了數字之外可能會有小數點 `.` 或者千分符逗號 `,` `numeric`：顯示 0-9 的數字鍵盤 `tel`：手機數字鍵盤，包含 0-9 數字、星號 `*` 或者井號 `#` 鍵 `search`：為搜尋輸入最佳化的虛擬鍵盤，送出按鈕通常會顯示 `search` 或者「搜尋」 `email`：為郵件地址輸入最佳化的虛擬鍵盤，通常會有 `@ .` 等鍵 `url`：為 URL 輸入最佳化的虛擬鍵盤，通常會有 `. / #` 等鍵
	`validity`	`ValidityState`	-
表單驗證狀態物件，具體參見 `ValidityState`
	`validationMessage`	`string`	-
如果表單驗證未通過，此屬性將包含提示資訊。如果驗證通過，此屬性將為空字串
	`valueAsNumber`	`number`	-
取得目前值，並轉換為 `number` 類型；或設定一個 `number` 類型的值。如果值無法被轉換為 `number` 類型，則會回傳 `NaN`。
`autofocus`	`autofocus`	`boolean`	`false`
是否在頁面載入完成後自動取得焦點
`tabindex`	`tabIndex`	`number`	-
元素在使用 Tab 鍵切換焦點時的順序

方法

名稱	參數	回傳值
`select`		`void`
選取文字欄位中的文字
`setSelectionRange`	`start: number` `end: number` `direction: 'forward' \| 'backward' \| 'none'`	`void`
選取文字欄位中特定範圍的內容
`setRangeText`	`replacement: string` `start: number` `end: number` `selectMode: 'select' \| 'start' \| 'end' \| 'preserve'`	`void`
將文字欄位中特定範圍的文字替換為新的文字
`checkValidity`		`boolean`
檢查表單欄位是否通過驗證。如果未通過，回傳 `false` 並觸發 `invalid` 事件；如果通過，回傳 `true`
`reportValidity`		`boolean`
檢查表單欄位是否通過驗證。如果未通過，回傳 `false` 並觸發 `invalid` 事件；如果通過，回傳 `true`。如果驗證未通過，還會在元件上顯示驗證失敗的提示。
`setCustomValidity`	`message: string`	`void`
設定自訂的錯誤提示文字。只要這個文字不為空，就表示欄位未通過驗證
`click`		`void`
模擬滑鼠點擊元素
`focus`	`options: FocusOptions` (選配)	`void`
將焦點設定到目前元素。可以傳入一個物件作為引數，該物件的屬性包括： `preventScroll`：預設情況下，元素取得焦點後，頁面會捲動以將該元素捲動到檢視中。如果不希望頁面捲動，可以將此屬性設定為 `true`。
`blur`		`void`
移除目前元素的焦點

事件

名稱
`focus`
取得焦點時觸發
`blur`
失去焦點時觸發
`change`
在文字欄位的值變更，且失去焦點時觸發
`input`
在文字欄位的值變更時觸發
`invalid`
表單欄位驗證不通過時觸發
`clear`
在點擊由 `clearable` 屬性產生的清空按鈕時觸發。可以透過呼叫 `event.preventDefault()` 阻止清空文字欄位

Slots

名稱
`icon`
左側圖示
`end-icon`
右側圖示
`error-icon`
驗證失敗狀態的右側圖示
`prefix`
左側文字
`suffix`
右側文字
`clear-button`
清空按鈕
`clear-icon`
清空按鈕中的圖示
`toggle-password-button`
密碼顯示狀態切換按鈕
`show-password-icon`
顯示密碼狀態下，密碼顯示狀態切換按鈕中的圖示
`hide-password-icon`
隱藏密碼狀態下，密碼顯示狀態切換按鈕中的圖示
`helper`
底部的說明文字

CSS Parts

名稱
`container`
文字欄位容器
`icon`
左側圖示
`end-icon`
右側圖示
`error-icon`
驗證失敗狀態的右側圖示
`prefix`
左側文字
`suffix`
右側文字
`label`
上方的標籤文字
`input`
內部的 `<input>` 或 `<textarea>` 元素
`clear-button`
清空按鈕
`clear-icon`
清空按鈕中的圖示
`toggle-password-button`
密碼顯示狀態切換按鈕
`show-password-icon`
顯示密碼狀態下，密碼顯示狀態切換按鈕中的圖示
`hide-password-icon`
隱藏密碼狀態下，密碼顯示狀態切換按鈕中的圖示
`supporting`
底部輔助資訊容器，包括 helper、error、counter
`helper`
底部的說明文字
`error`
底部的錯誤描述文字
`counter`
底部右側的字數統計

Tabs 分頁

Tooltip 工具提示