文本区域

Textarea 组件为您提供一个 textarea HTML 元素，该元素可以自动调整其高度以匹配其中内容的长度。

简介

Joy UI 的 textarea 组件构建于 MUI Base TextareaAutoSize 组件之上。

组件

在安装之后，您可以使用以下基本元素开始构建此组件

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

export default function MyApp() {
  return <Textarea placeholder="Type anything…" />;
}

变体

textarea 组件支持四种全局变体：solid（默认）、soft、outlined 和 plain。

<Textarea name="Solid" placeholder="Type in here…" variant="solid" />
<Textarea name="Soft" placeholder="Type in here…" variant="soft" />
<Textarea name="Outlined" placeholder="Type in here…" variant="outlined" />
<Textarea name="Plain" placeholder="Type in here…" variant="plain" />

<Textarea name="Solid" placeholder="Type in here…" variant="solid" />
<Textarea name="Soft" placeholder="Type in here…" variant="soft" />
<Textarea name="Outlined" placeholder="Type in here…" variant="outlined" />
<Textarea name="Plain" placeholder="Type in here…" variant="plain" />

按 Enter 键开始编辑

尺寸

textarea 组件开箱即用地提供三种尺寸：sm、md（默认）和 lg。

<Textarea size="sm" name="Size" placeholder="Small" />
<Textarea size="md" name="Size" placeholder="Medium" />
<Textarea size="lg" name="Size" placeholder="Large" />

<Textarea size="sm" name="Size" placeholder="Small" />
<Textarea size="md" name="Size" placeholder="Medium" />
<Textarea size="lg" name="Size" placeholder="Large" />

按 Enter 键开始编辑

颜色

通过使用 color 属性切换用于着色文本字段的调色板。

表单属性

标准表单属性受支持，例如 required、disabled 等。

<form
  onSubmit={(event) => {
    event.preventDefault();
  }}
>
  <Textarea
    placeholder="Try to submit with no text!"
    required
    sx={{ mb: 1 }}
  />
  <Textarea placeholder="It is disabled" disabled sx={{ mb: 1 }} />
  <Button type="submit">Submit</Button>
</form>

<form
  onSubmit={(event) => {
    event.preventDefault();
  }}
>
  <Textarea
    placeholder="Try to submit with no text!"
    required
    sx={{ mb: 1 }}
  />
  <Textarea placeholder="It is disabled" disabled sx={{ mb: 1 }} />
  <Button type="submit">Submit</Button>
</form>

按 Enter 键开始编辑

聚焦环

提供这些 CSS 变量到 sx 属性以控制聚焦环的外观

--Textarea-focusedInset：聚焦环的位置，在 Textarea 的内部 (inset) 或外部 (var(--any, ))。
--Textarea-focusedThickness：聚焦环的大小。
--Textarea-focusedHighlight：聚焦环的颜色。

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

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

按 Enter 键开始编辑

要完全控制聚焦环，请直接自定义 ::before 伪元素的 box-shadow

<Textarea sx={{ '&:focus-within::before': { boxShadow: '...your custom value' } }} />

调试聚焦环

要通过模拟用户焦点来显示 Textarea 的聚焦环，请检查 Textarea 元素并切换伪状态面板。

如果您检查 Textarea 的根元素（带有 .MuiTextarea-root 类），则必须启用 :focus-within 状态。
如果您检查 <input> 元素，则必须启用 :focus 状态。

触发聚焦环

要以编程方式触发聚焦环，请设置 CSS 变量 --Textarea-focused: 1。

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

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

按 Enter 键开始编辑

验证

要切换错误状态，请使用 error 属性。

<Textarea
  placeholder="Type in here…"
  error
  defaultValue="Oh no! Something is definitely wrong."
/>

<Textarea
  placeholder="Type in here…"
  error
  defaultValue="Oh no! Something is definitely wrong."
/>

按 Enter 键开始编辑

请注意，将 color 属性与 danger 值一起使用会得到相同的结果

<Textarea color="danger" />

行数

使用 minRows 设置要显示的最小行数，使用 maxRows 限制用户将看到的最大行数。

<Textarea
  placeholder="Type in here…"
  defaultValue="Try to put text longer than 4 lines."
  minRows={2}
  maxRows={4}
/>

<Textarea
  placeholder="Type in here…"
  defaultValue="Try to put text longer than 4 lines."
  minRows={2}
  maxRows={4}
/>

按 Enter 键开始编辑

装饰器

使用 startDecorator 和/或 endDecorator 属性向 textarea 添加支持图标或元素。通常更常见的是看到在顶部和底部使用装饰器的 textarea 组件。

0字符

HTML textarea ref

使用 slotProps.textarea 属性将 props 传递给 ref 和其他受支持的 HTML 属性到 textarea 元素。

<Textarea
  placeholder="Placeholder"
  slotProps={{ textarea: { ref: textareaRef } }}
/>
<Button onClick={handleTextareaFocus}>Focus textarea element</Button>

<Textarea
  placeholder="Placeholder"
  slotProps={{ textarea: { ref: textareaRef } }}
/>
<Button onClick={handleTextareaFocus}>Focus textarea element</Button>

按 Enter 键开始编辑

无障碍性

为了使 textarea 可访问，它应该链接到一个标签。

FormControl 自动生成一个唯一的 ID，将 textarea 与 FormLabel 组件链接起来

标签

这是一个辅助文本。

<FormControl>
  <FormLabel>Label</FormLabel>
  <Textarea placeholder="Placeholder" minRows={2} />
  <FormHelperText>This is a helper text.</FormHelperText>
</FormControl>

<FormControl>
  <FormLabel>Label</FormLabel>
  <Textarea placeholder="Placeholder" minRows={2} />
  <FormHelperText>This is a helper text.</FormHelperText>
</FormControl>

按 Enter 键开始编辑

或者，您可以手动通过定位 textarea 插槽来完成

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

常用示例

聚焦轮廓

此示例显示如何使用 CSS 轮廓替换默认的聚焦环外观。

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

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

按 Enter 键开始编辑

浮动标签

要创建浮动标签 textarea，需要自定义组件（<textarea> 和 <label> 的组合）来替换默认的 textarea 插槽。

标签

<Textarea
  slots={{ textarea: InnerTextarea }}
  slotProps={{ textarea: { placeholder: 'A placeholder' } }}
  sx={{ borderRadius: '6px' }}
/>

<Textarea
  slots={{ textarea: InnerTextarea }}
  slotProps={{ textarea: { placeholder: 'A placeholder' } }}
  sx={{ borderRadius: '6px' }}
/>

按 Enter 键开始编辑

下划线输入框

评论框

您的评论

API

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

<Textarea />

文本区域

Playground

调试聚焦环