文本域
概述
用于输入多行文本的组件，支持自动高度、字符计数与可清除功能。适用于描述、评论、留言等跨行内容。单行输入请使用 SInput。
用法
特性
- 📏 6 种尺寸：xs、sm、md、lg、xl、2xl
- 📐 自动高度，支持
minRows/maxRows边界与 overflow 切换 - 🧹 可清除模式，清除按钮带 i18n
aria-label - 🔢 字符计数器（
count / maxlength），有无maxlength两种形态 - 🔄
resize控制：none / vertical / horizontal（autosize 启用时忽略） - 📋 设置
name时通过代理隐藏输入框支持原生表单提交 - 🧩
clear/counter/footer插槽，可按需定制各部分 - ♿ 完整无障碍支持——
aria-roledescription、清除按钮命名、axe 零违规
文本域组件系列
- STextarea - 基础多行文本域组件
- STextareaClear - 清除按钮，
clearable时悬停/聚焦显示
演示
基础
100%
底部
100%
API
Aria 层
6Textarea
22 属性2 事件3 插槽
属性
| 属性名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
class | ClassValue | — | 应用于根元素的额外类名。 |
size | ThemeSize | — | 组件的视觉尺寸。 |
ui | Partial<TextareaUi> | — | 该组件的按槽类重写。 |
resize | TextareaResize | — | textarea 的调整大小
如果 autosize 为 true，则会忽略调整大小操作 |
textareaRef | ((el: HTMLTextAreaElement) => void) | — | 用于设置 textarea 元素的函数。 |
clearable | boolean | false | 是否显示“清除”按钮。 |
showCounter | boolean | false | 是否显示计数器。 |
controlProps | TextareaControlProps | — | 转发给控件的属性。 |
clearProps | TextareaClearProps | — | 转发给 `clear` 元素的属性。 |
counterProps | TextareaCounterProps | — | 转发给计数器元素的属性。 |
defaultValue | string | — | textarea 的默认值 |
modelValue | string | — | textarea 控件的值 |
autosize | boolean | TextareaAutosizeOptions | — | 当值为 `true` 或为选项对象时，启用基于内容的自动调整大小功能 |
id | string | — | textarea 元素的 ID |
autofocus | boolean | — | 当值为 `true` 时，文本区域会自动获得焦点。 |
disabled | boolean | — | 当值为 `true` 时，禁止用户与文本区域进行交互。 |
maxlength | number | — | 文本区域中允许的最大字符数 |
minlength | number | — | 文本区域中允许的最小字符数 |
placeholder | string | — | 文本区域的占位符 |
readonly | boolean | — | 当值为 `true` 时，文本区域为只读。 |
name | string | — | 字段的名称。作为名称/值对的一部分，与其所属表单一同提交。 |
required | boolean | — | 当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。 |
事件
| 事件名 | 参数 | 描述 |
|---|---|---|
update:modelValue | string | 当模型值发生变化时触发。 |
clear | PointerEvent | 点击“清除”按钮时触发。 |
插槽
| 插槽名 | 参数 | 描述 |
|---|---|---|
clear | TextareaCompactSlotProps | 为“clear”槽位定制内容。 |
counter | TextareaCompactSlotProps | 计数器插槽的自定义内容。 |
footer | TextareaCompactSlotProps | 页脚位置的自定义内容。 |
TextareaClear
4 属性1 事件
属性
| 属性名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
type | ButtonType | 'button' | 按钮元素的类型。可以是 'button'、'submit' 或 'reset' 之一。 |
disabled | boolean | — | 该组件是否已禁用。 |
asChild | boolean | — | 将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。 |
as | AsTag | Component | 'div' | 该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。 |
事件
| 事件名 | 参数 | 描述 |
|---|---|---|
clear | PointerEvent | 点击“清除”按钮时触发。 |
TextareaCompact
18 属性2 事件3 插槽
属性
| 属性名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
textareaRef | ((el: HTMLTextAreaElement) => void) | — | 用于设置 textarea 元素的函数。 |
clearable | boolean | false | 是否显示“清除”按钮。 |
showCounter | boolean | false | 是否显示计数器。 |
controlProps | TextareaControlProps | — | 转发给控件的属性。 |
clearProps | TextareaClearProps | — | 转发给 `clear` 元素的属性。 |
counterProps | TextareaCounterProps | — | 转发给计数器元素的属性。 |
defaultValue | string | — | textarea 的默认值 |
modelValue | string | — | textarea 控件的值 |
autosize | boolean | TextareaAutosizeOptions | — | 当值为 `true` 或为选项对象时，启用基于内容的自动调整大小功能 |
id | string | — | textarea 元素的 ID |
autofocus | boolean | — | 当值为 `true` 时，文本区域会自动获得焦点。 |
disabled | boolean | — | 当值为 `true` 时，禁止用户与文本区域进行交互。 |
maxlength | number | — | 文本区域中允许的最大字符数 |
minlength | number | — | 文本区域中允许的最小字符数 |
placeholder | string | — | 文本区域的占位符 |
readonly | boolean | — | 当值为 `true` 时，文本区域为只读。 |
name | string | — | 字段的名称。作为名称/值对的一部分，与其所属表单一同提交。 |
required | boolean | — | 当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。 |
事件
| 事件名 | 参数 | 描述 |
|---|---|---|
update:modelValue | string | 当模型值发生变化时触发。 |
clear | PointerEvent | 点击“清除”按钮时触发。 |
插槽
| 插槽名 | 参数 | 描述 |
|---|---|---|
clear | TextareaCompactSlotProps | 为“clear”槽位定制内容。 |
counter | TextareaCompactSlotProps | 计数器插槽的自定义内容。 |
footer | TextareaCompactSlotProps | 页脚位置的自定义内容。 |
TextareaControl
TextareaCounter
TextareaRoot
12 属性1 事件
属性
| 属性名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
defaultValue | string | — | textarea 的默认值 |
modelValue | string | — | textarea 控件的值 |
autosize | boolean | TextareaAutosizeOptions | — | 当值为 `true` 或为选项对象时，启用基于内容的自动调整大小功能 |
id | string | — | textarea 元素的 ID |
autofocus | boolean | — | 当值为 `true` 时，文本区域会自动获得焦点。 |
disabled | boolean | — | 当值为 `true` 时，禁止用户与文本区域进行交互。 |
maxlength | number | — | 文本区域中允许的最大字符数 |
minlength | number | — | 文本区域中允许的最小字符数 |
placeholder | string | — | 文本区域的占位符 |
readonly | boolean | — | 当值为 `true` 时，文本区域为只读。 |
name | string | — | 字段的名称。作为名称/值对的一部分，与其所属表单一同提交。 |
required | boolean | — | 当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。 |
事件
| 事件名 | 参数 | 描述 |
|---|---|---|
update:modelValue | string | 当模型值发生变化时触发。 |
注意事项
架构与对标差异
VeanUI 将文本域拆分为负责状态、自动高度测量与表单代理的 Aria 层（@vean/aria/textarea），以及负责变体与 UnoCSS 样式的 styled 层（@vean/ui）。Aria TextareaCompact 组合 TextareaRoot / TextareaControl / TextareaClear / TextareaCounter 并暴露 clear / counter / footer 插槽。这与 Radix 的 headless/styled 分离一致，区别于 Ant Design、Element Plus、Mantine 等单包方案。
| 能力 | VeanUI | Ant Design Input.TextArea | Element Plus Input | Mantine Textarea |
|---|---|---|---|---|
| Aria/styled 分离 | ✅ | — | — | — |
| 受控/非受控 | ✅ | ✅ | ✅ | ✅ |
| autosize（min/max 行） | ✅ | ✅ | ✅ | ✅ |
| 清除按钮（悬停显示） | ✅ | — | ✅ | — |
字符计数器 count/max | ✅ | ✅ | ✅ | — |
resize 控制 | ✅ | — | ✅ | ✅ |
| 原生表单代理 | ✅ | — | — | — |
footer 插槽 | ✅ | — | — | — |
error 态 | — | — | ✅ | ✅ |
注意事项
- autosize 依赖真实布局（
scrollHeight/getComputedStyle），相关行为通过浏览器 e2e 验证，而非 happy-dom 单测。 error态、loading态、showCount、IME 组合事件与change事件未实现，列为增强待办。- 计数器本身不做
aria-live播报；如需实时播报，可在counter插槽内自行添加aria-live区域。
常见问题
如何让文本域随内容自动增高？
传入 autosize（布尔值）或 autosizeOptions（含 minRows / maxRows）。高度会在输入时自动调整，到达 maxRows 后切换为 overflow-y: auto。
如何显示字符计数器？
传入 showCounter：配合 maxlength 显示 count / maxlength，不传 maxlength 则显示原始计数。可通过 counter 插槽自定义呈现。
如何控制缩放？
使用 resize 属性（none / vertical / horizontal）。autosize 启用时 resize 被忽略，因为高度由组件自动管理。
文本域如何参与原生表单提交？
传入 name 即可——组件会渲染一个携带当前值的视觉隐藏代理输入框，原生表单提交无需额外接线。