输入框

Input 组件方便用户输入文本数据。

简介

Input 组件通过提供扩展的自定义选项和可访问性功能，增强了原生 HTML <input> 标签的功能。

基础知识

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

Input 组件提供了一个可自定义的输入字段，可用于收集用户信息，例如姓名、电子邮件、密码或其他类型的数据。

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

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

按 Enter 键开始编辑

自定义

变体

Input 组件支持 Joy UI 的四种全局变体：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 键开始编辑

表单提交

您可以向 Input 组件添加标准表单属性，例如 required 和 disabled

<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 输入框

如果您需要将 props 传递给内部 HTML <input>，请使用 slotProps={{ input: { ...props } }}。这些 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> 的组合）来替换默认的输入插槽。

标签

<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 组件获取 props 并将其映射到第三方组件 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 键开始编辑

或者，您可以手动执行此操作，方法是定位输入插槽 - 有关详细信息，请参见内部 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

请参阅下面的文档，以获取此处提及的组件的所有可用 props 和类的完整参考。