Textarea
输入多行长文本。中文惯用名：多行输入框。
稳定本期新增已接入
元信息
| 字段 | 值 |
|---|---|
| 规范 ID | component.textarea |
| 名称 | Textarea |
| 二级分类 | 数据录入（data-entry） |
| 用途 | 输入多行长文本 |
| 描述 | 中文惯用名：多行输入框。 |
预览
静态结构：Textarea 为多行文本域（vendored shadcn Textarea，data-slot="textarea"），rows 显式指定行数、缺省由内容自适应。Form 内声明非空 name 时经 FieldShell 包裹——data-slot="form-item" 容器 + label（htmlFor 关联控件 useId）+ 文本域 + data-slot="form-error" 校验错误行；独立渲染时 className / style 直接挂文本域本体。
DSL 结构
{
"type": "Textarea",
"props": {
"name": "remark",
"label": "备注说明",
"rows": 3,
"placeholder": "请输入备注说明"
}
}何时用
何时使用
- 采集多行文本：备注、说明、描述、正文草稿。
- 需要固定行高的输入区（rows 指定行数），或由内容自适应高度的轻量文本域。
- Form 内的长文本字段：声明 name 即自动注册并参与校验。
何时不用
- 单行短文本：使用 Input；数值 / 日期 / 时间：使用 NumberInput / DatePicker / TimePicker。
- 多行中需要引用用户或对象（@ 提及）：使用 Mentions。
- 需要富文本格式（加粗、链接、图片）：Textarea 是纯文本域，改用富文本组件。
变体
| 变体 | 视觉形态 | 适用场景 |
|---|---|---|
| 默认（rows 自适应） | 多行描边文本域，高度随内容增长 | 行数不确定的描述类输入 |
| rows 固定行数 | 按 rows 指定初始高度 | 表单布局需要稳定高度（如固定 3 行备注） |
| Form 表单项 | FieldShell：label + 文本域 + 校验错误行 | 表单内长文本字段（声明 name 自动注册） |
| disabled 禁用 | 半透明不可输入 | 只读回显、流程未就绪 |
API 属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
name | string | — | 字段名；在 Form 内声明即自动成为表单项 |
label | string | — | 表单项标签（FieldShell 呈现） |
rules | FieldRule[] | — | 校验规则 |
value | string | — | 受控值（独立渲染时生效）；Form 内作为字段初始值（优先于 Form initialValues） |
placeholder | string | — | 空态提示文案 |
rows | number | — | 行数；缺省由内容自适应 |
disabled | boolean | false | 禁用输入 |
onChange | (value: string) => void | — | 输入事件，传出 string（Renderer 绑定 events.onChange；非原生 event） |
className / style | string / CSSProperties | — | 通用：根节点 class 合并 / 内联样式（Form 内为 form-item 容器，独立渲染时为文本域本身） |
使用规范
- 多行纯文本专用；需要格式、链接或图文混排时换富文本组件，不用 Textarea 硬扛。
- rows 只定初始高度，浏览器仍可拖拽调整；需要稳定布局时同时约束容器宽度并确认换行表现。
- 长文本字段配 rules 做必填与长度校验，避免纯前端截断造成静默丢字。
- Form 内声明非空 name 才会注册字段；未声明 name 时仅为受控文本域，值不进表单 values。
- placeholder 给填写提示（如「请描述问题现象与复现步骤」），承载实际约束信息而非重复 label。
正例
- ✓ 工单表单：rows={4} 的「问题描述」字段，name + rules 必填，校验失败在下方提示。
- ✓ 审核意见：rows={3} 的备注输入，onChange 回写受控 state 并实时统计字数。
- ✓ 只读回显：disabled 展示已提交的备注内容，与编辑态视觉区分。
反例
- ✕ 用 Textarea 采集单行字段（如姓名、编号），占用垂直空间且无必要（应使用 Input）。
- ✕ 在 Textarea 中期待 @ 提及候选浮层（应使用 Mentions）。
- ✕ 把长文本存进 Input 后靠 CSS 拉高伪装多行输入。
Design Token 映射
不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。