TextArea

自 2.2.1

TextArea 是多行文本编辑器。其值为 String[] —— 每行一个元素。它内置了水平和垂直滚动条、用于错误高亮的文本验证器，以及完整的键盘支持（方向键、Home/End、PageUp/PageDown、Ctrl+←/→ 按词导航、选择、复制/剪切/粘贴、撤销/重做）。

当编辑器获得焦点（被点击）时，即可进行编辑。双击可选中一个单词。

INFO

UIElement 中记录的所有内容（布局、样式、事件、数据绑定等）同样适用于此组件。

---

用法

var area = new TextArea();
area.setValue(new String[] { "Line 1", "Line 2", "Line 3" });
area.setLinesResponder(lines -> {
    // 每次有效编辑时调用
    System.out.println("Lines: " + Arrays.toString(lines));
});
parent.addChild(area);

textArea({
    layout { width(200).height(80) }
}) {
    api {
        setValue(arrayOf("Line 1", "Line 2"))
        setLinesResponder { lines -> println(lines.joinToString("\n")) }
    }
}

let area = new TextArea();
area.setValue(["Line 1", "Line 2"]);
area.setLinesResponder(lines => { /* ... */ });
parent.addChild(area);

---

XML

    <!-- 预填充文本（在源码中以 \n 分隔行） -->
<text-area>Line 1
Line 2
Line 3</text-area>

INFO

TextArea 在 XML 中不能添加布局子元素 —— 只能包含文本内容。

---

内部结构

CSS 类名	描述
.__text-area_content-view__	主编辑区域。
.__text-area_vertical-scroller__	垂直滚动条（右侧）。
.__text-area_horizontal-scroller__	水平滚动条（底部）。

---

Text Area 样式

INFO

focus-overlay

当内容视图被悬停或获得焦点时绘制的覆盖纹理。

默认值：Sprites.RECT_RD_T_SOLID

area.textAreaStyle(style -> style.focusOverlay(myHighlight));

text-area {
    focus-overlay: rect(#FFFFFF22, 2);
}

INFO

font / font-size

所有行使用的字体和字号。

默认值：原版默认字体 / 9

text-area {
    font: "minecraft:uniform";
    font-size: 9;
}

INFO

text-color / error-color

有效文本的颜色 / 验证器拒绝内容时的颜色。

默认值：0xFFFFFF / 0xFF0000

text-area {
    text-color: #EEEEEE;
    error-color: #FF4444;
}

INFO

cursor-color

闪烁光标的颜色。

默认值：0xEEEEEE

text-area {
    cursor-color: #FFFFFF;
}

INFO

text-shadow

是否在文本下方绘制阴影。

默认值：true

text-area {
    text-shadow: false;
}

INFO

placeholder

当所有行为空时显示的占位文本。

默认值：翻译键 text_field.empty

area.textAreaStyle(style -> style
    .placeholder(Component.literal("Enter code…"))
);

INFO

line-spacing

行与行之间额外添加的像素间距。

默认值：1

text-area {
    line-spacing: 2;
}

INFO

scroller-view-mode

启用的滚动轴方向。可选值：HORIZONTAL、VERTICAL、BOTH。

默认值：BOTH

area.textAreaStyle(style -> style.viewMode(ScrollerMode.VERTICAL));

text-area {
    scroller-view-mode: VERTICAL;
}

INFO

scroller-vertical-display / scroller-horizontal-display

每个滚动条的可见策略。可选值：AUTO（仅在内容溢出时显示）、ALWAYS、NEVER。

默认值：AUTO

area.textAreaStyle(style -> style
    .verticalScrollDisplay(ScrollDisplay.ALWAYS)
    .horizontalScrollDisplay(ScrollDisplay.NEVER)
);

text-area {
    scroller-vertical-display: ALWAYS;
    scroller-horizontal-display: NEVER;
}

INFO

scroller-view-margin

当垂直滚动条可见时，水平滚动条的右边距。

默认值：5

text-area {
    scroller-view-margin: 5;
}

---

值绑定

TextArea 扩展自 BindableUIElement<String[]>，因此支持数据绑定系统：

area.bind(DataBindingBuilder.create(
    () -> config.getLines(),
    lines -> config.setLines(lines)
).build());

详见 数据绑定。

---

字段

名称	类型	访问权限	描述
horizontalScroller	Scroller.Horizontal	public final	水平滚动条。
verticalScroller	Scroller.Vertical	public final	垂直滚动条。
contentView	UIElement	public final	可见的编辑区域。
textAreaStyle	TextAreaStyle	private（有 getter）	当前样式实例。
isError	boolean	private（有 getter）	当前行未通过验证器时为 true。
cursorLine	int	private（有 getter）	光标所在行（从 0 开始）。
cursorCol	int	private（有 getter）	光标所在列（从 0 开始）。

---

方法

方法	返回	描述
setValue(String[])	TextArea	设置所有行并通知监听器。
setValue(String[], boolean)	TextArea	设置所有行；第二个参数控制是否通知。
setLines(List<String>)	TextArea	setValue(list.toArray(...)) 的便捷方法。
setLinesResponder(Consumer<String[]>)	TextArea	注册监听器，每次有效编辑时调用。
setTextValidator(Predicate<String[]>)	TextArea	自定义验证器；无效内容以 error-color 显示。
setCharValidator(Predicate<Character>)	TextArea	在字符插入前进行过滤。
textAreaStyle(Consumer<TextAreaStyle>)	TextArea	以流式方式配置样式。
getValue()	String[]	返回最后验证通过的行数组。
isEditable()	boolean	当获得焦点、处于活动状态、可见且已显示时为 true。
hasSelection()	boolean	当存在活动文本选区时为 true。
setCursor(int, int)	void	将光标移动到指定的 (line, col) 位置。