---
title: Textarea
description: 带字数统计与状态样式的多行输入框
category: Form
status: beta
since: 0.3.7
tags: [textarea, form, multiline]
syncStatus: reviewed
verified: true
---

## 用法

### 基础
::::TuffDemoWrapper{demo="TextareaTextareaDemo" code-lang="vue"}
---
code: |
  <script setup lang="ts">
  import { ref } from 'vue'

  const value = ref('')
  </script>

  <template>
    <TxTextarea
      v-model="value"
      placeholder="记录这次发布审阅结论..."
      :max-length="160"
      show-count
      :status="value.trim() ? 'success' : 'error'"
    />
  </template>
---
::::

### 最佳实践

- 有长度上限的备注、摘要与 Prompt 搭配 `maxLength` 与 `showCount`。
- 普通表单保持 `resize="vertical"`；外层布局已控制高度时才用 `none`。
- `status` 只做视觉提示；标签、帮助与校验文案放在外层表单项。

### 边缘与状态

文本域与输入框使用同一条内描边；错误与焦点只改变描边颜色和光晕，尺寸不变。

:::TuffDemoWrapper{demo="TextareaEdgeDemo" code-lang="vue"}
---
code: |
  <template>
    <TxTextarea v-model="text" :rows="2" />
    <TxTextarea status="error" />
  </template>
---
:::

## API 参考

### 属性

| 属性名 | 类型 | 默认值 | 说明 |
|------|------|---------|------|
| `modelValue` / `v-model` | `string` | `''` | 输入值。 |
| `placeholder` | `string` | `''` | 占位文本。 |
| `rows` | `number` | `4` | 原生行数。 |
| `disabled` | `boolean` | `false` | 原生禁用态。 |
| `readonly` | `boolean` | `false` | 原生只读态。 |
| `maxLength` | `number` | - | 原生最大长度，也是计数的分母。 |
| `showCount` | `boolean` | `false` | 显示字数；有 `maxLength` 时格式为 `current/max`。 |
| `resize` | `'none' \| 'vertical' \| 'horizontal' \| 'both'` | `'vertical'` | CSS `resize` 行为。 |
| `status` | `'default' \| 'success' \| 'error'` | `'default'` | 视觉校验状态。 |

### 事件

| 事件名 | 参数 | 说明 |
|------|------|------|
| `update:modelValue` | `(value: string)` | 输入时触发。 |
| `input` | `(value: string)` | 与 `update:modelValue` 同时触发。 |
| `focus` | `(event: FocusEvent)` | 原生 focus 事件。 |
| `blur` | `(event: FocusEvent)` | 原生 blur 事件。 |

### 暴露方法

| 方法 | 说明 |
|------|------|
| `focus()` | 聚焦原生 textarea。 |
| `blur()` | 使原生 textarea 失焦。 |
| `textareaRef` | 原生 textarea 的 ref。 |

## 概述

- 外部 `class` 与 `style` 留在根节点，其余 attrs（如 `id`、`name`）透传给内部 `<textarea>`。
- 在 `TxFormItem` 中自动取得 id、`aria-describedby`、`aria-invalid` 与 `required`，显示错误时 `status` 为 `error`；表单的 `disabled` 同样生效。显式传入的属性优先。

## 技术实现

- 源码：`packages/tuffex/packages/components/src/textarea/`；导出 `TxTextareaInstance` 类型。

<TuffDocSourceLink />
