API 参考 / 只读视图、场景、音频与文本

TextField

想先跑起来？

这一页是签名与行为参考。单行输入框，场景里直接 new。直接做一遍：教程 · 自定义场景。

统一单行文本编辑组件（宿主与模组共用一份实现），public final class，模组可直接 new 出来用于自制界面（如模组设置页的搜索框、联机房间的 IP/端口输入）。逻辑层不依赖渲染对象，可被终端等字符画场景直接复用；常规场景用 render 即可获得标准输入框外观。

方法速览

方法	用途
`TextField(int, boolean)` / `TextField()`	构造（最大长度 / 仅数字）
`password(boolean)`	密码掩码（链式）
`enableHistory(int)`	启用输入历史（链式）
`charFilter(Predicate)`	自定义字符过滤（链式）
`text()` / `display()`	当前文本 / 展示文本
`cursorIndex()` / `selectionStart()` / `selectionEnd()` / `selectedText()`	光标与选区
`reset(String)` / `clear()`	重置 / 清空
`handleInput(InputEvent)`	事件入口（场景转发）
`keyPressed(int, boolean, boolean)`	方法级按键入口
`typeString(String)`	插入文本
`rememberCurrent()`	记入输入历史
`reportImeAnchor(double, double)`	手动上报 IME 锚点
`render(RenderCanvas, double, double, double, double, boolean)`	标准输入框绘制

TextField(int, boolean)

java

public TextField(int maxLength, boolean numericOnly);

行为：创建输入组件。maxLength 内部按 Math.max(1, maxLength) 收敛；numericOnly 为 true 时只接受 0-9（键入与粘贴统一生效）。示例：

java

TextField port = new TextField(5, true);

TextField()

java

public TextField();

行为：等价于「最大 256 字符、不限数字」。示例：

java

TextField search = new TextField();

password(boolean)

java

public TextField password(boolean on);

行为：开关密码掩码——开启后 display() 返回等长 *，text() 仍为原文。返回 this 以支持链式调用。示例：

java

TextField pw = new TextField(32, false).password(true);

enableHistory(int)

java

public TextField enableHistory(int max);

行为：启用输入历史并设置容量（内部 Math.max(0, max)，0 = 不启用）。返回 this。示例：

java

TextField cmd = new TextField(200, false).enableHistory(20);

charFilter(Predicate)

java

public TextField charFilter(Predicate<Character> filter);

行为：设置自定义字符过滤器（null = 不过滤），对键入与粘贴统一生效：返回 false 的字符被丢弃。返回 this。示例：

java

TextField fileName = new TextField(64, false)
        .charFilter(ch -> "\\/:*?\"<>|".indexOf(ch) < 0);

text()

java

public String text();

行为：当前文本（原始值，掩码不影响）。示例：

java

String value = field.text();

display()

java

public String display();

行为：展示文本——密码模式下为等长 *（空文本仍为空串），否则与 text() 相同。示例：

java

canvas.drawText(field.display(), x, y, style);

cursorIndex()

java

public int cursorIndex();

行为：光标位置，取值 0..length。示例：

java

int caret = field.cursorIndex();

selectionStart()

java

public int selectionStart();

行为：选区起点（min(anchor, caret)）；无选区时等于光标位置。示例：

java

int from = field.selectionStart();

selectionEnd()

java

public int selectionEnd();

行为：选区终点（max(anchor, caret)，排他）；无选区时等于光标位置。示例：

java

int to = field.selectionEnd();

selectedText()

java

public String selectedText();

行为：当前选区文本；无选区返回 null（调用方需判空）。示例：

java

String sel = field.selectedText();
if (sel != null && !sel.isEmpty()) { ClipboardAccess.setText(sel); }

reset(String)

java

public void reset(String s);

行为：重置文本与光标（null 视为空串，光标移到末尾），并清空撤销/重做栈与历史游标；不修改配置（最大长度、掩码、过滤器、历史容量保持）。示例：

java

field.reset("");

clear()

java

public void clear();

行为：等价 reset("")。示例：

java

field.clear();

handleInput(InputEvent)

java

public boolean handleInput(InputEvent event);

行为：事件入口——TEXT_INPUT 走 typeString(text())，KEY_PRESSED 走 keyPressed(keyCode, shiftDown, ctrlDown)，其余类型直接返回 false。场景应只把聚焦组件的输入转发到这里。示例：

java

@Override
public boolean handleInput(InputEvent event) {
    if (event.type() != InputType.KEY_PRESSED && event.type() != InputType.TEXT_INPUT) {
        return false;
    }
    return field.handleInput(event);
}

keyPressed(int, boolean, boolean)

java

public boolean keyPressed(int keyCode, boolean shift, boolean ctrl);

行为：方法级按键入口（供轮询式场景直接调用，如终端/登录），键码与 JDK VK_* 一致，返回 true 表示键被消费。支持：←→（Shift 扩展选区）、Home / End、Backspace、Delete；Ctrl+C/X/V/Z/Y/A（Ctrl+Shift+Z 与 Ctrl+Y 为重做）。↑↓ 在启用历史时翻阅（历史为空或未启用时返回 false）；TAB 永不消费（返回 false，焦点切换留给场景）；其余键返回 false。撤销栈上限 64 步。示例：

java

field.keyPressed(java.awt.event.KeyEvent.VK_BACK_SPACE, false, false);
field.keyPressed(java.awt.event.KeyEvent.VK_LEFT, true, false);   // Shift+← 扩展选区

typeString(String)

java

public boolean typeString(String t);

行为：插入文本，规则与键入一致：丢弃控制符（< 32 与 127）、多行取首行、numericOnly 限制、charFilter 过滤、按剩余预算截断到最大长度，并替换当前选区；null / 空串为空操作。返回值恒为 true（文本事件总被聚焦组件消费）。示例：

java

field.typeString("hello");

rememberCurrent()

java

public void rememberCurrent();

行为：场景在提交成功后调用（如发送聊天），把当前文本记入输入历史：historyMax <= 0 或文本为空时无效果；相同的既有条目会先被移除（去重）再追加，超出容量时移除最早条目；随后重置历史游标。示例：

java

if (enterPressed) {
    submit(field.text());
    field.rememberCurrent();
}

reportImeAnchor(double, double)

java

public void reportImeAnchor(double cursorVirtualX, double anchorVirtualY);

行为：供自绘场景在渲染 focused 组件时手动上报 IME 锚点，直接转发到 ImeAnchor 的 report。cursorVirtualX 为光标竖线的场景逻辑 X，anchorVirtualY 为期望候选窗顶部 Y（通常取输入框底部），坐标属 1280×720 逻辑空间。示例：

java

field.reportImeAnchor(boxX + caretOffset, boxY + boxH);

render(RenderCanvas, double, double, double, double, boolean)

java

public void render(RenderCanvas c, double x, double y, double w, double h, boolean focused);

行为：按标准外观绘制（深底、1px 边框、文本、选区反白、光标竖线）；文本超宽时水平滚动跟随光标。focused 为 true 时绘制光标竖线并自动上报 ImeAnchor（坐标 x 方向含滚动偏移、y 方向取输入框底边）。内部宽度 ≤ 4 时只画底与边框后提前返回（此时不上报锚点）。组件不持有焦点状态，焦点由场景管理并在每次调用时传入。示例：

java

field.render(canvas, 40, 620, 300, 32, focused);

完整签名

java

public final class TextField {
    public TextField(int maxLength, boolean numericOnly);
    public TextField();
    public TextField password(boolean on);
    public TextField enableHistory(int max);
    public TextField charFilter(java.util.function.Predicate<Character> filter);
    public String text();
    public String display();
    public int cursorIndex();
    public int selectionStart();
    public int selectionEnd();
    public void reset(String s);
    public void clear();
    public boolean handleInput(InputEvent event);
    public boolean keyPressed(int keyCode, boolean shift, boolean ctrl);
    public boolean typeString(String t);
    public void rememberCurrent();
    public void reportImeAnchor(double cursorVirtualX, double anchorVirtualY);
    public String selectedText();
    public void render(RenderCanvas c, double x, double y, double w, double h, boolean focused);
}

能力一览：光标移动（←→/Home/End）、键盘选区（Shift+移动）、剪贴板（Ctrl+C/X/V，经 ClipboardAccess）、撤销/重做（Ctrl+Z / Ctrl+Y 或 Ctrl+Shift+Z）、全选（Ctrl+A）、输入历史（↑↓，需启用）、密码掩码、数字限制、最大长度限制、自定义字符过滤、中文 IME（TEXT_INPUT 链路）。

线程：源码未声明额外线程约束（组件本身无锁，只在场景线程使用）。

性能：render 每次调用都会测量文本宽度，超宽内容会触发水平滚动重算——不要每帧对大文本反复测量或对同一文本重复绘制。

稳定性：2.0 起冻结：2.x 内只增不破。

上一页文本输入（text 包）下一页ImeAnchor