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

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

TextInput

TextInput 是抽象类，它集中了 TextField（单行）和 TextArea（多行）之间共享的所有编辑逻辑：光标、选择、剪贴板、焦点/闪烁、键盘快捷键、方向键导航、带 ActionSheet 的长按，以及与虚拟键盘的集成。子类实现空间映射（1D 与 2D）、滚动、渲染和掩码。

你不直接实例化 TextInput —— 而是实例化 TextField 或 TextArea。本页是两者所继承内容的总览。它实现 UIConstants.TextInputComponent（setText/getText/isPassword/replaceText/keyboardHidden/getCursorPos/hasFocus）。

🟡 · 包： dev.crossfly.ui · 继承： Component · 实现： UIConstants.TextInputComponent · 抽象

何时使用

  • 作为引用任何输入字段的通用类型（TextInput campo = new TextField(...)）。
  • 编写在光标/选择/剪贴板上操作而不关心是 1 行还是 N 行的代码时。

何时不使用

  • 实例化一个具体字段 → 使用 TextField（1 行）或 TextArea（多行）。

层级

Component → TextInput（抽象）→ TextField / TextArea。构造函数接收缓冲区的初始容量：TextInput(int initialCapacity)。它是 isPressable() → true。

内部状态（关键字段）

字段 类型 含义
chars StringBuffer 文本的原始缓冲区
text String 显示的文本（由子类更新；初始为 ""）
insertPos int 光标位置（插入）
startSelectPos int 选择的起点，若无选择则为 -1
cursorShowing boolean 光标闪烁的可见相位
keyboardCanOpen boolean 键盘可在下一次 touch-up 时打开
hasFocus boolean 拥有键盘焦点
caption String 占位符 / 浮动 caption

继承的方法（光标、选择、剪贴板）

方法 返回 作用
setText(String) void* 设置文本（由子类实现）
getText() String 当前文本（在 TextField 中含掩码）
setCursorPos(int start, int end) void 设置选择；若 start==end，则只移动光标
setCursorPos(int pos) void 无选择的光标
getCursorPos() int[] [startSelectPos, insertPos]
getInsertPos() int 光标位置
hasSelection() boolean 是否有选中的区间？
getSelectionStart() / getSelectionEnd() int 位置的 min / max
getTextBuffer() / getLength() StringBuffer / int 原始缓冲区 / 长度
clipboardCopy() / clipboardCut() void 复制 / 剪切选区（通过 Device.clipboard*）
clipboardPaste() / clearText() void 抽象 —— 子类处理掩码/\n
mapKeys(String from, String to) void 逐字符的重映射（若长度不同则抛出 IllegalArgumentException；null/null 清除）
hasFocus() boolean 拥有键盘焦点
restoreFocusAtEnd() void 重新赋予焦点并将光标移到末尾（关闭 picker/keypad 之后）

*setText 在 TextComponent 契约中返回 void；TextField.text(...)/TextArea.text(...) 提供返回字段本身的流式变体。

回调与事件

回调 何时触发
onAction(Action)（继承） 在 onTouchUp（打开键盘之后）
onFocus() / onBlur() 获得 / 失去焦点（开启/关闭光标和闪烁）

不存在专门的 onChange：要对变化作出反应，通过动作回调观察或查询 getText()。

状态

  • focused： 光标开启并闪烁（cursorShowing），触摸时打开键盘/Keypad；onFocus()/onBlur() 控制过渡。
  • selection： 区间 [startSelectPos, insertPos]；长按选中全部并打开 ActionSheet（Copy/Cut/Paste/Clear）。
  • disabled / read-only： 样式中的 setEnabled(false) 或 editable=false 阻止编辑。

按键（继承自 onKeyDown）

  • Ctrl+C / V / X → 复制 / 粘贴 / 剪切；Ctrl+A → 选中全部。
  • Backspace / Delete → 删除选区或一个字符。
  • Left / Right / Home / End → 移动光标；配合 Shift 扩展选择。

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

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

      // 多态引用：TextInput 是 TextField/TextArea 的抽象基类
      TextInput campo = new TextField("valor inicial");
      add(LAY_AUTO, (Component) campo);

      // 输出 Label
      Label saida = new Label("Leia o campo com o botão");
      add(LAY_AUTO, saida);

      // 没有按键事件：在提交时读取 getText()
      Button enviar = new Button("Enviar")
         .onAction(c -> saida.setText("Você digitou: " + campo.getText()));
      add(LAY_AUTO, enviar);
   }
}

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

示例（使用基类型）

// 对具体字段的多态引用
TextInput campo = new TextField("valor inicial");
container.add(LAY_AUTO, (Component) campo);

// 通过基类进行的通用操作
if (campo.hasSelection())
   campo.clipboardCopy();
int[] sel = campo.getCursorPos();     // [start, insert]
campo.setCursorPos(campo.getLength()); // 光标移到末尾

最佳实践

  • 当代码不依赖于格式（1 行 vs N 行）时，针对 TextInput/UIConstants.TextInputComponent 编程。
  • 关闭 picker/Keypad 之后，调用 restoreFocusAtEnd() 以正确地归还焦点。

常见错误

  • 试图实例化 TextInput： 它是抽象的 —— 使用 TextField/TextArea。
  • 期待 clipboardPaste()/clearText() 在基类中生效： 它们是抽象的；行为来自子类（TextField 中的掩码，TextArea 中的 \n）。

另见

这个页面有帮助吗？