文本字段（TextField）

TextField 是单行字段。基础功能使用流式 API；精细行为来自 TextFieldStyle。

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

package com.exemplo;

import dev.crossfly.ui.*;
import dev.crossfly.ui.layout.*;
import dev.crossfly.ui.style.*;   // TextFieldStyle（行为配置）

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

      // 带浮动标签的姓名字段
      TextField nome = new TextField().caption("Nome");
      nome.<TextFieldStyle>getStyle().floatingCaption(true);
      add(LAY_AUTO, nome);

      // 带显示/隐藏按钮的密码字段
      TextField senha = new TextField().caption("Senha");
      senha.<TextFieldStyle>getStyle()
         .mode(EditMode.PASSWORD)
         .passwordToggle(true);
      add(LAY_AUTO, senha);

      // 用于显示读取值的标签
      Label resultado = new Label("");
      add(LAY_AUTO, resultado);

      // 没有按键回调：在提交时读取 getText()
      Button enviar = new Button("Enviar");
      enviar.onAction(c -> resultado.setText("Nome = " + nome.getText()));
      add(LAY_AUTO, enviar);
   }
}

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

基本用法

TextField nome = new TextField()
   .caption("Nome")                 // 浮动标签
   .text("");                       // 初始值
painel.add(LAY_AUTO, nome);

// 需要时读取值（没有按键事件）：
Button enviar = new Button("Enviar");
enviar.onAction(c -> Debug.log("Nome = " + nome.getText()));

构造函数与流式 API

浮动标题

在样式中启用（floatingCaption）——标题在聚焦/填写时上移：

TextField email = new TextField().caption("E-mail");
email.<TextFieldStyle>getStyle().floatingCaption(true);

带显示/隐藏按钮的密码框

TextField senha = new TextField().caption("Senha");
senha.<TextFieldStyle>getStyle()
   .mode(EditMode.PASSWORD)     // 遮蔽字符
   .passwordToggle(true);       // 自动添加眼睛图标

使用 passwordToggle(true) 时，右侧图标会自动切换可见性。

操作图标（如清空）

TextField busca = new TextField().caption("Buscar")
   .rightIcon(new MaterialIcon(""), c -> busca.clearText());  // "close"

最佳实践

• 在提交时用 getText() 读取值；对于原始数字，使用 getTextWithoutMask()。
• 通过类型化的 getStyle()（campo.<TextFieldStyle>getStyle()...）配置行为 （mode、maxLength、floatingCaption）。
• 在有意义时用样式中的 .maxLength(n) 限制长度。

常见错误

• 寻找 onChange/onTextChanged——它不存在；需要时读取 getText()。
• 在保存到数据库时混淆 getText()（带掩码）和 getTextWithoutMask()（不带掩码）。
• 在组件上设置 mode/mask——它们是样式的 setter。

另见

• 掩码与键盘 · 焦点与验证 · 文本区域
• 目录：TextField · 参考：第 14 章