文字欄位

文字欄位讓使用者輸入和編輯文字。

文字欄位允許使用者在 UI 中輸入文字。它們通常出現在表單和對話方塊中。

基本文字欄位

TextField 包裝元件是一個完整的表單控制項，包含標籤、輸入和輔助文字。它有三種變體：外框（預設）、填滿和標準。

<TextField id="outlined-basic" label="Outlined" variant="outlined" />
<TextField id="filled-basic" label="Filled" variant="filled" />
<TextField id="standard-basic" label="Standard" variant="standard" />

<TextField id="outlined-basic" label="Outlined" variant="outlined" />
<TextField id="filled-basic" label="Filled" variant="filled" />
<TextField id="standard-basic" label="Standard" variant="standard" />

按下 Enter 開始編輯

表單屬性

支援標準表單屬性，例如 required、disabled、type 等，以及 helperText，用於提供有關欄位輸入的上下文，例如輸入將如何使用。

控制 HTML 輸入

使用 slotProps.htmlInput 將屬性傳遞到底層的 <input> 元素。

<TextField slotProps={{ htmlInput: { 'data-testid': '…' } }} />

呈現的 HTML 輸入將如下所示

<input
  aria-invalid="false"
  class="MuiInputBase-input MuiOutlinedInput-input"
  type="text"
  data-testid="…"
/>

驗證

error 屬性切換錯誤狀態。然後可以使用 helperText 屬性向使用者提供有關錯誤的回饋。

多行

multiline 屬性將文字欄位轉換為 MUI Base Textarea Autosize 元素。除非設定了 rows 屬性，否則文字欄位的高度會動態符合其內容。您可以使用 minRows 和 maxRows 屬性來限制它。

選取器

select 屬性使文字欄位在內部使用 Select 元件。

圖示

有多種方法可以在文字欄位中顯示圖示。

使用開始裝飾

TextField

使用 sx

輸入裝飾

主要方法是使用 InputAdornment。這可用於向輸入新增前綴、後綴或動作。例如，您可以使用圖示按鈕來隱藏或顯示密碼。

使用一般 TextField

公斤

重量

密碼

金額

使用一般 TextField

公斤

重量

密碼

金額

使用一般 TextField

公斤

重量

密碼

金額

自訂裝飾

您可以將自訂樣式套用至裝飾，並根據另一個裝飾的屬性觸發對一個裝飾的變更。例如，以下示範使用標籤的 [data-shrink=true] 屬性，在標籤處於縮小狀態時使後綴可見（透過不透明度）。

尺寸

想要更小的輸入？請使用 size 屬性。

filled 變體輸入高度可以透過在外部呈現標籤來進一步縮減。

<TextField
  hiddenLabel
  id="filled-hidden-label-small"
  defaultValue="Small"
  variant="filled"
  size="small"
/>
<TextField
  hiddenLabel
  id="filled-hidden-label-normal"
  defaultValue="Normal"
  variant="filled"
/>

<TextField
  hiddenLabel
  id="filled-hidden-label-small"
  defaultValue="Small"
  variant="filled"
  size="small"
/>
<TextField
  hiddenLabel
  id="filled-hidden-label-normal"
  defaultValue="Normal"
  variant="filled"
/>

按下 Enter 開始編輯

邊距

margin 屬性可用於變更文字欄位的垂直間距。使用 none（預設）不會將邊距套用至 FormControl，而 dense 和 normal 會套用邊距。

margin="none"

margin="dense"

margin="normal"

<RedBar />
<TextField label={'margin="none"'} id="margin-none" />
<RedBar />
<TextField label={'margin="dense"'} id="margin-dense" margin="dense" />
<RedBar />
<TextField label={'margin="normal"'} id="margin-normal" margin="normal" />
<RedBar />

<RedBar />
<TextField label={'margin="none"'} id="margin-none" />
<RedBar />
<TextField label={'margin="dense"'} id="margin-dense" margin="dense" />
<RedBar />
<TextField label={'margin="normal"'} id="margin-normal" margin="normal" />
<RedBar />

按下 Enter 開始編輯

全寬

fullWidth 可用於使輸入佔用其容器的完整寬度。

fullWidth

<TextField fullWidth label="fullWidth" id="fullWidth" />

<TextField fullWidth label="fullWidth" id="fullWidth" />

按下 Enter 開始編輯

非受控 vs. 受控

元件可以是受控或非受控的。

<TextField
  id="outlined-controlled"
  label="Controlled"
  value={name}
  onChange={(event: React.ChangeEvent<HTMLInputElement>) => {
    setName(event.target.value);
  }}
/>
<TextField
  id="outlined-uncontrolled"
  label="Uncontrolled"
  defaultValue="foo"
/>

<TextField
  id="outlined-controlled"
  label="Controlled"
  value={name}
  onChange={(event: React.ChangeEvent<HTMLInputElement>) => {
    setName(event.target.value);
  }}
/>
<TextField
  id="outlined-uncontrolled"
  label="Uncontrolled"
  defaultValue="foo"
/>

按下 Enter 開始編輯

元件

TextField 由較小的元件（FormControl、Input、FilledInput、InputLabel、OutlinedInput 和 FormHelperText）組成，您可以直接利用它們來大幅自訂您的表單輸入。

您可能也注意到 TextField 元件中缺少一些原生 HTML 輸入屬性。這是故意的。元件會處理最常用的屬性。然後，使用者可以使用以下示範中顯示的底層元件。不過，如果您想避免一些樣板程式碼，您仍然可以使用 slotProps.htmlInput（和 slotProps.input、slotProps.inputLabel 屬性）。

輸入

<Input defaultValue="Hello world" inputProps={ariaLabel} />
<Input placeholder="Placeholder" inputProps={ariaLabel} />
<Input disabled defaultValue="Disabled" inputProps={ariaLabel} />
<Input defaultValue="Error" error inputProps={ariaLabel} />

<Input defaultValue="Hello world" inputProps={ariaLabel} />
<Input placeholder="Placeholder" inputProps={ariaLabel} />
<Input disabled defaultValue="Disabled" inputProps={ariaLabel} />
<Input defaultValue="Error" error inputProps={ariaLabel} />

按下 Enter 開始編輯

顏色

color 屬性會在文字欄位取得焦點時變更其醒目提示色彩。

<TextField label="Outlined secondary" color="secondary" focused />
<TextField label="Filled success" variant="filled" color="success" focused />
<TextField
  label="Standard warning"
  variant="standard"
  color="warning"
  focused
/>

<TextField label="Outlined secondary" color="secondary" focused />
<TextField label="Filled success" variant="filled" color="success" focused />
<TextField
  label="Standard warning"
  variant="standard"
  color="warning"
  focused
/>

按下 Enter 開始編輯

自訂

以下是一些自訂元件的範例。您可以在覆寫文件頁面中深入瞭解這方面資訊。

使用 styled API

使用主題樣式覆寫 API

使用 styleOverrides 鍵來變更 Material UI 注入到 DOM 中的任何樣式。請參閱主題樣式覆寫文件以瞭解更多詳細資訊。

外框

填滿

標準

<ThemeProvider theme={customTheme(outerTheme)}>
  <TextField label="Outlined" />
  <TextField label="Filled" variant="filled" />
  <TextField label="Standard" variant="standard" />
</ThemeProvider>

<ThemeProvider theme={customTheme(outerTheme)}>
  <TextField label="Outlined" />
  <TextField label="Filled" variant="filled" />
  <TextField label="Standard" variant="standard" />
</ThemeProvider>

按下 Enter 開始編輯

自訂不只侷限於 CSS。您可以使用組合來建置自訂元件，並為您的應用程式提供獨特的外觀。以下是使用 InputBase 元件的範例，其靈感來自 Google 地圖。

🎨 如果您正在尋找靈感，可以查看 MUI Treasury 的自訂範例。

`useFormControl`

對於進階自訂用例，公開了 useFormControl() Hook。此 Hook 會傳回父 FormControl 元件的內容值。

API

import { useFormControl } from '@mui/material/FormControl';

傳回

value (物件)

value.adornedStart (布林值)：指出子 Input 或 Select 元件是否具有開始裝飾。
value.setAdornedStart (函式)：adornedStart 狀態值的設定器函式。
value.color (字串)：正在使用的主題色彩，繼承自 FormControl color 屬性。
value.disabled (布林值)：指出元件是否以停用狀態顯示，繼承自 FormControl disabled 屬性。
value.error (布林值)：指出元件是否以錯誤狀態顯示，繼承自 FormControl error 屬性
value.filled (布林值)：指出輸入是否已填滿
value.focused (布林值)：指出元件及其子元件是否以焦點狀態顯示
value.fullWidth (布林值)：指出元件是否佔用其容器的完整寬度，繼承自 FormControl fullWidth 屬性
value.hiddenLabel (布林值)：指出標籤是否隱藏，繼承自 FormControl hiddenLabel 屬性
value.required (布林值)：指出標籤是否指示輸入為必要輸入，繼承自 FormControl required 屬性
value.size (字串)：元件的尺寸，繼承自 FormControl size 屬性
value.variant (字串)：FormControl 元件及其子元件正在使用的變體，繼承自 FormControl variant 屬性
value.onBlur (函式)：應在輸入失去焦點時呼叫
value.onFocus (函式)：應在輸入取得焦點時呼叫
value.onEmpty (函式)：應在輸入清空時呼叫
value.onFilled (函式)：應在輸入填滿時呼叫

範例

<form noValidate autoComplete="off">
  <FormControl sx={{ width: '25ch' }}>
    <OutlinedInput placeholder="Please enter text" />
    <MyFormHelperText />
  </FormControl>
</form>

<form noValidate autoComplete="off">
  <FormControl sx={{ width: '25ch' }}>
    <OutlinedInput placeholder="Please enter text" />
    <MyFormHelperText />
  </FormControl>
</form>

按下 Enter 開始編輯

效能

自動填滿關鍵影格的全域樣式會在每次掛載和卸載時分別注入和移除。如果您一次載入大量文字欄位元件，則最好透過在 MuiInputBase 中啟用 disableInjectingGlobalStyles 來變更此預設行為。請務必在應用程式頂端注入自動填滿關鍵影格的 GlobalStyles。

import { GlobalStyles, createTheme, ThemeProvider } from '@mui/material';

const theme = createTheme({
  components: {
    MuiInputBase: {
      defaultProps: {
        disableInjectingGlobalStyles: true,
      },
    },
  },
});

export default function App() {
  return (
    <ThemeProvider theme={theme}>
      <GlobalStyles
        styles={{
          '@keyframes mui-auto-fill': { from: { display: 'block' } },
          '@keyframes mui-auto-fill-cancel': { from: { display: 'block' } },
        }}
      />
      ...
    </ThemeProvider>
  );
}

限制

縮小

輸入標籤「縮小」狀態並不總是正確。輸入標籤應該在輸入顯示內容後立即縮小。在某些情況下，我們無法判斷「縮小」狀態（數字輸入、日期時間輸入、Stripe 輸入）。您可能會注意到重疊。

shrink

若要解決此問題，您可以強制標籤的「縮小」狀態。

<TextField slotProps={{ inputLabel: { shrink: true } }} />

或

<InputLabel shrink>Count</InputLabel>

請輸入您的姓名

名稱

<TextField
  helperText="Please enter your name"
  id="demo-helper-text-misaligned"
  label="Name"
/>
<TextField id="demo-helper-text-misaligned-no-helper" label="Name" />

<TextField
  helperText="Please enter your name"
  id="demo-helper-text-misaligned"
  label="Name"
/>
<TextField id="demo-helper-text-misaligned-no-helper" label="Name" />

按下 Enter 開始編輯

這可以透過將空格字元傳遞至 helperText 屬性來修正

名稱

請輸入您的姓名

名稱

<TextField
  helperText="Please enter your name"
  id="demo-helper-text-aligned"
  label="Name"
/>
<TextField
  helperText=" "
  id="demo-helper-text-aligned-no-helper"
  label="Name"
/>

<TextField
  helperText="Please enter your name"
  id="demo-helper-text-aligned"
  label="Name"
/>
<TextField
  helperText=" "
  id="demo-helper-text-aligned-no-helper"
  label="Name"
/>

按下 Enter 開始編輯

與第三方輸入程式庫整合

您可以使用第三方程式庫來格式化輸入。您必須使用 inputComponent 屬性提供 <input> 元素的自訂實作。

以下示範使用 react-imask 和 react-number-format 程式庫。相同的概念可以應用於例如 react-stripe-element。

react-imask

react-number-format

提供的輸入元件應公開一個 ref，其值實作以下介面

interface InputElement {
  focus(): void;
  value?: string;
}

const MyInputComponent = React.forwardRef((props, ref) => {
  const { component: Component, ...other } = props;

  // implement `InputElement` interface
  React.useImperativeHandle(ref, () => ({
    focus: () => {
      // logic to focus the rendered component from 3rd party belongs here
    },
    // hiding the value e.g. react-stripe-elements
  }));

  // `Component` will be your `SomeThirdPartyComponent` from below
  return <Component {...other} />;
});

// usage
<TextField
  slotProps={{
    input: {
      inputComponent: MyInputComponent,
      inputProps: {
        component: SomeThirdPartyComponent,
      },
    },
  }}
/>;

協助工具

為了使文字欄位具有協助工具，**輸入應連結到標籤和輔助文字**。底層 DOM 節點應具有此結構

<div class="form-control">
  <label for="my-input">Email address</label>
  <input id="my-input" aria-describedby="my-helper-text" />
  <span id="my-helper-text">We'll never share your email.</span>
</div>

如果您使用的是 TextField 元件，您只需提供唯一的 id，除非您僅在用戶端使用 TextField。在 UI 還原之前，沒有明確 id 的 TextField 將不會有相關聯的標籤。
如果您要組合元件

<FormControl>
  <InputLabel htmlFor="my-input">Email address</InputLabel>
  <Input id="my-input" aria-describedby="my-helper-text" />
  <FormHelperText id="my-helper-text">We'll never share your email.</FormHelperText>
</FormControl>

補充專案

對於更進階的用例，您或許可以利用

react-hook-form-mui：Material UI 和 react-hook-form 的組合。
formik-material-ui：用於將 Material UI 與 formik 搭配使用的繫結。
mui-rff：用於將 Material UI 與 React Final Form 搭配使用的繫結。
@ui-schema/ds-material 用於將 Material UI 與 UI Schema 搭配使用的繫結。JSON Schema 相容。

無樣式

使用 Base UI 文字欄位以完全擁有元件的設計，無需覆寫 Material UI 或 Joy UI 樣式。此元件的無樣式版本是需要大量自訂且套件大小較小的理想選擇。

API

請參閱以下文件，以取得此處提及之元件可用的所有屬性和類別的完整參考。

文字欄位

基本文字欄位

表單屬性

控制 HTML 輸入

驗證

多行

選取器

圖示

輸入裝飾

自訂裝飾

尺寸

邊距

全寬

非受控 vs. 受控

元件

輸入

顏色

自訂

使用 styled API

使用主題樣式覆寫 API

`useFormControl`

效能

限制

縮小

浮動標籤

type="number"

輔助文字

與第三方輸入程式庫整合

協助工具

補充專案

無樣式

API