3.5.2.1.21. 图片组件

Image 图片组件可以显示不同源的图片。可以绑定到数据容器或通过代码设置。

参考 在 CUBA 应用程序中使用图片 指南,了解如何在应用程序中上传和显示图片。

该组件的 XML 名称为: image

Image 图片组件可以显示实体属性为 FileDescriptorbyte[] 类型的数据。下面是一个简单的通过 dataContainerproperty 属性设置图片的例子:

<image id="image" dataContainer="employeeDc" property="avatar"/>

该组件展示 employeeDc 数据容器中 Employee 实体的 avatar 属性。

Image 图片组件还可以展示其它源的图片。可通过以下 image 的元素设置不同的源类型:

  • classpath - classpath 中的某个资源

    <image>
        <classpath path="com/company/sample/web/screens/myPic.jpg"/>
    </image>
  • file - 文件系统中的某个资源

    <image>
        <file path="D:\sample\modules\web\web\VAADIN\images\myImage.jpg"/>
    </image>
  • relativePath - 应用程序目录中的某个资源

    <image>
        <relativePath path="VAADIN/images/myImage.jpg"/>
    </image>
  • theme - 主题资源,例如 VAADIN/themes/customTheme/some/path/image.png

    <image>
        <theme path="com.company.sample/myPic.jpg"/>
    </image>
  • url - 可以从指定 URL 加载的资源

    <image>
        <url url="https://www.cuba-platform.com/sites/all/themes/cuba_adaptive/img/lori.png"/>
    </image>

image 图片组件的属性:

  • scaleMode - 缩放模式,有以下几种模式可选:

    • FILL - 根据组件大小拉伸图片。

    • CONTAIN - 保留长宽比压缩图片到能刚好在组件中全部展示。

    • COVER - 图片会被压缩或者拉升以适应组件的整个区域,维持组件本身的比例。如果图片的比例和组件的比例不匹配,会将图片做裁剪以适配组件的比例。

    • SCALE_DOWN - 在 NONECONTAIN 中选择图片能全部展示并且尺寸最小的方式。

    • NONE - 按实际大小显示。

  • alternateText - 设置替换文本,当资源未设置或找不到时显示该文本。

    <image id="image" alternateText="logo"/>

image 资源设置:

  • bufferSize - 下载该资源时的缓存大小,以字节为单位。

    <image>
        <file bufferSize="1024" path="C:/img.png"/>
    </image>
  • cacheTime - 该资源缓存过期时间,以毫秒为单位。

    <image>
        <file cacheTime="2400" path="C:/img.png"/>
    </image>
  • mimeType - 该资源的 MIME 类型。

    <image>
        <url url="https://avatars3.githubusercontent.com/u/17548514?v=4&#38;s=200"
             mimeType="image/png"/>
    </image>

如需以编程的方式管理 Image 组件,可以使用下列方法:

  • setValueSource() - 设置数据容器和实体属性名称,只支持 FileDescriptorbyte[] 两种类型的属性。

    数据容器可以通过编程的方式设置,比如在单元格中显示图片:

    frameworksTable.addGeneratedColumn("image", entity -> {
        Image image = uiComponents.create(Image.NAME);
        image.setValueSource(new ContainerValueSource<>(frameworksTable.getInstanceContainer(entity), "image"));
        image.setHeight("100px");
        return image;
    });
    gui Image 1
  • setSource() - 设置图片源内容。输入源类型,返回源对象,并继续通过流式接口配置源内容。每种源类型都有各自设置源内容的方法,比如 ThemeResource 主题源用 setPath()StreamResource 流资源用 setStreamSupplier()

    Image image = uiComponents.create(Image.NAME);
    
    image.setSource(ThemeResource.class)
            .setPath("images/image.png");

    或:

    image.setSource(StreamResource.class)
            .setStreamSupplier(() -> new FileDataProvider(fileDescriptor).provide())
            .setBufferSize(1024);

    使用以下实现了 Resource 接口的资源类型,或者通过扩展它实现自定义资源:

    • ClasspathResource - 位于 classpath 中的图片. 这类资源还可以通过 image 组件的 classpath 元素以声明的方式设置。

    • FileDescriptorResource - 通过 FileDescriptorFileStorage 中获取的图片。

    • FileResource - 文件系统中的图片。这类资源还可以通过 image 组件的 file 元素以声明的方式设置。

    • RelativePathResource - 应用程序中的图片。这类资源还可以通过 image 组件的 relativePath 元素以声明的方式设置。

    • StreamResource - 来自于流的图片。

    • ThemeResource - 主题的图片,比如 VAADIN/themes/yourtheme/some/path/image.png。这类资源还可以通过 image 组件的 theme 元素以声明的方式设置。

    • UrlResource - 从 URL 中加载的图片。这类源还可以通过 image 组件的 url 元素以声明的方式设置。

  • createResource() - 根据图片源类型创建图片资源。创建的对象可以传入 setSource() 方法。

    FileDescriptorResource resource = image.createResource(FileDescriptorResource.class)
            .setFileDescriptor(avatar);
    image.setSource(resource);
  • addClickListener() - 设置点击图片区域的监听器。

    image.addClickListener(clickEvent -> {
        if (clickEvent.isDoubleClick())
            notifications.create()
                    .withCaption("Double clicked")
                    .show();
    });
  • addSourceChangeListener() - 设置图片源改变的监听器。