# 如何为 Component 设置背景图像

> 使用 addBackgroundImage 和 ImageSize 为任意 Component 添加背景图像。

Source: https://crossfly.dev/zh/docs/cookbook/images/imagem-de-fundo — CrossFly documentation. Full docs as one file: https://crossfly.dev/llms-full.txt

# 如何为 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` — 自然尺寸，不缩放。

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

```java
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` 骨架中。

## 最小片段

```java
// 已在源码核实：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](/docs/cookbook/images/carregar-arquivo-rede) — 在把图像用作背景之前先加载它。
- [图像](/docs/ui/images-and-graphics/images) — `ImageSize` 各模式详解。