Image QML Type

显示一张图片。更多...

• 所有成员的列表，包括继承的成员

属性

• asynchronous : bool
• autoTransform : bool
• cache : bool
• currentFrame : int
• fillMode : enumeration
• frameCount : int
• horizontalAlignment : enumeration
• mipmap : bool
• mirror : bool
• mirrorVertically : bool (since 6.2)
• paintedHeight : real
• paintedWidth : real
• progress : real
• retainWhileLoading : bool (since 6.8)
• smooth : bool
• source : url
• sourceClipRect : rect
• sourceSize : size
• status : enumeration
• verticalAlignment : enumeration

详细说明

Image 类型用于显示图像。

图像的来源通过source 属性以URL形式指定。图像可以采用Qt支持的任何标准图像格式，包括PNG和JPEG等位图格式，以及SVG等矢量图形格式。若需显示动画图像，请使用AnimatedSprite 或AnimatedImage 。

如果未指定width 和height 属性，Image 会自动采用加载图像的尺寸。默认情况下，指定项的宽度和高度会导致图像按该尺寸缩放。通过设置fillMode 属性可以更改此行为，使图像改为拉伸和平铺显示。

可以提供"@nx" high DPI syntax 。

用法示例

以下示例展示了 Image 类型的最简单用法。

import QtQuick

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

压缩纹理文件

如果底层图形 API 的实现运行时支持，图像也可以以压缩纹理文件的形式提供。内容必须是简单的 RGB(A) 格式的 2D 纹理。支持的压缩方案仅受底层驱动程序和 GPU 的限制。支持以下容器文件格式：

• PKM （自 Qt 5.10 起）
• KTX （自 Qt 5.11 起）
• ASTC （自 Qt 5.13 起）

transform: [ Translate { y: -myImage.height }, Scale { yScale: -1 } ]

或

mirrorVertically: true

convert foo.png \( +clone -alpha Extract \) -channel RGB -compose Multiply -composite foo_pm.png

请勿将容器格式（例如KTX ）与存储在容器文件中的实际纹理数据格式混淆。例如，所有平台均支持读取KTX 文件，这与运行时使用的 GPU 驱动程序无关。但这并不能保证文件中数据所使用的压缩纹理格式在运行时受到支持。 例如，如果 KTX 文件包含格式为ETC2 RGBA8 的压缩数据，而运行时使用的 3D 图形 API 实现不支持ETC2 压缩纹理，则 Image 控件将不会显示任何内容。

请勿假设对压缩格式的支持是特定于某个平台的。它也可能取决于该特定平台上使用的驱动程序和 3D API 实现。 实际上，同一供应商针对同一硬件，在同一平台（例如 Windows）上实现的不同 3D 图形 API（例如 Vulkan 和 OpenGL）可能提供不同的压缩纹理格式集。

当仅针对桌面环境（Windows、macOS、Linux）时，一般建议考虑使用DXTn/BCn 格式，因为在这些平台上的 Direct 3D、Vulkan、OpenGL 和 Metal 实现中，这些格式通常具有最广泛的支持。 相比之下，当针对移动或嵌入式设备时，ETC2 或ASTC 格式可能是更好的选择，因为这些通常是此类硬件上 OpenGL ES 实现所支持的格式。

打算在桌面、移动和嵌入式硬件上运行的应用程序，应谨慎规划和设计压缩纹理的使用。 仅依赖一种格式很可能是不够的，因此应用程序可能需要根据平台进行分支处理，以使用适合该平台的压缩纹理格式，或者在某些情况下跳过使用压缩纹理。

文件扩展名的自动检测

如果source URL 指向一个不存在的本地文件或资源，Image 元素会尝试自动检测文件扩展名。如果在source URL 后附加任何受支持的图像文件扩展名后能找到现有文件，则将加载该文件。

文件搜索会首先尝试查找压缩纹理容器文件扩展名。如果搜索未果，则会尝试使用conventional image file types 对应的文件扩展名进行搜索。例如：

// Assuming the "pics" directory contains the following files:
//   dog.jpg
//   cat.png
//   cat.pkm

Image {
    source: "pics/cat.png"     // loads cat.png
}

Image {
    source: "pics/dog"         // loads dog.jpg
}

Image {
    source: "pics/cat"         // normally loads cat.pkm, but if no OpenGL, loads cat.png instead.
}

此功能便于在不同的目标平台上部署不同类型的图像资源文件。这有助于优化应用程序性能并适应不同的图形硬件。

该功能于 Qt 5.11 版本中引入。

性能

默认情况下，本地可用图像会立即加载，且用户界面将处于阻塞状态直至加载完成。若需加载大尺寸图像，建议通过启用asynchronous 属性，在低优先级线程中加载该图像。

如果图像是从网络而非本地资源获取的，则会自动以异步方式加载，并且会根据需要更新progress 和status 属性。

图像会在内部进行缓存和共享，因此如果多个 Image 项具有相同的source ，则只会加载该图像的一份副本。

注意：在 QML 用户界面中，图像通常是占用内存最多的组件。建议通过sourceSize 属性限制不属于用户界面一部分的图像的大小。对于从外部源加载或由用户提供的内容，这一点尤为重要。

另请参阅 《Qt Quick 示例——图像元素》（ QQuickImageProvider ）以及QImageReader::setAutoDetectImageFormat()。

属性文档

asynchronous : bool

指定应通过单独的线程异步加载本地文件系统中的图像。默认值为 false，这会导致在加载图像时用户界面线程被阻塞。当保持用户界面的响应性比立即显示图像更为重要时，将 `asynchronous ` 设置为 true 会很有帮助。

请注意，此属性仅对从本地文件系统读取的图像有效。通过网络资源（例如 HTTP）加载的图像始终以异步方式加载。

autoTransform : bool

此属性用于指定图像是否应自动应用图像变换元数据（例如 EXIF 方向信息）。

默认情况下，此属性的值为 false。

cache : bool

指定是否应缓存该图像。默认值为 true。在处理大尺寸图像时，将 `cache ` 设置为 false 很有用，这样可以确保不会为了缓存这些大图像而牺牲小尺寸的“UI 元素”图像的缓存空间。

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

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

fillMode : enumeration

设置此属性以定义当源图像的尺寸与项目不同时应如何处理。

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 示例——图像元素”。

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

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

mipmap : bool

无论在缩放还是变换时，该属性都决定图像是否使用Mipmap过滤。

与“平滑”选项相比，Mipmap 过滤在缩小图像时能提供更好的视觉质量，但可能会牺牲性能（无论是在初始化图像时还是在渲染过程中）。

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

另请参阅 smooth 。

mirror : bool

此属性用于控制是否应将图像水平翻转（即实际显示镜像图像）。

默认值为 false。

mirrorVertically : bool [since 6.2]

此属性用于指定是否应将图像垂直翻转（实际上显示镜像图像）。

默认值为 false。

该属性在 Qt 6.2 中引入。

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

progress : real [read-only]

该属性用于表示图片加载的进度，范围从 0.0（尚未加载）到 1.0（加载完成）。

另请参阅 status 。

retainWhileLoading : bool [since 6.8]

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

如果retainWhileLoading 为false （默认值），则旧图像将立即被丢弃，并在加载新图像期间清空组件。如果设置为true ，则保留旧图像，并使其保持可见，直到新图像准备就绪。

启用此属性可在加载新图像耗时较长的情况下避免画面闪烁。其代价是在加载新图像期间，双缓冲机制会占用额外的内存。

该属性于 Qt 6.8 中引入。

smooth : bool

该属性控制图像在缩放或变换时是否进行平滑滤波。平滑滤波可提供更好的视觉效果，但在某些硬件上可能会降低运行速度。如果图像以原始尺寸显示，则该属性不会对视觉效果或性能产生影响。

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

另请参阅 mipmap 。

source : url

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

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

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

sourceClipRect : rect

如果设置了此属性，它将指定要加载的源图像的矩形区域。

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

sourceSize : size

该属性存储全画幅图像的缩放后宽度和高度。

与用于缩放图像绘制的width 和height 属性不同，该属性用于设置已加载图像存储的最大像素数，以避免大图像占用超过必要的内存。例如，无论Image对象的width 和height 值为何，这都能确保内存中的图像大小不超过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，此时图像将被缩放以匹配裁剪/适配的最佳尺寸），同时保持图像的宽高比。 缩放后图像的实际尺寸可通过Item::implicitWidth 和Item::implicitHeight 获取。

如果源文件是本质上可缩放的图像（例如 SVG），则该属性将决定加载后图像的大小，无论其原始尺寸如何。请避免动态更改此属性；与普通图像相比，渲染 SVG 的速度较慢。

如果源是不可缩放的图像（例如 JPEG），则加载的图像大小不会超过此属性指定的值。对于某些格式（目前仅限 JPEG），整个图像实际上永远不会被加载到内存中。

如果同时设置了sourceClipRect 属性，则sourceSize 将决定缩放比例，但图像会被裁剪为裁剪矩形的大小。

可以通过将 sourceSize 设置为undefined 来将其重置为图像的原始尺寸。

另请参阅 《Qt Quick 示例——指针处理程序》。

status : enumeration [read-only]

该属性表示图像的加载状态。其取值可以是以下之一：

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

• 触发状态变更：

  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 。