跳到主要内容

Textarea 多行输入

Textarea 固定 multiline,默认顶对齐;单行请用 Input。它与 Input 使用相同严格受控/非受控 union、slot、错误和 ref 契约。

contentAlignment="center" 按文字自然行高在最小输入区域内居中,用于聊天等紧凑输入。默认 start 保留顶对齐;两者都保留外层至少 44 的触达范围、多行增长、原文与最大高度内滚动,不强制文字行高。

plain 使用水平和垂直 space[3] 的文字留白,适合由外层绘制的聊天卡片;default 保留独立表面的水平 space[5]、垂直 space[4]。外层只提供布局和表面,不叠加相同文字内边距。

内容布局与消费交接​

输入表面(包括内部 padding 和边框)在 minHeight / maxHeight 范围内增长与缩短;错误说明在表面外,不占上限。首次长文、外部 value 更新、宽度与应用字号变化后,按真实内容重新测量;超过上限默认内部滚动,不截断文字。省略 maxHeight 可持续增长。

iOS 使用输入框实际宽度和同一字体/缩放策略的原生文字行独立测量,不依赖输入框固定高度后的内容尺寸事件;测量节点不可见且不进入可访问树,旧文本、宽度或字体的迟到结果不会应用到新内容。Android 保留自然测量,Web 保留 scrollHeight 测量。

受控清空通过外部 value 更新,ref 仍仅有 focus / blur。onFocus / onBlur 与 onContentSizeChange 原样交付;contentSize 是文字测量,组合区的总高度应由消费者自己的 onLayout 测量。页面负责键盘避让,回车可显式设置 submitBehavior="newline",发送与语音采集留在消费者。

用法​

<Textarea defaultValue="首次草稿" minHeight={120} maxHeight={240} />
<Textarea value={note} onChangeText={setNote} error={note ? undefined : '请输入备注'} />
<Textarea value={note} onChangeText={setNote} surface="plain" minHeight={44} maxHeight={120} />

defaultValue 只用于首次初始化;受控模式必须同时传 value 和 onChangeText,两种 mode 不能中途切换。

嵌入复合输入​

surface 可选 default(缺省)或 plain。default 绘制独立输入的玻璃背景、圆角、边框及焦点/错误描边;禁用只淡化前景。plain 用于外层卡片已经提供表面的复合输入,不绘制这些装饰;文字、焦点事件、错误说明、禁用状态及最小触达区域保持原契约。

default 使用水平 space[5]、垂直 space[4] 的文字内边距;plain 的水平和垂直内边距均为 space[3]。消费者不需要再给文字区叠加内边距。plain 没有边框,其垂直内边距合计为 2 * space[3]。minHeight/maxHeight 仍包含这些间距;例如消费者按四行文字计算 plain 的上限时,应将文字高度与这部分垂直间距相加。containerStyle 只作用于外层布局,不能用于穿透修改内部输入表面。

高度与 a11y​

  • minHeight 默认 96,必须是有限且至少 44 的数;非法值回退 96。
  • maxHeight 缺省时不限制;只有有限且不小于归一化后的 min 时生效,否则回退为无上限。
  • containerStyle 不能覆盖高度、min/max 尺寸、min/max 宽或 overflow,运行时 JS 传入也会剥除。
  • leading/trailing 只接受 TextFieldSlot。action slot 支持图标或文字,实际 frame 至少 44pt 宽、44pt 高,字段不可编辑时 action 也不可操作。
  • ref 是 TextFieldHandle,只有 focus() / blur();readOnly 改用 editable={false}。

错误文字 Android 使用 polite live region;iOS 只播报挂载后的非空错误变更。请给没有可见标签的字段传 accessibilityLabel。