焦点与验证

由于不存在按键事件，CrossFly 中的验证在提交时（或失去焦点时）进行：你读取 getText()，做出判断，并标示错误。

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

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");
      add(LAY_AUTO, nome);

      TextField email = new TextField().caption("E-mail");
      add(LAY_AUTO, email);

      // 只读字段：显示值，点击时不弹出键盘也不聚焦
      TextField codigo = new TextField("ABC-123").caption("Código");
      codigo.<TextFieldStyle>getStyle().editable(false);
      add(LAY_AUTO, codigo);

      // 校验在提交时进行（没有按键事件）：
      // 空字段 → Hint.show(...) + 将焦点返回到出错字段。
      Button enviar = new Button("Cadastrar");
      enviar.onAction(c -> {
         String n = nome.getText().trim();
         String e = email.getText().trim();
         if (n.isEmpty())         { Hint.show("Informe o nome", 2000);  nome.setFocused(true);  return; }
         if (e.indexOf('@') < 0)  { Hint.show("E-mail inválido", 2000); email.setFocused(true); return; }
         Hint.show("Cadastrado: " + n, 2000);
      });
      add(LAY_AUTO, enviar);
   }
}

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

焦点

属性（样式）/ 方法	效果
`focusOnTouch`（样式）	点击字段获得焦点（字段样式的默认行为）
`focusOnKey`（样式）	在父级聚焦时按键将焦点移到字段
`onFocus()` / `onBlur()`	获得 / 失去焦点时调用的钩子（在子类中重写）
`hasFocus()`	查询字段是否已聚焦
`restoreFocusAtEnd()`	将光标重新定位到末尾（通过选择器填写后）

// 只读字段（显示值，点击时不弹出键盘也不聚焦）：
saldo.<TextFieldStyle>getStyle().editable(false);

输入限制

telefone.<TextFieldStyle>getStyle()
   .maxLength(11)                    // 最多 11 个字符
   .capitalise(Capitalise.UPPER);   // 强制大写（Capitalise: NORMAL/UPPER/LOWER）

提交时验证（推荐模式）

Button enviar = new Button("Cadastrar");
enviar.onAction(c -> {
   String nome  = nomeField.getText().trim();
   String email = emailField.getText().trim();
   if (nome.isEmpty()) { Hint.show("Informe o nome", 2000); nomeField.setFocused(true); return; }
   if (email.indexOf('@') < 0) { Hint.show("E-mail inválido", 2000); emailField.setFocused(true); return; }
   salvar(nome, email);
});

Hint.show(...) 用于非阻塞式提示；Alert 用于确认（参见对话框与模态框）。
将焦点返回到出错的字段，以便用户更正。

最佳实践

通过读取 getText()/getTextWithoutMask() 在提交时验证——不要试图拦截每次按键。
对于计算/派生字段使用 editable(false)，而不是“禁用并强制只读”。
在源头限制输入（mask、maxLength、EditMode.NUMERIC）以减少验证。

常见错误

寻找按键变化的监听器——它不存在；请在提交时/离开字段时验证。
忘记将焦点返回到无效字段，导致用户不知所措。
当规则是关于数字时验证 getText()（带掩码）→ 使用 getTextWithoutMask()。

另见

文本字段 · 掩码与键盘 · 对话框与模态框