# 文本区域

> TextArea：多行文本输入、内容滚动，以及可以逐行显示的图标。

Source: https://crossfly.dev/zh/docs/ui/forms-and-input/text-areas — CrossFly documentation. Full docs as one file: https://crossfly.dev/llms-full.txt

# 文本区域（`TextArea`）

`TextArea` 是**多行**字段——与 `TextField` 基于同一基类（`TextInput`），支持换行、垂直滚动
和按行图标。

## 完整示例（复制、粘贴并运行）
```java
package com.exemplo;

import dev.crossfly.ui.*;
import dev.crossfly.ui.layout.*;
import dev.crossfly.ui.style.*;   // TextAreaStyle（行为配置）

/** 可执行的主界面。将 launcher 指向此类（classname）并运行：gradlew :lwjgl3:run */
public class MainWindow extends Window
{
   @Override
   public void onShow() throws Exception
   {
      super.onShow();
      setLayout(new VerticalLayout());

      // 多行区域：需要显式高度。
      // 此处用容器比例（高度的 40%）；替代方案：样式中的 autoHeight。
      TextArea obs = new TextArea().caption("Observações");
      add(0.4f, obs);

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

      // 没有按键回调：在提交时读取 getText()
      Button enviar = new Button("Enviar");
      enviar.onAction(c -> resultado.setText("Chars = " + obs.getText().length()));
      add(LAY_AUTO, enviar);
   }
}
```

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

## 基本用法
```java
TextArea obs = new TextArea()
   .caption("Observações")
   .text("");
painel.add(0.5f, obs);   // 占容器高度的 50%（VerticalLayout）

// 读取内容：
String texto = obs.getText();
```

## 构造函数与流式 API
| 成员 | 效果 |
|---|---|
| `new TextArea()` / `new TextArea("texto")` | 空 / 带初始值 |
| `.caption(String)` | 标题 |
| `.text(String)` / `setText(String)` | 设置内容 |
| `.rightIcons(Icon...)` | 右侧图标，每个操作行一个 |
| `.rightIconAction(int linha, Action)` | 特定图标的动作 |
| `getText()` / `clearText()` | 读取 / 清空 |
| `scrollToTop()` · `scrollToBottom()` · `scrollToLine(int)` | 程序化滚动 |

## 设置尺寸
与 `TextField`（单行高度）不同，`TextArea` 需要**显式高度**——在 `VerticalLayout` 中给出
一个比例，或在样式中使用 `autoHeight`：
```java
obs.getStyle().autoHeight(Relative.ofFont(6f));   // 约 6 行高
```

## 最佳实践
- 预留足够的高度（容器比例或 `autoHeight`）——否则会变成单行字段。
- 追加文本时（如日志/聊天）使用 `scrollToBottom()`，以保持最后一行可见。

## 常见错误
- 不设置高度 → 区域变得非常小。
- 期望水平滚动——`TextArea` 会换行；单行可滚动请使用 `TextField`。

## 另见
- [文本字段](/docs/ui/forms-and-input/text-fields) · [焦点与验证](/docs/ui/forms-and-input/focus-and-validation)
- 目录：[TextArea](/docs/ui/widgets/textarea) · 参考：第 14 章