间距（Gap）

⚠️ Spacer 已在 2026 现代化改造中移除。 不再有间距组件。要分隔组件，请按偏好顺序使用：布局分数（LAY_AUTO/LAY_FILL/分数）、组件的 ingap/outgap，或直接使用 Gap 值。

Gap 表示间距值（左、上、右、下），带可选缩放。它在整个 UI 中用作 padding（ingap）、margin（outgap），以及布局的内部间距。一个 Gap 可以是：

• 固定像素 —— Gap.ofPixels(...)
• 相对于字体 —— Gap.ofFont(...)（随 font.scaledHeight() 缩放，适合响应式）
• 相对于屏幕 —— Gap.ofScreen(...)（屏幕尺寸的百分比）

🟢 · 包： dev.crossfly.ui · 继承： Component · 相关： ComponentStyle.ingap/outgap、布局

何时使用

• 定义组件的内部 padding（ingap）或外部 margin（outgap）。
• 向布局传递间距（例如单元格之间的间隙）。
• 用成比例的空间替代旧的 Spacer。

何时不要使用

• 要“推动”某个组件并吸收剩余空间 → 在 VerticalLayout/HorizontalLayout 中使用一行 LAY_FILL（见 layouts/），而不是固定的 Gap。

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

package com.exemplo;

import dev.crossfly.ui.*;
import dev.crossfly.ui.layout.*;
import dev.crossfly.ui.style.*;   // Styles, ButtonRole, State

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

      // 高度自然的表头
      add(LAY_AUTO, new Label("Cabeçalho"));

      // 通过 outgap（相对于字体的边距）使按钮与相邻元素隔开
      Button b = new Button("Enviar").style(
         Styles.theme().button(ButtonRole.PRIMARY, State.NORMAL)
            .pressable()
            .outgap(Gap.ofFont(0.5f)));   // 四边均为 0.5 × 字体高度
      add(LAY_AUTO, b);

      // 页脚被推到底部：LAY_FILL 那一行吸收垂直方向的剩余空间
      add(LAY_FILL, new Label("(espaço que sobra)"));
      add(LAY_AUTO, new Label("Rodapé"));
   }
}

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

1. 布局分数（推荐）

VerticalLayout col = new VerticalLayout();
col.add(LAY_AUTO, cabecalho);   // 自然高度
col.add(LAY_FILL, conteudo);    // 吸收剩余空间（将页脚往下推）
col.add(LAY_AUTO, rodape);

2. 样式中的 ingap / outgap

// 通过相对于字体的 outgap 设置外边距（使此组件与相邻元素隔开）
Button b = new Button("Enviar").style(
   Styles.theme().button(ButtonRole.PRIMARY, State.NORMAL)
      .pressable()
      .outgap(Gap.ofFont(0.5f)));   // 四边均为 0.5 × 字体高度
container.add(LAY_AUTO, b);

3. Gap 作为内部 padding

Label card = new Label("Conteúdo do cartão").style(
   Styles.theme().label(LabelRole.BODY)
      .ingap(Gap.ofFont(1f, 0.5f, 1f, 0.5f)));  // L,T,R,B 以字体为单位
container.add(LAY_AUTO, card);

工厂方法（Gap）

属性与方法

最佳实践

• 对于“剩余空间”，在布局中使用单独一行 LAY_FILL，而不是多个 gap。
• 复用 Gap.ZERO 来清零 padding，无需分配对象。

常见错误

• 寻找 Spacer 类： 它已不存在。请使用布局分数 / Gap / ingap/outgap。
• 对所有情况都使用 Gap.ofPixels： 在不同密度的屏幕上间距会不一致；请优先使用 ofFont/ofScreen。
• 尝试用两个固定 gap 来居中： 请使用布局的对齐方式或两侧的 LAY_FILL。

另请参阅

• 领域指南：ui/ · 食谱：cookbook/
• 概念（约束、响应式）：concepts/
• 相关组件：Label · Button