# GridLayout

> 按分数比例划分列的网格布局，每一行的高度由该行最高的内容决定。

Source: https://crossfly.dev/zh/docs/ui/layouts/grid-layout — CrossFly documentation. Full docs as one file: https://crossfly.dev/llms-full.txt

# GridLayout

将子组件排布成一个**网格**：每行拥有自己的**按分数划分列**的方式，而行高由最高的组件决定。非常适合"标签 : 字段"形式的表单。

> 🟡 · **包：** `dev.crossfly.ui.layout` · **继承自：** `Layout`

## 何时使用
- 比例稳定、对齐的表单（标签 | 字段）。
- 简单的单元格表格。

## 何时不要使用
- 只有一列 → [VerticalLayout](/docs/ui/layouts/vertical-layout)。
- 将一个组件锚定到另一个组件 → [RelativeLayout](/docs/ui/layouts/relative-layout)。

## `add(...)` — 签名与语义（注意顺序！）
```java
public GridLayout add(Object... v)   // 先所有宽度，再所有组件
```
**先传入所有宽度**，再传入**所有组件**（数量相同）：

| 宽度 | 含义 |
|---|---|
| `> 0`（例如 `0.35f`） | 网格宽度的**分数**（35%） |
| `LAY_AUTO`（`0f`） | **自动**宽度（单元格使用内容的尺寸） |

## 构造函数
| 构造函数 | 说明 |
|---|---|
| `new GridLayout()` | 对齐方式为 `START`/`START` |
| `new GridLayout(Position h, Position v)` | 各行的水平/垂直对齐方式 |

## 完整示例（复制、粘贴并运行）
```java
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();

      GridLayout form = new GridLayout(Position.START, Position.START);
      // 标签（35%）| 字段（65%）——先宽度，后组件：
      form.add(0.35f, 0.65f, new Label("Nome"),     new TextField(""));
      form.add(0.35f, 0.65f, new Label("E-mail"),   new TextField(""));
      form.add(0.35f, 0.65f, new Label("Telefone"), new TextField(""));

      Component painel = new Component();
      painel.setLayout(form);

      setLayout(new VerticalLayout(Position.START, Position.START));
      add(LAY_AUTO, new Label("Cadastro"));
      add(LAY_FILL, painel);
   }
}
```

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

## 基本用法
```java
GridLayout form = new GridLayout(Position.START, Position.START);
// 标签（35%）| 字段（65%）——先宽度，后组件：
form.add(0.35f, 0.65f, new Label("Nome"),     new TextField(""));
form.add(0.35f, 0.65f, new Label("E-mail"),   new TextField(""));
form.add(0.35f, 0.65f, new Label("Telefone"), new TextField(""));

Component painel = new Component();
painel.setLayout(form);
```

## 排布方式
```
┌───────────┬──────────────────────┐
│ Nome (35%)│ [campo]        (65%)  │  ← linha 1
├───────────┼──────────────────────┤
│ E-mail    │ [campo]              │  ← linha 2
└───────────┴──────────────────────┘
```

## 最佳实践
- 一行的各分数**相加约为 ~1.0**，以覆盖整个宽度。
- 各行可以有**不同的列数**（每次 `add` 定义一行）。

## 常见错误
- **交错**传入宽度和组件：`add(0.35f, label, 0.65f, field)` → 抛出 `UIException`。
  正确写法是 `add(0.35f, 0.65f, label, field)`（宽度放一起，然后是组件）。
- 宽度数量 ≠ 组件数量 → `UIException`（`cols*2 == args`）。

## 另请参阅
- [VerticalLayout](/docs/ui/layouts/vertical-layout) · [RelativeLayout](/docs/ui/layouts/relative-layout) · [响应式设计](/docs/ui/layouts/responsiveness)