跳至主要内容

TextField

在 ChatGPT 中打开
阴影 dwc-field 23.02
Java API

TextField组件允许用户在单行中输入和编辑文本。您可以配置字段以显示特定的虚拟键盘，例如数字键盘、电子邮件输入、电话输入或URL输入。该组件还提供内置验证，以拒绝不符合指定类型的值。

用法​

Inheritance

This class is a Field component, and inherits its features and behaviors. For an overview of Field properties, events, and other important information, please refer to the Field documentation.

TextField适用于需要文本输入或编辑的广泛场景。这是一些使用TextField的例子：

  1. 表单输入：TextField通常用于表单中以捕获用户输入，例如姓名、地址或评论。当输入一般较短，适合在一行中显示时，最好在应用中使用TextField。

  2. 搜索功能：TextField可以用于提供搜索框，允许用户输入搜索查询。

  3. 文本编辑：TextField非常适合需要文本编辑或内容创作的应用，例如文档编辑器、聊天应用或记事本应用。

类型​

您可以使用setType()方法指定TextField的类型。同样，您可以使用getType()方法检索该类型，该方法将返回一个枚举值。

  • Type.TEXT: 这是TextField的默认类型，自动从输入值中删除换行符。

  • Type.EMAIL: 此类型用于输入电子邮件地址。它根据标准的电子邮件语法对输入进行验证。此外，提供兼容的浏览器和设备动态键盘，以简化输入过程，并包含常用的键，例如.com和@。

    笔记

    虽然此验证确认了电子邮件地址的格式，但并不能保证该电子邮件存在。

  • Type.TEL: 此类型用于输入电话号码。该字段将在一些具有动态键盘的设备上显示电话键盘。

  • Type.URL: 此类型用于输入URL。它验证用户输入的URL是否包含方案和域名，例如：https://webforj.com。此外，它为兼容的浏览器和设备提供动态键盘，以简化输入过程，并包含常用的键，例如:、/和.com。

  • Type.SEARCH: 用于输入搜索字符串的单行文本字段。换行符会自动从输入值中删除。

显示代码

字段值​

TextField的值表示当前用户输入的字符串。在webforJ中，可以使用getValue()方法访问该值，或使用setValue(String)方法以编程方式更新。

//设置初始内容
textField.setValue("初始内容");

//检索当前值
String text = textField.getValue();

如果在没有当前值的字段上使用getValue()方法，则返回一个空字符串（""）。

此行为与HTML <input type="text">元素通过JavaScript暴露其值的方式一致。

结合值处理与验证

应用如模式、最小长度或最大长度等约束，以定义何时认为值是有效的。

占位符文本​

您可以使用setPlaceholder()方法为TextField设置占位符文本。当字段为空时，占位符文本会显示，帮助提示用户在TextField中输入适当的内容。

选定文本​

可以与TextField类交互以检索用户选择的文本，并获取有关用户选择的信息。您可以使用getSelectedText()方法检索TextField中的选定文本。此行为通常与事件一起使用。

TextField textField = new TextField("输入内容...");
Button getSelectionBtn = new Button("获取选定文本");

getSelectionBtn.onClick(e -> {
  String selected = textField.getSelectedText();
  System.out.println("选定文本: " + selected);
});

同样，您可以使用getSelectionRange()方法检索TextField的当前选择范围。这将返回一个SelectionRange对象，表示选定文本的起始和结束索引。

使用getSelectedText()与事件负载

虽然您可以在事件处理程序中手动调用getSelectedText()，但使用事件负载中提供的选择数据（例如在SelectionChangeEvent中）更为高效，以避免额外的查找。

模式匹配​

您可以使用setPattern()方法使用正则表达式定义TextField的验证规则。设置模式会添加约束验证，要求输入值匹配指定的模式。

模式必须是有效的JavaScript正则表达式，由浏览器解释。u（Unicode）标志在内部应用，以确保Unicode代码点的准确匹配。不要将模式用斜杠（/）包裹，因为这不是必需的，并将被视为文字字符。

textField.setPattern("[A-Za-z]{3}\\d{2}"); // 例如ABC12

如果未提供模式或语法无效，则将忽略验证规则。

上下文帮助

在为TextField使用复杂模式时，考虑结合使用setLabel()、setHelperText()和setTooltipText()方法，以提供额外的提示和指导。

最小和最大长度​

TextField组件支持基于用户输入的字符数量的约束验证。这可以使用setMinLength()和setMaxLength()方法进行控制。使用这两种方法定义明确的可接受输入长度边界。

长度要求

默认情况下，当输入值超出范围时，该字段会显示消息，指示用户是否需要缩短或延长其输入。此消息可以使用setInvalidMessage()方法覆盖。

setMinLength()​

此方法设置字段被视为有效所需输入的最小UTF-16代码单元数量。值必须是整数，并且不得超过配置的最大长度。

textField.setMinLength(5); // 用户必须输入至少5个字符

如果输入的字符少于所需的最小数量，则输入将失败约束验证。此规则仅在用户更改字段值时适用。

setMaxLength()​

此方法设置文本字段中允许的最大UTF-16代码单元数量。值必须是0或更大。如果未设置或设置为无效值，则不强制执行最大长度。

textField.setMaxLength(20); // 用户不能输入超过20个字符

如果输入长度超过最小长度，则字段将失败约束验证。与setMinLength()一样，此验证仅在用户更改值时触发。

最佳实践​

以下部分概述了使用TextField的一些建议最佳实践。

  • 提供清晰的标签和说明：清晰地标记TextField以指示用户应输入的信息类型。提供额外的说明文本或占位符值，以引导用户并设定对所需输入的期望。

  • 拼写检查和自动完成：在适用的情况下，考虑使用setSpellCheck()实现拼写检查和/或在TextField中使用自动完成功能。这些功能可以帮助用户更快地输入信息，并通过提供基于先前输入或预定义选项的建议值来减少错误。

  • 可访问性：在考虑可访问性的情况下使用TextField组件，遵循诸如适当标记、键盘导航支持和与辅助技术的兼容性等可访问性标准。确保有障碍的用户可以有效地与TextField进行交互。