> Leaf UI 0.17.3 · Package: @ifhover/leaf-ui · Source: c3221834f84f2f48481a2054026b713456f8e5dc
> Browser documentation: https://ifhover.github.io/leaf-ui/components/textarea.html

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

# Textarea 文本域

输入多行文本，如留言、简介或备注。


## 基础用法

使用多行输入框编辑文本，并为字段提供关联名称。


项目简介

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/textarea/basic.tsx"
import { Form, FormField, Textarea } from '@ifhover/leaf-ui';

export function TextareaBasic() {
  return (
    <Form layout="vertical">
      <FormField label="项目简介">
        <Textarea name="description" placeholder="描述一下你的新想法" />
      </FormField>
    </Form>
  );
}
```

展开代码


## 示例

### 状态

使用 `readOnly`、`disabled` 或 `FormField` 的错误信息表达字段状态。


只读

禁用

错误

请补充描述。

states.tsx

复制代码

```tsx lineNumbers file="../../src/examples/textarea/states.tsx"
import { Form, FormField, Textarea } from '@ifhover/leaf-ui';

export function TextareaStates() {
  return (
    <Form layout="vertical">
      <FormField label="只读">
        <Textarea defaultValue="项目的公开介绍。" readOnly />
      </FormField>
      <FormField label="禁用">
        <Textarea placeholder="暂时不可编辑" disabled />
      </FormField>
      <FormField label="错误" error="请补充描述。">
        <Textarea placeholder="请补充描述" />
      </FormField>
    </Form>
  );
}
```

展开代码

### 自动高度

`autoSize` 根据内容调整高度，`minRows` 与 `maxRows` 限制行数；达到最大高度后在文本域内滚动。


项目简介

auto-size.tsx

复制代码

```tsx lineNumbers file="../../src/examples/textarea/auto-size.tsx"
import { Form, FormField, Textarea } from '@ifhover/leaf-ui';

export function TextareaAutoHeight() {
  return (
    <Form layout="vertical">
      <FormField label="项目简介">
        <Textarea autoSize={{ minRows: 2, maxRows: 6 }} placeholder="输入更多内容试试" />
      </FormField>
    </Form>
  );
}
```

展开代码

### 字数统计

设置 `showCount` 显示统计，搭配 `maxLength` 限制输入长度。


备注

8 / 120

count.tsx

复制代码

```tsx lineNumbers file="../../src/examples/textarea/count.tsx"
import { Form, FormField, Textarea } from '@ifhover/leaf-ui';

export function TextareaCount() {
  return (
    <Form layout="vertical">
      <FormField label="备注">
        <Textarea showCount maxLength={120} defaultValue="计划从这里开始。" />
      </FormField>
    </Form>
  );
}
```

展开代码

[](#)
### 受控输入

通过 `value` 和 `onChange` 管理内容，示例用当前值更新长度提示。


留言

0 / 120

controlled.tsx

复制代码

```tsx lineNumbers file="../../src/examples/textarea/controlled.tsx"
import { Form, FormField, Textarea } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function TextareaControlled() {
  const [value, setValue] = useState('');
  return (
    <Form layout="vertical">
      <FormField label="留言" help={`${value.length} / 120`}>
        <Textarea
          value={value}
          maxLength={120}
          resize="none"
          placeholder="最多 120 个字符"
          onChange={(event) => setValue(event.target.value)}
        />
      </FormField>
    </Form>
  );
}
```

展开代码

#### 表单接入

使用 `FormField` 或 `aria-label` 提供名称。设置 `name` 可参与原生表单提交；非受控值支持表单重置，受控值需同步重置应用状态。表单接入见 [Form](https://ifhover.github.io/leaf-ui/components/form.md)。


## API

### Textarea API

配置多行文本、字数限制和输入状态。

| 属性                       | 类型                                                              | 默认值          | 说明                          |
| ------------------------ | --------------------------------------------------------------- | ------------ | --------------------------- |
| `size`                   | `'sm' \| 'md' \| 'lg'`                                          | `'md'`       | 文本域尺寸                       |
| `status`                 | `'error' \| 'warning'`                                          | —            | 校验状态                        |
| `rows`                   | `number`                                                        | `3`          | 初始可见行数                      |
| `resize`                 | `'none' \| 'vertical' \| 'both'`                                | `'vertical'` | 允许的手动缩放方向                   |
| `value` / `defaultValue` | `string \| number \| readonly string[]`                         | —            | 受控值 / 非受控初始值                |
| `onChange`               | `ChangeEventHandler<HTMLTextAreaElement>`                       | —            | 从 `event.target.value` 读取内容 |
| `disabled` / `readOnly`  | `boolean`                                                       | `false`      | 禁用 / 只读                     |
| `ref`                    | `Ref<HTMLTextAreaElement>`                                      | —            | 文本域引用                       |
| `autoSize`               | [`boolean \| TextareaAutoSize`](#textareaautosize-api)          | `false`      | 根据内容调整高度，可限制行数              |
| `showCount`              | `boolean \| ((value: string, maxLength?: number) => ReactNode)` | `false`      | 显示字数，可自定义渲染                 |

### TextareaAutoSize API

限制自动调整高度时使用的最小和最大行数。

| 属性        | 类型       | 默认值 | 说明   |
| --------- | -------- | --- | ---- |
| `minRows` | `number` | —   | 最少行数 |
| `maxRows` | `number` | —   | 最多行数 |
