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

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

TextArea

TextArea 是多行文本输入。在基类 TextInput 之上，它增加了：自动换行、行结构、垂直滚动、二维坐标映射和多行布局。它支持右侧图标（每个可见行一个）和一个可滚动的只读模式（用于展示用户仅浏览的长文本）。

与 TextField 不同，TextArea 没有掩码也没有密码模式；ENTER 插入换行，getText() 保留 \n。

🟡 · 包： dev.crossfly.ui · 继承： TextInput · 样式： TextAreaStyle

何时使用

  • 备注、评论、描述、地址 —— 任何多行文本。
  • 展示一大块可滚动的长文本（使用 editable=false）。

何时不使用

  • 单行输入（姓名、邮箱、金额）→ 使用 TextField。
  • 掩码 / 密码模式 → 使用 TextField（TextArea 不支持它们）。

外观

带有 TextAreaStyle 的背景/边框的矩形，文本在内部宽度上自动换行分行，当内容超过高度时垂直滚动。首选高度来自 rowCount（可见行数）× 行高 + ingap。定义了右侧图标时，它们占据自己的一列，每个可见行一个。

``

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

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

      // 多行字段；LAY_FILL 为可滚动区域提供高度
      TextArea obs = new TextArea().caption("Observações");
      add(LAY_FILL, obs);

      // 输出 Label
      Label saida = new Label("Escreva algo e toque em Enviar");
      add(LAY_AUTO, saida);

      // 没有按键 onChange 事件：在提交时读取 getText()（保留 \n）
      Button enviar = new Button("Enviar")
         .onAction(c -> saida.setText("Você escreveu " + obs.getText().length() + " caracteres"));
      add(LAY_AUTO, enviar);
   }
}

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

基本用法

TextArea obs = new TextArea().caption("Observações");
container.add(0.4f, obs);
// ...
String texto = obs.getText();   // 保留 \n

构造函数

构造函数 描述
TextArea() 空
TextArea(String text) 带初始文本（\r\n/\r 被规范化为 \n）

属性与自定义

属性 / 方法 类型 默认值 作用
text(String) / setText(String) TextArea / void — 设置文本（规范化换行；光标置于开头）
getText() String — 原始文本，保留 \n
caption(String) TextArea（流式） null 占位符
rightIcons(Icon...) TextArea（流式） — 右侧图标，每个可见行一个
rightIconAction(int row, Action) TextArea（流式） — 第 row 行图标的动作（0 起始）
clearText() void — 清除全部文本
getNumberOfTextLines() int — 逻辑行总数（自动换行后）
scrollToTop() / scrollToBottom() / scrollToLine(int) void — 编程式滚动
样式 .rowCount(int) int — 可见行数（定义首选高度）
样式 .maxLength(int) int 0（无限制） 字符数限制
样式 .validChars(String) String null 允许的字符（\n 始终接受）
样式 .editable(false) boolean true 可滚动的只读
样式 .spaceBetweenLines(int) int — 行间额外间距

回调与事件

回调 何时触发
onAction(Action)（继承） 在 onTouchUp，打开键盘之后
onFocus() / onBlur()（继承） 获得 / 失去焦点
rightIconAction(row, Action) 触摸（并松开于）该行图标时

状态

  • focused： 光标闪烁，触摸时打开键盘；↑/↓ 方向键在行间导航。
  • selection： 通过拖动进行二维选择；长按选中全部并打开 ActionSheet。
  • read-only（editable=false）： 无光标/无编辑；拖动会滚动内容；鼠标滚轮也会滚动。

带限制的备注字段

TextArea obs = new TextArea().caption("Observações");
obs.style(Styles.theme()
   .textArea(State.NORMAL)
   .rowCount(4)
   .maxLength(500));
container.add(LAY_AUTO, obs);

只读、可滚动的文本块

TextArea termos = new TextArea(textoDosTermos);
termos.style(Styles.theme()
   .textArea(State.NORMAL)
   .editable(false)      // 只滚动，不编辑
   .rowCount(8));
container.add(LAY_FILL, termos);
termos.scrollToTop();

右侧带动作图标的行

TextArea lista = new TextArea("Item A\nItem B\nItem C");
lista.rightIcons(
   new MaterialIcon(""),   // 第 0 行的 "delete"
   new MaterialIcon(""),
   new MaterialIcon(""));
lista.rightIconAction(0, c -> removerLinha(0));
container.add(0.3f, lista);

最佳实践

  • 在样式中定义 rowCount 以控制可见高度；在布局中与 LAY_AUTO 配合。
  • 要展示不可编辑的长文本，使用 editable(false) —— 拖动将变为滚动而非选择。
  • 使用 getText() 进行持久化（保留 \n）；\r\n 的规范化已在输入时完成。

常见错误

  • 期待掩码或密码模式： TextArea 不支持它们 —— 使用 TextField。
  • 定义了过多 rightIcons： 只绘制到 visibleRows（可见行数）为止；超出的图标被忽略。

另见

这个页面有帮助吗？