跳到内容
CrossFly 是 100% 开源在 GitHub 关注我们
CrossFlyCrossFly
开始使用

本页面由葡萄牙语机器翻译，可能存在错误。葡萄牙语版本为准。

ImageView

ImageView 在组件边界内渲染一个 Image，缩放模式由枚举 ImageSize 控制，水平/垂直对齐通过 Position 设置。它是在布局中显示固定图像（照片、封面、logo）的声明式方式。

在内部，它维护一份缩放后的缓存副本（ResizeMode.STRETCH、ResizeQuality.FAST），以避免每一帧都重新调整大小；当更换图像、缩放模式或尺寸时，缓存会失效。

🟢 · 包： dev.crossfly.ui · 继承： Component · 样式： ComponentStyle（使用 ingap 作为内部 margin）

何时使用

  • 在布局中显示固定图像：照片、封面、logo、头像。
  • 调整图像如何填充空间（宽高比、覆盖、拉伸）。

何时不要使用

  • 逐帧动画、连续可变缩放或复合绘制 → 编写你自己的 Component，在 onPaint 中直接调用 paint.image(...)（见 images-and-graphics/）。
  • 另一个组件的背景图像 → 使用 Component 自身的 BackgroundImage（第 18 章）。

外观

图像默认在内部区域内（应用 ingap 之后）居中，并根据 ImageSize 缩放：

ImageSize 行为
ORIGINAL 自然尺寸，不缩放
RATIO 均匀缩放以适应边界内（letter-box）—— 默认
FIT 均匀缩放以覆盖边界（可能裁剪）
STRETCH 拉伸以精确填充（忽略宽高比）
FIT_WIDTH / FIT_HEIGHT 适应宽度 / 高度，保持比例
FIT_HALF_WIDTH / FIT_HALF_HEIGHT 适应一半宽度 / 高度

``

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

package com.exemplo;

import dev.crossfly.ui.*;
import dev.crossfly.ui.layout.*;
import dev.crossfly.ui.image.*;   // Image, ImageException

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

      // 加载 Image 可能抛出 ImageException/IOException — 请处理以免界面崩溃。
      ImageView iv = new ImageView();          // 空（占位符：什么也不绘制）
      try {
         Image capa = new Image("cf/samples/api/ui/books/book1.png");
         iv.image(capa).imageSize(ImageSize.RATIO);
      } catch (ImageException e) {
         System.out.println("Imagem não encontrada, usando placeholder vazio: " + e.getMessage());
      }

      add(LAY_FILL, iv);
   }
}

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

基本用法

Image capa = new Image("cf/samples/api/ui/books/book1.png");
ImageView iv = new ImageView(capa, ImageSize.RATIO);
container.add(LAY_FILL, iv);

构造函数

构造函数 描述
ImageView() 空（image = null，ImageSize.RATIO）
ImageView(Image image) 图像，模式为 RATIO
ImageView(Image image, ImageSize imageSize) 图像 + 缩放模式

属性与自定义

属性 / 方法 类型 默认值 作用
image(Image) ImageView（链式） null 更换图像（使缓存/布局失效）
imageSize(ImageSize) ImageView（链式） RATIO 定义缩放模式
alignX(Position) ImageView（链式） CENTER 水平对齐（START/CENTER/END）
alignY(Position) ImageView（链式） CENTER 垂直对齐
getImage() Image — 当前图像（或 null）
getImageSize() ImageSize — 当前模式
getAutoWidth() / getAutoHeight() int — 图像尺寸 + ingap（无图像时为 0）

回调与事件

无。ImageView 是非交互式的。

状态

没有交互状态。如果 image == null，则不绘制任何内容。

顶部对齐的覆盖（裁剪）

Image foto = new Image(caminhoFoto);
ImageView avatar = new ImageView(foto, ImageSize.FIT)
   .alignY(Position.START);      // 裁剪时保持顶部可见
container.add(0.4f, avatar);

运行时更换图像（链式）

ImageView iv = new ImageView();          // 空
container.add(LAY_FILL, iv);
// 之后，加载时：
iv.image(new Image(novoCaminho))
  .imageSize(ImageSize.STRETCH);

最佳实践

  • 给 ImageView 一个确定的布局空间（LAY_FILL 或分数）—— 缩放模式只有在边界已知时才有意义。
  • 当 Image 不再使用时，用 dispose() 释放它（原生资源 —— 见第 18 章）。
  • 在 Web 上，优先使用 ResizeQuality.FAST；ImageView 的内部缩放已经使用该路径。

常见错误

  • 混淆 FIT 与 RATIO： RATIO 做 letter-box（整体适应）；FIT 覆盖并可能裁剪。STRETCH 会扭曲。
  • 期望无图像的 ImageView 有自动尺寸： 当 image == null 时，getAutoWidth/Height() 返回 0。

另请参阅

这个页面有帮助吗？