文本框:指南
文本框让用户可以在 UI 中输入文本。

用法
当用户需要在 UI 中输入文本时(例如填写联系信息或支付信息),请使用文本框。

文本框有两种变体:
- 填充式文本框
- 描边式文本框
两种变体都通过容器提供交互的视觉提示,并具备相同的功能。


描边式文本框
描边式文本框的视觉突出程度低于填充式文本框。当多个文本框一起出现在表单等位置时,较低的视觉突出度有助于简化布局。

选择文本框
选择文本框
两种文本框变体功能相同,选择哪种可仅依据样式决定。
选择符合以下条件的变体:
- 与应用的视觉风格最契合
- 最能满足 UI 的设计目标
- 与其他组件(如按钮)及周围内容区分最明显


在同一屏幕上使用两种文本框变体
如果 UI 中同时使用两种文本框变体,应在不同区域分别保持一致使用,不要在同一区域内混用。
例如,在一个区域使用描边式文本框,在另一个区域使用填充式文本框。


结构
填充式文本框

- 容器
- 前导图标(可选)
- 字段为空时的标签文本
- 字段已输入内容时的标签文本
- 尾部图标(可选)
- 聚焦状态的活动指示器
- 光标
- 输入文本
- 辅助文本(可选)
- 启用状态的活动指示器
描边式文本框

- 启用状态的容器轮廓
- 字段为空时的标签文本
- 前导图标(可选)
- 字段已输入内容时的标签文本
- 尾部图标(可选)
- 聚焦状态的容器轮廓
- 光标
- 输入文本
- 辅助文本(可选)
容器
容器通过形成文本框与周围内容的对比,让文本框更容易被识别。
填充和描边
文本框容器带有填充和描边,描边可环绕整个容器,也可仅位于底部边缘。描边的颜色和粗细会变化,以表示文本框是否处于活动状态。
圆角
描边式文本框的容器为圆角,而填充式文本框的容器顶部为圆角、底部为直角。

标签文本
标签文本说明用户需要提供什么信息。每个文本框都应有标签。
标签文本应与输入文本对齐并始终可见,可位于文本框中部或靠近容器顶部。
标签文本应简短、清晰且完整可见,不应被截断,也不应占据多行。


相邻标签
如果已有独立的相邻标签说明字段用途,文本框内可不再显示标签。
相邻标签应与文本框容器的前置边对齐。

必填文本指示器
如需表明字段为必填项,请在标签文本旁显示星号(*),并通过以下任一方式说明星号表示必填字段:
- 辅助文本
- 表单开头的一条说明
其他最佳实践包括:
- 标出所有必填字段
- 若必填项文本使用特定颜色,星号也应使用相同颜色

输入文本
输入文本即用户在文本框中输入的文本。
文本框可通过以下方式显示输入文本:
- 单行文本框仅显示一行文本
- 多行文本框会扩展以容纳多行文本
- 文本区域是高度固定的字段

前缀文本
文本框可包含前缀文本,例如货币符号。

后缀文本
文本框可包含后缀文本,例如计量单位或电子邮件域名。


辅助文本与字符计数器
辅助文本用于传达与输入字段相关的附加信息,例如它将如何使用。理想情况下为一行,必要时可换行显示。辅助文本可以始终可见,也可仅在聚焦时可见。
如果存在字符数或单词数限制,请提供字符计数器或单词计数器。计数器显示已用字符数(或单词数)与上限的比值。

- 辅助文本
- 字符计数器
错误文本
对于需要验证内容的文本框(例如密码字段),请用错误文本替换辅助文本,以避免新增文本行挤压内容或改变布局。
- 若只可能出现一种错误,错误文本应说明如何避免该错误
- 若可能出现多种错误,错误文本应说明如何避免最可能发生的错误

错误图标
强烈建议在文本框处于错误状态时显示错误图标。
这有助于视障用户发现错误,并提供额外的感知提示。

图标与图像
文本框中的图标为可选项。文本框图标可以:
- 说明有效的输入方式,例如麦克风图标
- 提供访问附加功能的交互入口,例如清除字段内容
- 提示错误
前导图标和尾部图标会根据从左到右(LTR)或从右到左(RTL)的书写方向改变位置。
高度为 24dp 的图像可放置在文本框内部。该高度可确保字段顶部和底部内边距效果最佳,并与图标尺寸建议保持一致。
- 图标指示符
图标指示符可说明文本框所需的输入类型,并可充当嵌套组件的触控目标。例如,点击日历图标可显示日期选择器。 - 有效或错误图标
图标可指示正确和错误的输入,使色盲用户也能清楚了解错误状态。 - 清除图标
清除图标让用户可清除整个输入字段,仅在存在输入文本时显示。 - 语音输入图标
麦克风图标表示用户可通过语音输入字符。 - 下拉图标
下拉箭头表示文本框内嵌了选择组件。 - 图像
图像有助于说明需要输入的文本内容,例如信用卡号。

- 图标指示符
- 有效或错误图标
- 清除图标
- 语音输入图标
- 下拉图标
- 图像
只读字段
只读文本框显示用户无法编辑的预填充文本。
只读文本框的样式与常规文本框相同,并明确标记为只读。


自适应设计
当布局适应更大的屏幕和不同的断点时,应为文本框设置灵活的容器尺寸。随着布局缩放,应为边距、内边距和容器尺寸设置最小值和最大值,使字体排印进行调整,以获得更好的阅读体验。

当文本框在流式布局中扩展时,应避免使用固定边距和字体排印属性,否则可能导致文本框过长。
例如,文本框不应占据大屏幕的整个宽度。

密度
密集文本框可帮助用户快速浏览大量信息并执行操作。

避免默认应用密度
不要默认对文本框应用密度,否则其触控目标会小于建议的 48×48 CSS 像素。应为用户提供选择更高密度的方式,例如选择更密集的布局或更改主题。
为确保启用该密度设置后可以轻松还原,请将所有用于切换该设置的触控目标保持在至少 48×48 CSS 像素。