跳至主要内容

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：此类型用于输入URLs。它验证用户输入的URL是否包括方案和域名，例如： https://webforj.com。此外，它为兼容的浏览器和设备提供动态键盘，从而简化输入过程，包含常用的键，如 :、/ 和 .com。

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

显示代码

字段值​

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

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

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

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

这种行为与如何通过 JavaScript 曝露 HTML <input type="text"> 元素的值是一致的。

结合值处理与验证

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

占位符文本​

您可以使用 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 交互。