輸入框

Input 元件方便使用者輸入文字資料。

簡介

Input 元件透過提供擴充的客製化選項和無障礙功能，增強了原生 HTML <input> 標籤的功能。

基本用法

import Input from '@mui/joy/Input';

Input 元件提供可客製化的輸入欄位，可用於收集使用者資訊，例如姓名、電子郵件、密碼或其他類型的資料。

<Input placeholder="Type in here…" />

<Input placeholder="Type in here…" />

按下 Enter 開始編輯

客製化

Variant 變體

Input 元件支援 Joy UI 的四種全域 variant 變體：solid（預設）、soft、outlined 和 plain。

<Input placeholder="Type in here…" variant="solid" />
<Input placeholder="Type in here…" variant="soft" />
<Input placeholder="Type in here…" variant="outlined" />
<Input placeholder="Type in here…" variant="plain" />

<Input placeholder="Type in here…" variant="solid" />
<Input placeholder="Type in here…" variant="soft" />
<Input placeholder="Type in here…" variant="outlined" />
<Input placeholder="Type in here…" variant="plain" />

按下 Enter 開始編輯

尺寸

輸入元件提供三種尺寸：sm、md（預設）和 lg

<Input size="sm" placeholder="Small" />
<Input size="md" placeholder="Medium" />
<Input size="lg" placeholder="Large" />

<Input size="sm" placeholder="Small" />
<Input size="md" placeholder="Medium" />
<Input size="lg" placeholder="Large" />

按下 Enter 開始編輯

顏色

主題中包含的每個調色盤都可以透過 color 屬性使用。

<Input placeholder="Type in here…" variant="outlined" color="primary" />
<Input placeholder="Type in here…" variant="outlined" color="neutral" />
<Input placeholder="Type in here…" variant="outlined" color="danger" />
<Input placeholder="Type in here…" variant="outlined" color="success" />
<Input placeholder="Type in here…" variant="outlined" color="warning" />

<Input placeholder="Type in here…" variant="outlined" color="primary" />
<Input placeholder="Type in here…" variant="outlined" color="neutral" />
<Input placeholder="Type in here…" variant="outlined" color="danger" />
<Input placeholder="Type in here…" variant="outlined" color="success" />
<Input placeholder="Type in here…" variant="outlined" color="warning" />

按下 Enter 開始編輯

表單提交

您可以將標準表單屬性（例如 required 和 disabled）新增至 Input 元件

<form
  onSubmit={(event) => {
    event.preventDefault();
    const formData = new FormData(event.currentTarget);
    const formJson = Object.fromEntries((formData as any).entries());
    alert(JSON.stringify(formJson));
  }}
>
  <Stack spacing={1}>
    <Input placeholder="Try to submit with no text!" required />
    <Input placeholder="It is disabled" disabled />
    <Button type="submit">Submit</Button>
  </Stack>
</form>

<form
  onSubmit={(event) => {
    event.preventDefault();
    const formData = new FormData(event.currentTarget);
    const formJson = Object.fromEntries((formData as any).entries());
    alert(JSON.stringify(formJson));
  }}
>
  <Stack spacing={1}>
    <Input placeholder="Try to submit with no text!" required />
    <Input placeholder="It is disabled" disabled />
    <Button type="submit">Submit</Button>
  </Stack>
</form>

按下 Enter 開始編輯

聚焦環

提供這些 CSS 變數給 sx 屬性以控制聚焦環的外觀

--Input-focusedInset：聚焦環的位置，在 Input 內部 (inset) 或外部 (var(--any, ))。
--Input-focusedThickness：聚焦環的大小。
--Input-focusedHighlight：聚焦環的顏色。

<Input
  placeholder="Bootstrap"
  sx={{
    '--Input-focusedInset': 'var(--any, )',
    '--Input-focusedThickness': '0.25rem',
    '--Input-focusedHighlight': 'rgba(13,110,253,.25)',
    '&::before': {
      transition: 'box-shadow .15s ease-in-out',
    },
    '&:focus-within': {
      borderColor: '#86b7fe',
    },
  }}
/>

<Input
  placeholder="Bootstrap"
  sx={{
    '--Input-focusedInset': 'var(--any, )',
    '--Input-focusedThickness': '0.25rem',
    '--Input-focusedHighlight': 'rgba(13,110,253,.25)',
    '&::before': {
      transition: 'box-shadow .15s ease-in-out',
    },
    '&:focus-within': {
      borderColor: '#86b7fe',
    },
  }}
/>

按下 Enter 開始編輯

偵錯聚焦環

若要透過模擬使用者焦點來顯示 Input 的聚焦環，請檢查 Input 元素並切換虛擬狀態面板。

如果您檢查 Input 的根元素，帶有 .MuiInput-root 類別，則必須開啟 :focus-within 狀態。
如果您檢查 <input> 元素，您可以切換 :focus 或 :focus-within 狀態。

觸發聚焦環

若要以程式方式觸發聚焦環，請設定 CSS 變數 --Input-focused: 1。

<Input
  placeholder="Looks like I'm focused but no"
  sx={{ '--Input-focused': 1, width: 256 }}
/>

<Input
  placeholder="Looks like I'm focused but no"
  sx={{ '--Input-focused': 1, width: 256 }}
/>

按下 Enter 開始編輯

標籤和輔助文字

將 Input 與 Form label 和 Form helper text 群組在 Form control 元件中，以建立文字欄位。

標籤

這是輔助文字。

<FormControl>
  <FormLabel>Label</FormLabel>
  <Input placeholder="Placeholder" />
  <FormHelperText>This is a helper text.</FormHelperText>
</FormControl>

<FormControl>
  <FormLabel>Label</FormLabel>
  <Input placeholder="Placeholder" />
  <FormHelperText>This is a helper text.</FormHelperText>
</FormControl>

按下 Enter 開始編輯

驗證

在 Input 或 Form Control 上使用 error 屬性來切換錯誤狀態

標籤

糟糕！發生錯誤。

<Input placeholder="Type in here…" error defaultValue="Oh no, error found!" />
<FormControl error>
  <FormLabel>Label</FormLabel>
  <Input placeholder="Type in here…" defaultValue="Oh no, error found!" />
  <FormHelperText>
    <InfoOutlined />
    Opps! something is wrong.
  </FormHelperText>
</FormControl>

<Input placeholder="Type in here…" error defaultValue="Oh no, error found!" />
<FormControl error>
  <FormLabel>Label</FormLabel>
  <Input placeholder="Type in here…" defaultValue="Oh no, error found!" />
  <FormHelperText>
    <InfoOutlined />
    Opps! something is wrong.
  </FormHelperText>
</FormControl>

按下 Enter 開始編輯

裝飾器

startDecorator 和 endDecorator 屬性可用於將支援圖示或元素新增至輸入框。對於輸入框，裝飾器通常位於輸入欄位的頂部和/或底部。

內部 HTML 輸入框

如果您需要將屬性傳遞至內部 HTML <input>，請使用 slotProps={{ input: { ...props } }}。這些屬性可能包含 HTML 屬性，例如 ref、min、max 和 autocomplete。

CSS 變數 Playground

試用 Input 元件可用的 CSS 變數，以查看設計如何變化。您可以使用這些變數透過 sx 屬性和主題來客製化元件。

<Input
  startDecorator={<MailIcon />}
  endDecorator={<Button>Message</Button>}
>

CSS 變數

--Input-radius

--Input-gap

--Input-placeholderOpacity

--Input-focusedThickness

--Input-minHeight

--Input-paddingInline

--Input-decoratorChildHeight

常見範例

聚焦外框

此範例示範如何使用 CSS outline 取代預設聚焦環（使用 ::before）。

<Input
  placeholder="Type in here…"
  sx={{
    '&::before': {
      display: 'none',
    },
    '&:focus-within': {
      outline: '2px solid var(--Input-focusedHighlight)',
      outlineOffset: '2px',
    },
  }}
/>

<Input
  placeholder="Type in here…"
  sx={{
    '&::before': {
      display: 'none',
    },
    '&:focus-within': {
      outline: '2px solid var(--Input-focusedHighlight)',
      outlineOffset: '2px',
    },
  }}
/>

按下 Enter 開始編輯

浮動標籤

若要建立浮動標籤輸入框，需要自訂元件（<input> 和 <label> 的組合）來取代預設的輸入框 slot。

標籤

<Input
  endDecorator={<CheckCircleOutlined />}
  slots={{ input: InnerInput }}
  slotProps={{ input: { placeholder: 'A placeholder', type: 'password' } }}
  sx={{ '--Input-minHeight': '56px', '--Input-radius': '6px' }}
/>

<Input
  endDecorator={<CheckCircleOutlined />}
  slots={{ input: InnerInput }}
  slotProps={{ input: { placeholder: 'A placeholder', type: 'password' } }}
  sx={{ '--Input-minHeight': '56px', '--Input-radius': '6px' }}
/>

按下 Enter 開始編輯

底線輸入框

密碼強度計

非常弱

防抖輸入框

<DebounceInput
  placeholder="Type in here…"
  debounceTimeout={1000}
  handleDebounce={handleDebounce}
/>
<Typography>Debounced input: {debouncedValue}</Typography>

<DebounceInput
  placeholder="Type in here…"
  debounceTimeout={1000}
  handleDebounce={handleDebounce}
/>
<Typography>Debounced input: {debouncedValue}</Typography>

按下 Enter 開始編輯

第三方格式化

Input 元件可以與第三方格式化函式庫整合，以用於更複雜的使用情境。

建立一個轉接器元件，以從 Input 元件取得屬性，並將它們對應到第三方元件 API。然後使用該轉接器作為 Joy UI Input 的 slotProps.input.component 屬性的值。

以下示範說明如何使用兩個流行的函式庫來執行此操作。

React imask

react-imask 提供 IMaskInput 元件，用於複雜的格式化選項。

標籤

<FormControl>
  <FormLabel>Label</FormLabel>
  <Input
    value={value}
    onChange={(event) => setValue(event.target.value)}
    placeholder="Placeholder"
    slotProps={{ input: { component: TextMaskAdapter } }}
  />
</FormControl>

<FormControl>
  <FormLabel>Label</FormLabel>
  <Input
    value={value}
    onChange={(event) => setValue(event.target.value)}
    placeholder="Placeholder"
    slotProps={{ input: { component: TextMaskAdapter } }}
  />
</FormControl>

按下 Enter 開始編輯

React number format

react-number-format 提供 NumericFormat 元件，用於強制執行遵循特定數字或字串模式的文字格式化。

React number format

<FormControl>
  <FormLabel>React number format</FormLabel>
  <Input
    value={value}
    onChange={(event) => setValue(event.target.value)}
    placeholder="Placeholder"
    slotProps={{
      input: {
        component: NumericFormatAdapter,
      },
    }}
  />
</FormControl>

<FormControl>
  <FormLabel>React number format</FormLabel>
  <Input
    value={value}
    onChange={(event) => setValue(event.target.value)}
    placeholder="Placeholder"
    slotProps={{
      input: {
        component: NumericFormatAdapter,
      },
    }}
  />
</FormControl>

按下 Enter 開始編輯

無障礙設計

所有輸入框都應具有描述性標籤連結，以協助使用者瞭解其用途。

Form Control 元件會自動產生唯一的 ID，將 Input 與 Form Label 和 Form Helper Text 元件連結

標籤

這是輔助文字。

<FormControl>
  <FormLabel>Label</FormLabel>
  <Input placeholder="Placeholder" />
  <FormHelperText>This is a helper text.</FormHelperText>
</FormControl>

<FormControl>
  <FormLabel>Label</FormLabel>
  <Input placeholder="Placeholder" />
  <FormHelperText>This is a helper text.</FormHelperText>
</FormControl>

按下 Enter 開始編輯

或者，您可以手動執行此操作，方法是鎖定輸入框 slot — 請參閱內部 HTML 輸入框以瞭解詳細資訊

<label htmlFor="unique-id">Label</label>
<Input
  slotProps={{
    input: {
      id: 'unique-id',
    }
  }}
/>

結構

Input 元件由根 <div> 組成，其中巢狀包含 <input>

<div class="MuiInput-root">
  <input class="MuiInput-input" />
</div>

無樣式

使用Base UI Input 完全掌控元件的設計，而無需覆寫 Material UI 或 Joy UI 樣式。此元件的無樣式版本是高度客製化的理想選擇，且套件大小更小。

API

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