图片 QML 类型

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

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

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

currentFrame是当前可见的帧。默认是0。您可以将其设置为介于0和frameCount - 1之间的数字，以显示具有多个帧的图像的不同帧。

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

指定本地文件系统上的图像应在单独的线程中异步加载。默认值为 false，导致在加载图像时阻塞用户界面线程。将 异步 设置为 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.

该属性表示当图像缩放或变换时是否进行平滑过滤。平滑过滤可以提供更好的视觉质量，但在某些硬件上可能会变慢。如果图像以自然大小显示，则此属性对视觉效果或性能没有影响。

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

另请参阅mipmap。

图像可以处理Qt支持的任何图像格式，无论是从任何Qt支持的URL方案加载。

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

另请参阅QQuickImageProvider，压缩纹理文件和自动检测文件扩展名。

如果设置此属性，则表示要加载的源图像的矩形区域。

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 来清除此属性，以便重新加载整个图像。

此属性包含图像帧的缩放后的宽度和高度。

与 宽度 和 高度 属性不同，它们缩放图像的绘制，该属性设置存储加载图像的像素数目的最大值，以防止大图像占用超过必要的内存。例如，这确保内存中的图像不大于1024x1024像素，而不管图像的 宽度 和 高度 值。

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

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

如果图像的实际大小大于 sourceSize，则图像会缩小。如果只设置大小的其中一个维度大于0，则另一个维度按比例设置以保留源图像的宽高比。（这 fillMode 不受影响。）

如果设置 sourceSize.width 和 sourceSize.height，则图像将缩小以适应指定的尺寸（除非使用 PreserveAspectCrop 或 PreserveAspectFit，然后它会按 cropping/fitting 的最佳尺寸缩放），保持图像的宽高比。缩放后图像的实际大小可通过 Item::implicitWidth 和 Item::implicitHeight 获取。

如果源是一个本质上可缩放的图像（例如SVG），此属性确定加载的图像的大小，而不考虑内在大小。请避免动态更改此属性；与图像相比，渲染SVG要慢得多。

如果源是一个非可缩放图像（例如JPEG），加载的图像将不会超过此属性指定的尺寸。对于某些格式（目前仅为JPEG），整个图像实际上永远不会被完全加载到内存中。

如果还将sourceClipRect属性设置为，则sourceSize确定缩放级别，但它将被剪裁到剪辑矩形的大小。

可以通过将sourceSize设置为undefined将其清除到图像的原始大小。

另请参阅 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。