图片组件 - CUBA 框架开发者手册

3.5.2.1.21. 图片组件

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

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

该组件的 XML 名称为： image

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

<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 - 在 NONE 和 CONTAIN 中选择图片能全部展示并且尺寸最小的方式。
- 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() - 设置数据容器和实体属性名称，只支持 FileDescriptor 和 byte[] 两种类型的属性。

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

frameworksTable.addGeneratedColumn("image", entity -> {
    Image image = uiComponents.create(Image.NAME);
    image.setValueSource(new ContainerValueSource<>(frameworksTable.getInstanceContainer(entity), "image"));
    image.setHeight("100px");
    return image;
});

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 - 通过 FileDescriptor 从 FileStorage 中获取的图片。
- 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() - 设置图片源改变的监听器。

Image 图片组件的属性列表: align - alternateText - caption - captionAsHtml - colspan - contextHelpText - contextHelpTextHtmlEnabled - css - dataContainer - description - descriptionAsHtml - editable - enable - box.expandRatio - height - htmlSanitizerEnabled - icon - id - property - required - requiredMessage - responsive - rowspan - scaleMode - stylename - stylename - visible - width
Image resources 图片源的属性列表: bufferSize - cacheTime - mimeType
Image 图片组件的元素: classpath - file - relativePath - theme - url
API: addClickListener - addSourceChangeListener - createResource - setScaleMode - setSource - setValueSource