如何为 Component 设置背景图像

目的。 在任意 Component（一个屏幕、一个面板、 一个卡片）的内容后面绘制一张图像，控制它如何填充区域以及居中在何处。与 ImageView 不同， 背景图像由组件自身绘制，在子元素后面。

使用的 API

• void Component.addBackgroundImage(Image image, ImageSize imageSize, float centerX, float centerY) — 添加一张背景图像。centerX/centerY 是 0 到 1 之间的分数，用于把图像定位在剩余空间中（0.5, 0.5 = 居中）。
• void Component.addBackgroundImage(Image image, Relative width, Relative height, float centerX, float centerY) — 使用显式相对宽度/高度（通过 Relative）而非 ImageSize 的变体。
• ImageSize（枚举，已在 UIConstants 中验证）：ORIGINAL, RATIO, STRETCH, FIT, FIT_WIDTH, FIT_HEIGHT, FIT_HALF_WIDTH, FIT_HALF_HEIGHT。

适用于背景的模式（BackgroundImage.onPaint 中的行为）

• FIT — 在保持比例的情况下覆盖整个区域（可能超出/裁切）。这是壁纸的典型模式。
• RATIO — 在保持比例的情况下整幅装入区域内（letter-box）。
• STRETCH — 拉伸以精确填充，忽略比例。
• ORIGINAL — 自然尺寸，不缩放。

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

package com.exemplo;

import java.io.IOException;

import dev.crossfly.ui.*;                     // Window, Component
import dev.crossfly.ui.layout.*;             // VerticalLayout
import dev.crossfly.ui.image.*;              // Image, ImageException
import dev.crossfly.ui.UIConstants.ImageSize;

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

      try {
         Image bg = new Image("/sdcard/wallpaper.jpg");

         // 覆盖整个组件（此处为窗口本身），居中，
         // 并保持比例：
         addBackgroundImage(bg, ImageSize.FIT, 0.5f, 0.5f);
      } catch (ImageException | IOException e) {
         // 文件未找到或已损坏
      }
   }
}

下面的片段仅展示核心部分。要运行它，请把它放入上面的 MainWindow 骨架中。

最小片段

// 已在源码核实：Component.addBackgroundImage（158、181）；BackgroundImage.java onPaint（105）
import dev.crossfly.ui.image.Image;
import dev.crossfly.ui.UIConstants.ImageSize;

Image bg = new Image("/sdcard/wallpaper.jpg");

// 覆盖整个组件，居中，保持比例：
meuComponent.addBackgroundImage(bg, ImageSize.FIT, 0.5f, 0.5f);

实现说明（源码）：

• 对于除 ORIGINAL 外的所有模式，如果图像大于目标区域，BackgroundImage 会预缩放图像一次（resize(..., ResizeMode.STRETCH, ResizeQuality.FAST)）并缓存 结果，从而减少 GPU 的纹理带宽。如果 resize 失败，则回退到原图。
• centerX/centerY 在剩余空间内移动图像：位置为 (component.width - w) * centerX（Y 同理）。使用 0,0 时图像贴在左上角。
• 可以向同一个组件添加多张背景图像；它们按插入顺序绘制。

深入了解

• 姊妹配方：carregar-arquivo-rede.md — 在把图像用作背景之前先加载它。
• 图像 — ImageSize 各模式详解。