跳到内容
CrossFly 是 100% 开源在 GitHub 关注我们
CrossFlyCrossFly
开始使用

本页面由葡萄牙语机器翻译，可能存在错误。葡萄牙语版本为准。

TextField

TextField 是单行文本输入。在基类 TextInput 之上，它增加了：掩码引擎（日期、货币、自定义）、密码模式（带显示/隐藏切换）、可点击的左/右图标、水平滚动和一个可选的浮动 caption。输入行为由 EditMode（NORMAL/DATE/CURRENCY/NUMERIC/TIME/PASSWORD）定义，它同时也选择默认键盘。

🟡 · 包： dev.crossfly.ui · 继承： TextInput · 样式： TextFieldStyle（default 与 focused 各异）

何时使用

  • 任何单行输入：姓名、邮箱、密码、数字/货币值、日期、时间。
  • 带掩码的字段（邮编、电话、日期）或带可点击图标的字段（清除、搜索、密码眼睛）。

何时不使用

  • 多行文本（备注、评论）→ 使用 TextArea。
  • 从固定选项中选择 → 使用 Dropdown / Option（见 ui/）。

外观

带有 TextFieldStyle 背景/边框的框，文本在一行内，两端有可选图标，以及可选的一个浮动 caption（floatingCaption），当有焦点或内容时它会上升到字段上方。

``

完整示例（复制、粘贴并运行）

package com.exemplo;

import dev.crossfly.ui.*;
import dev.crossfly.ui.layout.*;

/** 可执行的主界面。将 launcher 指向此类（classname）并运行：gradlew :lwjgl3:run */
public class MainWindow extends Window
{
   @Override
   public void onShow() throws Exception
   {
      super.onShow();
      setLayout(new VerticalLayout());

      // 带浮动 caption 的单行字段
      TextField nome = new TextField().caption("Nome");
      add(LAY_AUTO, nome);

      // 输出 Label
      Label saida = new Label("Digite seu nome e toque em Enviar");
      add(LAY_AUTO, saida);

      // 没有按键 onChange 事件：在提交时读取 getText()
      Button enviar = new Button("Enviar")
         .onAction(c -> saida.setText("Olá, " + nome.getText() + "!"));
      add(LAY_AUTO, enviar);
   }
}

下面的片段只展示核心部分（放入 onShow() 内的内容）。要运行它们，请将它们放入上面的 MainWindow 骨架中。

基本用法

TextField nome = new TextField().caption("Nome");
container.add(LAY_AUTO, nome);
// ...
String valor = nome.getText();

构造函数

构造函数 描述
TextField() 空
TextField(String text) 带初始文本（null = 空）

EditMode（编辑模式）

EditMode 默认键盘 备注
NORMAL DEFAULT 普通文本；可带自定义掩码
DATE DATE 打开 DatePicker；日期掩码
CURRENCY CALCULATOR 货币/小数，掩码从右到左
NUMERIC NUMERIC 数字（桌面端回退到 KEYPAD）
TIME TIME 打开 TimePicker
PASSWORD DEFAULT 用 passwordChar 代替字符显示

setMode(mode) 或 setMode(mode, maskedEdit) 设置模式；maskedEdit=true 启用按掩码的自动格式化。

属性与自定义

属性 / 方法 类型 默认值 作用
text(String) / setText(String) TextField / void — 设置文本（规范化掩码/货币；光标置于末尾）
getText() String — 显示的文本（含掩码，若启用）
getTextWithoutMask() String — “干净”值（仅数字 / 格式化小数）
caption(String) TextField（流式） null 浮动 caption / 占位符
setMode(EditMode[, boolean]) void NORMAL 编辑模式（+ 掩码）
keyboard(Keyboard) / setKeyboard(Keyboard) TextField / void 按 EditMode 键盘类型
leftIcon(Icon[, Action]) / rightIcon(Icon[, Action]) TextField（流式） null 图标（带可选动作）
leftIconAction(Action) / rightIconAction(Action) TextField（流式） — 图标动作（单独设置）
isPassword() boolean — 是否处于密码模式？
clearText() void — 清除文本、掩码和缓存
样式 .mask(String) char[] — 掩码（9=数字，其余为字面量）："99/99/9999"
样式 .validChars(String) String null 允许的字符
样式 .maxLength(int) int 0（无限制） 字符数限制
样式 .passwordToggle(true) boolean false 创建显示/隐藏的“眼睛”图标
样式 .floatingCaption(true) boolean — 聚焦/填充时 caption 上升
getDefaultCurrencyMask(int) (static) char[] — 货币掩码（LocaleFormats 的分隔符）

回调与事件

回调 何时触发
onAction(Action)（继承） 在 onTouchUp，打开键盘之后
onFocus() / onBlur()（继承） 获得 / 失去焦点
leftIconAction / rightIconAction 触摸（并松开于）对应图标时

没有专门的 onChange —— 通过动作作出反应或查询 getText()/getTextWithoutMask()。

状态

  • focused： 样式 textFieldFocused(...)，光标闪烁，触摸时打开键盘/picker；若 floatingCaption 则 caption 上升。
  • password： 有了 passwordToggle，右侧图标在 PASSWORD↔NORMAL（显示/隐藏）之间切换，更新 default 和 focused 样式。
  • disabled / read-only： setEnabled(false) 或 editable=false 阻止编辑。

带显示/隐藏切换的密码字段

TextField senha = new TextField().caption("Senha");
senha.setMode(EditMode.PASSWORD);
senha.style(Styles.theme()
   .field(FieldRole.PASSWORD, State.NORMAL)
   .passwordToggle(true));   // 自动创建 "眼睛" 图标
container.add(LAY_AUTO, senha);

带掩码 + DatePicker 的日期

TextField data = new TextField().caption("Data");
data.setMode(EditMode.DATE, true);          // maskedEdit = true
data.style(Styles.theme()
   .field(FieldRole.NORMAL, State.NORMAL)
   .mask("99/99/9999"));
// 点击打开 DatePicker；选择后字段被填充。
container.add(LAY_AUTO, data);

带验证和清除图标的邮编

TextField cep = new TextField().caption("CEP");
cep.style(Styles.theme()
   .field(FieldRole.NORMAL, State.NORMAL)
   .mask("99999-999")
   .validChars("0123456789"));
cep.rightIcon(new MaterialIcon(""), c -> cep.clearText());  // "close"
container.add(LAY_AUTO, cep);

String limpo = cep.getTextWithoutMask();   // 仅 8 位数字

最佳实践

  • 对于掩码，启用 maskedEdit（setMode(mode, true)）并在样式中定义 mask —— 只定义掩码而不启用 maskedEdit 不会自动格式化。
  • 持久化/验证时使用 getTextWithoutMask()（干净的数字），显示时使用 getText()。
  • 优先使用正确的 EditMode/Keyboard，以便为每个字段打开理想的键盘。

常见错误

  • 定义了 mask 但忘记 maskedEdit： 文本不会被格式化。使用 setMode(mode, true)。
  • 读取 getText() 期待干净的数字： 它返回的是含分隔符的；使用 getTextWithoutMask()。
  • 没有密码模式却用 passwordToggle： toggle 默认已隐含密码，但请确认 EditMode.PASSWORD / FieldRole.PASSWORD 以获得正确的视觉效果。

另见

这个页面有帮助吗？