掩码与键盘

字段的 EditMode 同时控制两件事：格式化（掩码）和打开的键盘。它是结构化输入的 核心部件。

EditMode → 键盘

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

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());

      // 日期字段：启用掩码后点击会打开 DatePicker
      TextField data = new TextField().caption("Data");
      data.setMode(EditMode.DATE, true);      // maskedEdit=true → 格式化并打开 DatePicker
      add(LAY_AUTO, data);

      // 货币字段：输入时格式化为货币
      TextField valor = new TextField().caption("Valor");
      valor.setMode(EditMode.CURRENCY, true);
      valor.<TextFieldStyle>getStyle().decimalPlaces(2);
      add(LAY_AUTO, valor);

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

      // 没有按键回调：在提交时读取 getText()。
      // getTextWithoutMask() 只返回数字（适合存入数据库）。
      Button enviar = new Button("Enviar");
      enviar.onAction(c -> resultado.setText(
         "Data = " + data.getText() + "  |  Valor = " + valor.getTextWithoutMask()));
      add(LAY_AUTO, enviar);
   }
}

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

启用自动掩码

setMode(mode, true) 开启实时格式化（maskedEdit）：

TextField data = new TextField().caption("Data");
data.setMode(EditMode.DATE, true);         // 输入时变为 15/03/2024 并打开 DatePicker

TextField valor = new TextField().caption("Valor");
valor.setMode(EditMode.CURRENCY, true);    // 输入时格式化为货币
valor.<TextFieldStyle>getStyle().decimalPlaces(2);

自定义掩码（'9' 表示数字位）

在掩码中，每个 '9' 是一个数字位；其余字符为固定的字面量：

TextField cpf = new TextField().caption("CPF");
cpf.<TextFieldStyle>getStyle()
   .mask("999.999.999-99".toCharArray())    // 11 位数字 + 分隔符
   .mode(EditMode.NUMERIC, true);
// getText()          -> "123.456.789-00"  （带掩码）
// getTextWithoutMask()-> "12345678900"    （仅数字）

现成的货币：TextField.getDefaultCurrencyMask(int casasDecimais) 使用 locale 的千位/小数 分隔符生成掩码。

显式选择键盘

campo.keyboard(Keyboard.NUMERIC);   // 强制数字
campo.keyboard(Keyboard.NONE);      // 从不弹出键盘（视觉上的只读字段）

Keyboard（在 UIConstants 中）：NONE, DEFAULT, NUMERIC, KEYPAD, CALCULATOR, DATE, TIME。DEFAULT 采用当前 EditMode 隐含的键盘。

内置 Keypad

Keyboard.KEYPAD/CALCULATOR 使用 CrossFly 自身的 Keypad 组件（而非操作系统的键盘）——在 自助终端/POS 中很有用。它由字段自动打开；如需单独使用：

new Keypad(meuCampo).show();        // 字段启用数字键盘

最佳实践

• 在数据库中保存 getTextWithoutMask()（原始数字）；显示时带掩码。
• 对于证件（CPF、CEP、电话），将 mask(...) 与 mode(EditMode.NUMERIC, true) 结合使用。
• 在桌面上，NUMERIC 会自动回退到 Keypad——不要假设使用原生键盘。

常见错误

• 开启 mode(EditMode.DATE) 但不带 maskedEdit=true → 无自动格式化。
• 当后端只需要数字时持久化 getText()（带点/破折号）。
• 掩码中没有任何 '9' → 不接受任何数字。

另见

• 文本字段 · 目录：DatePicker · TimePicker · Keypad