> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/zh/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/zh/llms-full.txt.

# Textarea

数据录入`@rockshin/tao-ui`

[代码演示](#代码演示)[API](#api)

输入多行文本，并支持状态、尺寸、变体与自动高度。

## 何时使用

用户需要输入说明、备注或其他多行内容时使用 Textarea。

**推荐**

- 通过 FormField 提供标签与错误信息。
- 合理限制自动高度范围。

**避免**

- 短单行内容应使用 Input。

## 代码演示


### 基础用法
```tsx preview
import { Stack, Textarea } from '@rockshin/tao-ui';

function TextareaExample() {
  return (
    <Stack gap="md" style={{ maxWidth: 420 }}>
      <Textarea placeholder="Write a description" />
      <Textarea
        defaultValue="Autosize grows with its content."
        autoSize={{ minRows: 2, maxRows: 5 }}
      />
      <Textarea value="Invalid content" error readOnly />
    </Stack>
  );
}

export default TextareaExample;
```

### 变体
```tsx preview
import { Stack, Textarea } from '@rockshin/tao-ui';

function TextareaVariants() {
  return (
    <Stack gap="md" style={{ maxWidth: 420 }}>
      <Textarea variant="outlined" placeholder="Outlined" />
      <Textarea variant="filled" placeholder="Filled" />
      <Textarea variant="borderless" placeholder="Borderless" />
    </Stack>
  );
}

export default TextareaVariants;
```

### 尺寸与自动高度
```tsx preview
import { Stack, Textarea } from '@rockshin/tao-ui';

function TextareaSizes() {
  return (
    <Stack gap="md" style={{ maxWidth: 420 }}>
      <Textarea size="small" placeholder="Small" />
      <Textarea
        size="medium"
        autoSize={{ minRows: 2, maxRows: 5 }}
        defaultValue="Autosize grows with content."
      />
      <Textarea size="large" placeholder="Large" />
    </Stack>
  );
}

export default TextareaSizes;
```

### 受控输入与字数
原生 maxLength 限制输入，受控值用于显示剩余字数。
```tsx preview
import { useState } from 'react';
import { Textarea, Stack } from '@rockshin/tao-ui';
export default function Example() {
  const [text, setText] = useState('');
  return (
    <Stack direction="vertical">
      <Textarea
        aria-label="Description"
        value={text}
        maxLength={120}
        onChange={(e) => setText(e.target.value)}
      />
      <output>{text.length} / 120</output>
    </Stack>
  );
}
```

### 有界自动高度
输入多行内容，观察高度在 minRows 与 maxRows 之间增长。
```tsx preview
import { Textarea } from '@rockshin/tao-ui';
export default function Example() {
  return (
    <Textarea
      aria-label="Notes"
      autoSize={{ minRows: 2, maxRows: 6 }}
      placeholder="Enter multiple lines…"
    />
  );
}
```

### 只读、禁用与错误
分别表达可阅读、不可操作和需要修正的状态。
```tsx preview
import { Textarea, Stack } from '@rockshin/tao-ui';
export default function Example() {
  return (
    <Stack direction="vertical">
      <Textarea
        aria-label="Read-only notes"
        readOnly
        value="This record is locked."
      />
      <Textarea
        aria-label="Disabled notes"
        disabled
        defaultValue="Unavailable"
      />
      <Textarea
        aria-label="Invalid notes"
        status="error"
        defaultValue="A reason is required."
      />
    </Stack>
  );
}
```

### 表单提交与重置
通过 name 读取文本域内容，reset 恢复默认值。
```tsx preview
import { useState } from 'react';
import { Textarea, Button, Stack } from '@rockshin/tao-ui';
export default function Example() {
  const [saved, setSaved] = useState('');
  return (
    <form
      onSubmit={(e) => {
        e.preventDefault();
        setSaved(String(new FormData(e.currentTarget).get('notes')));
      }}
      onReset={() => setSaved('')}
    >
      <Stack direction="vertical">
        <Textarea
          name="notes"
          aria-label="Review notes"
          defaultValue="Ready for review"
        />
        <Stack>
          <Button type="submit">Save notes</Button>
          <Button type="reset">Reset</Button>
        </Stack>
        <output aria-live="polite">{saved}</output>
      </Stack>
    </form>
  );
}
```

### 定制输入外观
通过语义部件设置文本域样式，保留组件状态与焦点行为。
```tsx preview
import { Textarea } from '@rockshin/tao-ui';
export default function Example() {
  return (
    <Textarea
      aria-label="Code notes"
      autoSize
      styles={{ textarea: { fontFamily: 'monospace', lineHeight: 1.8 } }}
      defaultValue="const ready = true;"
    />
  );
}
```

## 清空与计数

`Textarea` 与 `Input.TextArea` 是同一组件，支持 `allowClear`、`onClear`、`showCount`、`count`、`onPressEnter` 和 `variant="underlined"`。[查看完整输入家族示例与 API](https://rickyshin93.github.io/tao-ui/zh/components/input.md)。

## API


### [#](#textarea)Textarea



| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| autoSize | Auto-grow height to fit content. `true` grows freely; pass min/max rows to clamp. | `boolean | AutoSizeOptions | undefined` | `-` |

