Image QML Type

这些属性表示实际绘制图像的大小。在大多数情况下，它与width 和height 相同，但在使用Image.PreserveAspectFit 或Image.PreserveAspectCrop 时，paintedWidth 或paintedHeight 可以小于或大于图像项的width 和height 。

设置图像的水平和垂直对齐方式。默认情况下，图像居中对齐。

horizontalAlignment 的有效值是Image.AlignLeft,Image.AlignRight 和Image.AlignHCenter 。verticalAlignment 的有效值是Image.AlignTop 、Image.AlignBottom 和Image.AlignVCenter 。

currentFrame 是当前可见的框架。默认值为 。如果图像包含多个帧，可以将其设置为 和 之间的一个数字，以显示不同的帧。0 0 frameCount - 1

frameCount 是图像的帧数。大多数图像只有一帧。

指定本地文件系统上的图像应在单独的线程中异步加载。默认值为 false，这会导致加载图像时用户界面线程阻塞。将asynchronous 设置为 true 比立即显示图像更需要保持用户界面的响应速度。

请注意，此属性只对从本地文件系统读取的图像有效。通过网络资源（如 HTTP）加载的图像总是异步加载的。

该属性用于确定图像是否应自动应用图像转换元数据（如 EXIF 方向）。

默认情况下，此属性设置为 false。

指定是否应缓存图像。默认值为 true。在处理大型图片时，将cache 设置为 false 会很有用，这样可以确保在缓存大型图片时不会影响小型 "ui 元素 "图片。

设置此属性可定义源图像与项目大小不同时的情况。

Image {
    width: 130; height: 100
    source: "qtlogo.png"
}

Image {
    width: 130; height: 100
    fillMode: Image.PreserveAspectFit
    source: "qtlogo.png"
}

Image {
    width: 130; height: 100
    fillMode: Image.PreserveAspectCrop
    source: "qtlogo.png"
    clip: true
}

Image {
    width: 120; height: 120
    fillMode: Image.Tile
    horizontalAlignment: Image.AlignLeft
    verticalAlignment: Image.AlignTop
    source: "qtlogo.png"
}

Image {
    width: 120; height: 120
    fillMode: Image.TileVertically
    verticalAlignment: Image.AlignTop
    source: "qtlogo.png"
}

Image {
    width: 120; height: 120
    fillMode: Image.TileHorizontally
    verticalAlignment: Image.AlignLeft
    source: "qtlogo.png"
}

请注意，clip 默认为false ，这意味着即使 fillMode 设置为PreserveAspectCrop ，项目也可能绘制在其边界矩形之外。

另请参阅 Qt Quick 示例 - 图像元素。

此属性表示图像在缩放或变换时是否使用 mipmap 过滤。

与平滑滤波相比，mipmap 滤波在缩放时能提供更好的视觉质量，但可能要付出性能代价（在初始化图像和渲染时）。

默认情况下，此属性设置为 false。

另请参阅 smooth 。

该属性用于确定图像是否应水平反转（实际上是显示镜像图像）。

默认值为 false。

该属性设置图像是否应垂直反转（实际上是显示镜像图像）。

默认值为 false。

此属性在 Qt 6.2 中引入。

该属性显示图像加载的进度，从 0.0（未加载）到 1.0（已完成）。

另请参阅 status 。

该属性定义了当改变source 属性且异步加载时的行为。当asynchronous 属性设置为true 时，或图像不在本地文件系统上时，就会出现这种情况。

如果retainWhileLoading 是false （默认值），则会立即丢弃旧图片，并在加载新图片时清空组件。如果设置为true ，旧图像将保留并保持可见，直到新图像就绪。

如果加载新图像需要很长时间，启用该属性可以避免闪烁。但代价是，在加载新图像时，会因双重缓冲而占用一些额外内存。

此属性在 Qt 6.8 中引入。

在缩放或变换图像时，该属性决定是否对图像进行平滑过滤。平滑滤波可提供更好的视觉质量，但在某些硬件上可能会更慢。如果图像以自然尺寸显示，该属性不会对视觉或性能产生影响。

默认情况下，此属性设置为 true。

另请参阅 mipmap 。

Image 可以处理 Qt 支持的任何图像格式，并从 Qt 支持的任何 URL 方案中加载。

URL 可以是绝对的，也可以是相对于组件 URL 的。

另请参阅 QQuickImageProvider,Compressed Texture Files, 和Automatic Detection of File Extension 。

如果设置了该属性，它将保存要加载的源图像的矩形区域。

sourceClipRect 与sourceSize 属性配合使用，可在只需加载图片的一部分时节省系统资源。

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

    Image {
       anchors.fill: parent
       source: "reallyBigImage.svg"
       sourceSize.width: 1024
       sourceSize.height: 1024
       sourceClipRect: Qt.rect(100, 100, 512, 512)
    }
}

在上面的示例中，我们首先将 SVG 图形概念缩放为 1024x1024，然后从顶部和左侧边缘 100 像素的位置剪切出 512x512 像素的感兴趣区域。因此，sourceSize 决定了比例，但实际输出的图像是 512x512 像素。

有些图像格式可以只渲染指定区域，从而节省 CPU 时间。其他图像格式则需要先加载整个图像，然后剪切到指定区域。

可通过将sourceClipRect 设置为undefined 来清除此属性，以重新加载整个图像。

该属性保存全帧图像的宽度和高度缩放值。

与缩放图像画幅的width 和height 属性不同，该属性为加载的图像设置了最大存储像素数，这样大型图像就不会占用超出必要的内存。例如，无论图像的width 和height 值是多少，都能确保内存中的图像不大于 1024x1024 像素：

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

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

如果图像的实际尺寸大于源尺寸，图像将被缩放。如果尺寸中只有一个维度设置为大于 0，则另一个维度将按比例设置，以保持源图像的宽高比。(fillMode 与此无关）。

如果同时设置了 sourceSize.width 和 sourceSize.height，图像将被缩放到指定尺寸内（除非使用了 PreserveAspectCrop 或 PreserveAspectFit，否则图像将被缩放到与裁剪/拟合的最佳尺寸相匹配），同时保持图像的纵横比。缩放后图像的实际尺寸可通过Item::implicitWidth 和Item::implicitHeight 查看。

如果源是本质上可缩放的图像（如 SVG），则无论本质大小如何，该属性都将决定加载图像的大小。请避免动态更改此属性；与图像相比，渲染 SVG 的速度很慢。

如果来源是不可缩放的图像（如 JPEG），加载的图像将不会大于此属性指定的大小。对于某些格式（目前只有 JPEG），整个图像实际上永远不会加载到内存中。

如果sourceClipRect 属性也被设置，sourceSize 将决定缩放比例，但缩放比例将被剪切为剪切矩形的大小。

通过将 sourceSize 设置为undefined ，可以将 sourceSize 清除为图像的自然尺寸。

另请参阅 Qt Quick 示例 - 指针处理程序。

该属性显示图像加载的状态。它可以是

使用此状态提供更新或以某种方式对状态变化做出响应。例如，您可以

• 触发状态更改：

  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 。