文本输入框

用于在一行中输入任意文本、数字和符号值的组件。可用于页面表单和对话框，以及登录、搜索和筛选表单。

§应用

与 TextArea 不同，它在输入过程中不会改变高度，用于输入任意字母、数字或符号组合的简单自由格式数据。

当输入的文本超出字段宽度时，可以左右滚动内容。

✅ 何时使用

1. 当只需要单行文本时。
2. 当无法从预定列表中选择选项时。
3. 当有足够的空间进行数据输入，且不需要更复杂的输入界面时。

🚫 何时不使用

1. 当参数只能从预定列表中输入时，这可能会导致错误。为此，请考虑使用具有特定值选项选择的其他组件，例如 Select、Radio Button、Radio 和 Checkbox。
2. 当必须输入大量字符时（超过 5 个单词）。为此，我们建议使用 TextArea，这是一个用于多行文本输入的组件。

§类型

TextInput 有两种类型：Normal 和 Clear，它们具有相同的功能集，但根据上下文的外观和用法不同。

Normal

• 最常用的类型。
• 此组件的显著特点是其内部填充和圆角。这些参数由元素的大小和 1px 的描边决定。
• 在表单中使用，当组件之间需要有自由空间时，例如表单元素之间的填充。

Clear

• 此组件的定义特征是缺少边框，元素位于输入字段的边距内。
• 当 Normal 类型会产生视觉干扰时使用。
• 使用此类型时，请确保此组件的目的对用户来说是清晰的。

§结构

1. 左侧图标

• 是一个可选组件。
• 图标可用于额外的字段标识。
• 例如，如果这是一个搜索字符串，可以使用“放大镜”图标。如果这是一个密码输入字段，则可以使用“钥匙”图标。

2. 行内标签

• 是一个可选组件。
• 增强字段名称的价值。
• 取代外部标签。
• 用作字段名称，因为输入值后，提示会消失，导致字段的目的对用户不明确。

3. 值

• 是必需元素。
• 用于提示文本和输入文本的空间。
• 输入一个字符后，输入文本将替换提示。

4. 清除按钮

• 是一个可选组件。
• 当需要清除字段内容时使用。
• 当字段中至少输入一个字符时显示。
• 即使焦点不在字段上时也显示。
• 是一个 Flat-secondary 类型的 Button 组件，继承了其所有属性。例如，鼠标悬停时，十字的背景会填充。
• 单击清除按钮时，焦点会移至字段，并且输入的文本会被清除。

5. 行内按钮

• 是一个可选元素，嵌入在右侧。
• 用于更清晰地指示内容与操作之间的关系，并可以放置在组件内。
• 该字段最多允许两个 Button 组件。
• 嵌入式按钮的大小应比组件自身的大小小一个级别。例如，如果使用 S 尺寸，按钮应为 XS；如果使用 M 尺寸，按钮应为 S；依此类推。
• 例如，可用于确认操作、发送消息或为字段添加其他筛选器。

6. 附加内容

• 是一个可选元素，嵌入在右侧。
• 当需要内部附加文本时使用。
• 文本右对齐。
• 例如，可用作计数器（已输入字符的计数器）、用于计算搜索字符串中找到的值的数量，或用于测量单位。

7. 错误图标

• 仅在 Inline Error 状态下显示。
• 与 Tooltip 配合使用，在鼠标悬停在图标上时提供错误描述，以实现表单的紧凑布局。

8. 错误描述

• 仅在 Outline Error 状态下显示。
• 嵌入在左下角。

§状态

具有以下状态：Suggest、Default、Hover、Active、Disabled、Inline Error 和 Outline Error。

1. Suggest。 当与组件没有直接交互且未输入数据时的非活动状态。在此状态下，值可以作为提示，指示用户应该在字段中输入什么类型的信息。
2. Default。 当与组件没有直接交互且已输入数据时的非活动状态。在此状态下，提示值会根据用户的输入而变化。
3. Hover。 当鼠标光标悬停在组件区域上时的活动状态。
4. Active。 通过从上一个组件切换或单击鼠标触发的活动状态。当切换到其他组件或单击空白区域时，该状态会重置。
5. Disabled。 组件无法交互时的非活动状态。
6. Outline error。 当验证过程中发生错误时组件的活动状态，并在字段底部显示错误及其说明。
7. Inline error。 当字段验证发生错误时组件的活动状态，但错误不显示。相反，错误由一个特殊图标表示，鼠标悬停在该图标上时会显示一个错误 Tooltip。

§尺寸

该组件有四种尺寸：S、M、L 和 XL。

字段的高度和圆角，以及字段内部的填充和文本大小，会根据组件的大小而变化。

圆角取决于大小，并由 variables 设置。

1. S (-g-border-radius-s: 5px;) – 当标准输入过大时使用（例如，表格、小卡片）。
2. M (-g-border-radius-m: 6px;) – 基本尺寸，在大多数表单和筛选器中使用。
3. L (-g-border-radius-l: 8px;) – 用于搜索（例如，服务搜索）。
4. XL (-g-border-radius-xl: 10px;) – 在通信环境中使用（例如，网站和登陆页面）。

§用户指南

1. 使用字段

• 字段只能包含一行。为此，我们建议使用 TextArea，这是一个用于多行文本输入的组件。
• 我们不建议在字段中包含 提示，因为输入值后字段名称将不可见，除非空间有限或字段的目的对用户来说很清楚。
• 字段的宽度必须与输入值的宽度相同。它会告知用户预期的输入。
• 对表单的所有补充组件使用 相同的尺寸。如果您选择了 M 尺寸，所有其他组件也应为相同尺寸。

2. 外部字段标题

• 字段名称应简短，最好限制在一行内。
• 在桌面表单中，组件应与字段值对齐放置。如果是在移动端或 Dialog 尺寸为 S 的情况下，组件的标题将显示在组件上方。

3. 带有工具提示的提示信息

• 当鼠标悬停在带问号的图标上时，显示填写字段的说明。
• 当标题需要进一步解释时使用。
• 不应包含超过两段文字。

4. 附加说明

• 可以位于字段的下方或右侧。
• 在极少数情况下使用，当不清楚如何填写字段而需要附加说明时，或者需要解释已输入的值时。

5. 测量单位 可以按以下方式放置：

• 在字段的文本描述中，如果表单空间充足。
• 在输入字段内，如果描述需要缩短。
• 在字段的右侧，如果字段内部需要为其他元素（如按钮或清除（重置）图标）腾出空间。