Roson的Qt之旅＃104 QML Image控件

概述

Image类型显示一个图像。

使用source属性将图像的源指定为URL。可以以Qt支持的任何标准图像格式提供图像，包括位图格式(如PNG和JPEG)和矢量图形格式(如SVG)。如果您需要显示动画图像，请使用AnimatedSprite或AnimatedImage。

如果没有指定宽度和高度属性，图像将自动使用加载图像的大小。默认情况下，指定项目的宽度和高度将导致图像缩放到该大小。这个行为可以通过设置fillMode属性来改变，允许图像被拉伸和平铺。

代码示例
下面的示例展示了Image类型的最简单用法.

  import QtQuick 2.0

  Image {
      source: "pics/qtlogo.png"
  }

性能

默认情况下，本地可用的映像将立即加载，并且用户界面将被阻塞，直到加载完成。如果要加载一个大的映像，通过启用异步属性，最好在低优先级线程中加载映像。
如果映像是从网络而不是本地资源获得的，则会自动异步加载它，并相应地更新进度和状态属性。
图像被缓存并在内部共享，因此如果多个Image项具有相同的源，则只加载图像的一个副本。
注意:图像通常是QML用户界面中最大的内存用户。建议不作为用户界面一部分的图像通过sourceSize属性来限定其大小。这对于从外部源加载或由用户提供的内容尤其重要。
参见Qt快速示例-图像元素和QQuickImageProvider。

属性说明

bool asynchronous

指定本地文件系统上的图像应该在单独的线程中异步加载。默认值为false，导致加载图像时用户界面线程阻塞。将异步设置为true在维护响应式用户界面比让图像立即可见更可取的情况下非常有用。
注意，此属性仅对从本地文件系统读取的图像有效。通过网络资源(例如HTTP)加载的图像总是异步加载的。

bool autoTransform

此属性保存图像是否应该自动应用图像转换元数据(如EXIF方向)。
默认情况下，该属性设置为false。
这个QML属性是在Qt 5.5中引入的。

bool cache

指定是否应该缓存映像。默认值为true。设置cache为false在处理大型图像时很有用，以确保它们不会以牺牲小的'ui元素'图像为代价进行缓存。

enumeration fillMode

设置此属性以定义当源图像的大小与项目不同时会发生什么情况。

• Image.Stretch - 图像被缩放以适应需要。
• Image.PreserveAspectFit - 图像被均匀地缩放到适合的位置，不进行裁剪
• Image.PreserveAspectCrop - 图像被均匀地缩放以填充，必要时进行裁剪。
• Image.Tile - 图像在水平和垂直方向上被复制。
• Image.TileVertically - 图像在水平方向上被拉伸，在垂直方向上被平铺
• Image.TileHorizontally - 图像在垂直方向上被拉伸，并在水平方向上铺设。
• Image.Pad - 图像不被转换

 注意clip默认为false，这意味着即使fillMode设置为PreserveAspectCrop，项目也可能在其边界矩形之外绘制。
参见Qt快速示例-图像元素。

enumeration horizontalAlignment

设置图像的水平和垂直对齐。默认情况下，图像是居中对齐的。
水平对齐的有效值是Image.AlignLeft、Image.AlignRight和Image.AlignHCenter。垂直对齐的有效值是Image.AlignTop、Image.AlignBottom和Image.AlignVCenter。

bool mipmap

无论图像在缩放或转换时是否使用mipmap过滤，此属性都保持不变。
与平滑相比，Mipmap过滤在缩放时提供了更好的视觉质量，但它可能会以性能成本为代价(在初始化图像和渲染期间)。
默认情况下，该属性设置为false。
这个QML属性是在Qt 5.3中引入的。
参见smooth

bool mirror

该属性保存图像是否应该水平反转(有效地显示镜像图像)。
默认值为false。

real paintedHeight

这些属性持有实际被绘制的图像的大小。在大多数情况下，它与宽度和高度相同，但当使用Image.PreserveAspectFit或Image.PreserveAspectCrop时，paintedWidth或paintedHeight可以比Image项目的宽度和高度小或大。

real paintedWidth

这些属性持有实际被绘制的图像的大小。在大多数情况下，它与宽度和高度相同，但当使用Image.PreserveAspectFit或Image.PreserveAspectCrop时，paintedWidth或paintedHeight可以比Image项目的宽度和高度小或大。

real progress

这个属性保存图片加载的进程，从0.0(没有加载)到1.0(完成)。
参见status。

smooth : bool

该属性保持图像在缩放或变换时是否平滑过滤。平滑过滤提供了更好的视觉质量，但在某些硬件上可能会比较慢。如果图像以其自然大小显示，则此属性没有视觉或性能效果。
默认情况下，该属性设置为true。
看到mipmap

url source

Image可以处理Qt支持的任何图像格式，从Qt支持的任何URL模式加载。
URL可以是绝对的，也可以是相对于组件URL的。
参见QQuickImageProvider.

sourceSize : QSize

这个属性保存加载图像的实际宽度和高度。
与缩放图像绘制的宽度和高度属性不同，此属性设置为加载的图像存储的实际像素数，以便大型图像不会使用不必要的更多内存。例如，这将确保内存中的图像不超过1024x1024像素，无论图像的宽度和高度值是多少:

  Rectangle {
      width: ...
      height: ...

      Image {
         anchors.fill: parent
         source: "reallyBigImage.jpg"
         sourceSize.width: 1024
         sourceSize.height: 1024
      }
  }

如果图像的实际大小大于sourceSize，则图像会缩小。如果只将尺寸的一个维度设置为大于0，则按比例设置其他维度，以保持源图像的长宽比。(fillMode独立于此。)

如果两个源都是。宽度和sourceSize。高度设置后，图像将被缩放以适应指定的大小(除非使用PreserveAspectCrop或PreserveAspectFit，然后它将被缩放以匹配最佳大小的裁剪/拟合)，保持图像的长宽比。缩放后的图像的实际大小可以通过Item::implicitWidth和Item::implicitHeight获得。

如果源是内在可伸缩的映像(例如。SVG)，该属性决定所加载图像的大小，而不考虑图像本身的大小。避免动态更改此属性;与图像相比，SVG的呈现速度较慢。

如果源是一个不可伸缩的映像(例如。JPEG)，加载的图像将不大于此属性指定的值。对于某些格式(目前仅为JPEG)，整个图像实际上永远不会加载到内存中。

sourceSize可以通过将sourceSize设置为undefined来清除为图像的自然大小。

注意:动态更改此属性会导致映像源重新加载，如果它不在磁盘缓存中，甚至可能从网络加载。

enumeration status

这个属性保存图像加载的状态。它可以是:
Image.Null - 没有设置映像
Image.Ready - 已加载图片
Image.Loading - 图片正在加载中
Image.Error - 加载图像时发生错误

使用此状态以某种方式提供更新或响应状态更改。例如，你可以:

• 触发状态改变:

State { name: 'loaded'; when: image.status == Image.Ready }

• 实现一个onStatusChanged信号处理程序:

  Image {
      id: image
      onStatusChanged: if (image.status == Image.Ready) console.log('Loaded')
  }

• 绑定到状态值:

 Text { text: image.status == Image.Ready ? 'Loaded' : 'Not loaded' }

参见progress.

enumeration verticalAlignment

设置图像的水平和垂直对齐。默认情况下，图像是居中对齐的。
水平对齐的有效值是Image.AlignLeft、Image.AlignRight和Image.AlignHCenter。垂直对齐的有效值是Image.AlignTop、Image.AlignBottom和Image.AlignVCenter。