TextFieldAPI

React TextField 元件的 API 參考文件。瞭解此匯出模組的 props、CSS 和其他 API。

示範

如需此 React 元件的使用範例和詳細資訊，請造訪元件示範頁面

匯入

import TextField from '@mui/material/TextField';
// or
import { TextField } from '@mui/material';

閱讀關於最小化套件大小的指南，以瞭解差異。

TextField 是最常見情況 (80%) 的便利包裝函式。它不可能滿足所有人的需求，否則 API 將會失控增長。

進階設定

重要的是要瞭解文字欄位是以下元件之上的簡單抽象概念

如果您希望變更套用至 input 元素的 props，您可以按照以下方式操作

const inputProps = {
  step: 300,
};

return <TextField id="time" type="time" inputProps={inputProps} />;

對於進階情況，請點擊上方「編輯此頁面」按鈕查看 TextField 的原始碼。請考慮以下任一方式

使用大寫 props 將值直接傳遞至元件
直接使用示範中顯示的底層元件

Props

FormControl 元件的 Props 也可使用。

名稱	類型	預設	描述
autoComplete	string	-	此 prop 可協助使用者更快填寫表單，尤其是在行動裝置上。名稱可能會造成混淆，因為它更像是自動填寫。您可以依照規格瞭解更多資訊。
autoFocus	bool	false	如果為 `true`，則 `input` 元素會在首次掛載期間取得焦點。
classes	object	-	覆寫或擴展套用至元件的樣式。請參閱下方的CSS 類別 API 以取得更多詳細資訊。
color	'primary' \| 'secondary' \| 'error' \| 'info' \| 'success' \| 'warning' \| string	'primary'	元件的顏色。它同時支援預設和自訂主題顏色，可以按照調色盤自訂指南中所示的方式新增。
defaultValue	any	-	預設值。在元件不受控制時使用。
disabled	bool	false	如果為 `true`，則元件會停用。
error	bool	false	如果為 `true`，則標籤會以錯誤狀態顯示。
FormHelperTextProps	object	-	套用至 `FormHelperText` 元素的 Props。已過時－請改用 `slotProps.formHelperText`。此 prop 將在 v7 中移除。請參閱從已過時的 API 遷移以取得更多詳細資訊。
fullWidth	bool	false	如果為 `true`，則輸入將佔據其容器的完整寬度。
helperText	node	-	輔助文字內容。
id	string	-	`input` 元素的 ID。使用此 prop 使 `label` 和 `helperText` 可供螢幕閱讀器存取。
InputLabelProps	object	-	套用至 `InputLabel` 元素的 Props。只有在 `shrink` 為 `true` 時，才會啟用 `onClick` 等指標事件。已過時－請改用 `slotProps.inputLabel`。此 prop 將在 v7 中移除。請參閱從已過時的 API 遷移以取得更多詳細資訊。
inputProps	object	-	套用至 `input` 元素的屬性。已過時－請改用 `slotProps.htmlInput`。此 prop 將在 v7 中移除。請參閱從已過時的 API 遷移以取得更多詳細資訊。
InputProps	object	-	套用至 Input 元素的 Props。它將是 `FilledInput`、`OutlinedInput` 或 `Input` 元件，具體取決於 `variant` prop 值。已過時－請改用 `slotProps.input`。此 prop 將在 v7 中移除。請參閱從已過時的 API 遷移以取得更多詳細資訊。
inputRef	ref	-	將 ref 傳遞至 `input` 元素。
label	node	-	標籤內容。
margin	'dense' \| 'none' \| 'normal'	'none'	如果為 `dense` 或 `normal`，將調整此元件和包含的元件的垂直間距。
maxRows	number \| string	-	當 multiline 選項設定為 true 時，要顯示的最大列數。
minRows	number \| string	-	當 multiline 選項設定為 true 時，要顯示的最小列數。
multiline	bool	false	如果為 `true`，則會轉譯 `textarea` 元素，而不是輸入。
name	string	-	`input` 元素的 Name 屬性。
onChange	func	-	值變更時觸發的回呼。簽名：`function(event: object) => void` `event` 回呼的事件來源。您可以透過存取 `event.target.value` (字串) 來取出新值。
placeholder	string	-	使用者輸入值之前，`input` 中顯示的簡短提示。
required	bool	false	如果為 `true`，則標籤會顯示為必填，且 `input` 元素為必填。
rows	number \| string	-	當 multiline 選項設定為 true 時，要顯示的列數。
select	bool	false	轉譯 `Select` 元素，同時將 Input 元素作為 `input` 參數傳遞至 `Select`。如果設定此選項，您必須將 select 的選項作為子項傳遞。
SelectProps	object	-	套用至 `Select` 元素的 Props。已過時－請改用 `slotProps.select`。此 prop 將在 v7 中移除。請參閱從已過時的 API 遷移以取得更多詳細資訊。
size	'medium' \| 'small' \| string	'medium'	元件的大小。
slotProps	{ formHelperText?: func \| object, htmlInput?: func \| object, input?: func \| object, inputLabel?: func \| object, select?: func \| object }	{}	用於每個插槽內部的 props。
slots	{ formHelperText?: elementType, htmlInput?: elementType, input?: elementType, inputLabel?: elementType, root?: elementType, select?: elementType }	{}	用於每個插槽內部的元件。
sx	Array<func \| object \| bool> \| func \| object	-	系統 prop，允許定義系統覆寫以及其他 CSS 樣式。請參閱 `sx` 頁面以取得更多詳細資訊。
type	string	-	`input` 元素的類型。它應該是有效的 HTML5 輸入類型。
value	any	-	`input` 元素的值，受控元件的必要值。
variant	'filled' \| 'outlined' \| 'standard'	'outlined'	要使用的變體。

元件無法保留 ref。

繼承

雖然上方未明確記錄，但 FormControl 元件的 props 也可在 TextField 中使用。您可以利用這一點定位巢狀元件。

主題預設 props

您可以使用 MuiTextField 透過主題變更此元件的預設 props。

插槽

插槽名稱	類別名稱	預設元件	描述
root	.MuiTextField-root	`FormControl`	轉譯根元件的元件。
input		`OutlinedInput`	轉譯輸入的元件。
inputLabel		`InputLabel`	轉譯輸入標籤的元件。
htmlInput		`'input'`	html 輸入元素。
formHelperText		`FormHelperText`	轉譯輔助文字的元件。
select		`Select`	轉譯選取器的元件。

原始碼

如果您在此頁面中找不到資訊，請考慮查看元件的實作以取得更多詳細資訊。