class QQuickImageProvider#

QQuickImageProvider 类为 QML 提供了一个接口，用于支持位图和线程化图像请求。更多...

Inheritance diagram of PySide6.QtQuick.QQuickImageProvider

继承自： QQuickAsyncImageProvider

概要#

方法#

虚函数#

注意

本文档可能包含从 C++ 自动翻译到 Python 的代码片段。我们始终欢迎对片段翻译的贡献。如果您发现翻译有问题，也可以通过在 https:/bugreports.qt.io/projects/PYSIDE 上创建工单来告诉我们。

详细描述#

警告

本节包含从 C++ 自动翻译到 Python 的代码片段，可能包含错误。

QQuickImageProvider 用于在 QML 应用程序中提供高级图像加载功能。它允许 QML 中的图像

  • 使用 Q_PIXMAP 而不是实际图像文件进行加载

  • 在单独的线程中异步加载

要指定由图像提供程序加载图像，请使用图像的 URL 源的 “image:” 方案，后跟图像提供程序标识符和请求的图像。例如

这指定图像应由名为 “myimageprovider” 的图像提供程序加载，要加载的图像名为 "image.png"。QML 引擎根据通过 QQmlEngine::addImageProvider() 注册的提供程序来调用相应的图像提供程序。

请注意，标识符不区分大小写，但 URL 的其余部分将以保留大小写的方式传递。例如，下面的代码片段仍然指定图像应由名为 "myimageprovider" 的图像提供程序加载，但它将请求与上面代码片段不同的图像（"Image.png" 而不是 "image.png"）。

如果您想使 URL 的其余部分不区分大小写，则必须在您的图像提供程序内部自行处理。

示例#

这里有两个图像。它们的 source 值指示它们应被名为“colors”的图像提供程序加载，要加载的图像分别是“yellow”和“red”。

Column {
    Image { source: "image://colors/yellow" }
    Image { source: "image://colors/red" }
}

当使用QML加载这些图像时，它会查找匹配的图像提供者，并调用其 requestImage() 或 requestPixmap() 方法（取决于其 imageType()）来加载图像。该方法调用时，将 id 参数设置为第一个图像的“yellow”，第二个图像的“red”。

以下是一个图像提供者实现示例，该示例可以加载上述QML请求的图像。此实现动态生成填充了请求颜色的 QPixmap 图像。

class ColorImageProvider(QQuickImageProvider):

# public
    ColorImageProvider()
    super().__init__(.Pixmap)


    QPixmap requestPixmap(QString id, QSize size, QSize requestedSize) override

       width = 100
       height = 50
       if size:
          size = QSize(width, height)
       QPixmap pixmap(requestedSize.width() > 0 if requestedSize.width() else width,
                      requestedSize.height() > 0 if requestedSize.height() else height)
       pixmap.fill(QColor(id).rgba())
       return pixmap

要使此提供者对 QML 可用，需要使用“colors”标识符将其注册到 QML 引擎中。

if __name__ == "__main__":

view = QQuickView()
engine = view.engine()
engine.addImageProvider("colors", ColorImageProvider())
view.setSource(QUrl.fromLocalFile("imageprovider-example.qml"))
view.show()
sys.exit(app.exec())

现在可以在 QML 中成功加载这些图像。

../../_images/imageprovider.png

请参阅 图像提供者示例 获取完整实现。注意，该示例通过插件而不是如上所述在应用程序 main() 函数中注册提供者。

异步图像加载#

支持 QImage 或 Texture 加载的图像提供者自动包括对异步图像加载的支持。要启用图像源异步加载，请将相关 Image 或 BorderImage 对象的 asynchronous 属性设置为 true。启用此功能后，对提供者的图像请求将在低优先级线程中运行，允许在后台执行图像加载，并减少对用户界面的性能影响。

如果需要对图像源强制进行异步加载，即使没有将 asynchronous 属性设置为 true 的图像源，也可以在图像提供者构造函数中传递 QQmlImageProviderBase::ForceAsynchronousImageLoading 标志。这确保了所有图像请求都由单独的线程处理。

仅在没有 ThreadedPixmaps 功能的平台中支持使用 QPixmap 的图像提供者的异步加载，在这些平台上，只有在将 asynchronous 设置为 true 时，如果设置了 asynchronous，则其值会被忽略，并且图像会以同步方式加载。

除了 ImageResponse 类型的提供者之外，异步加载是在每个引擎的单个工作线程中执行的。这意味着一个慢速的图像提供者会阻止任何其他请求的加载。为了避免这种情况，我们建议使用 QQuickAsyncImageProvider 并在提供者端通过 QThreadPool 或类似方式实现多线程。请参阅 图像响应提供者示例 获取完整实现。

图像缓存#

由 QQuickImageProvider 返回的图片会自动缓存，类似于 QML 引擎加载的任何图片。当从缓存中加载以 “image://” 前缀开头的图片时，不会调用相关图像提供者的 requestImage() 和 requestPixmap() 方法。如果图片始终需要从图像提供者获取，并且不应完全缓存，可以将相关 Image 或 BorderImage 对象的 cache 属性设置为 false。

__init__(type[, flags=QQmlImageProviderBase.Flags()])#
参数：

创建一个图像提供者，它将提供给定 type 的图片并以给定的 flags 行为。

requestImage(id, size, requestedSize)#
参数：

  • id – str

  • size – QSize

  • requestedSize – QSize

返回类型：:

QImage

实现此方法以返回具有 id 的图片。默认实现返回一个空图像。

id 是请求的图片源，已移除 “image:” 方案和提供者标识符。例如，如果图像 source 为 “image://myprovider/icons/home”，则给定的 id 为 “icons/home”。

requestedSize 与 Image 项目请求的 Image::sourceSize 相对应。如果 requestedSize 是一个有效的大小，则返回的图片应为该大小。

在任何情况下，size必须设置为图像的原始大小。这用于设置相关宽度和高度，如果这些值尚未显式设置。

注意

该方法可能由多个线程调用，因此请确保该方法的实现是可重入的。

requestPixmap(id, size, requestedSize)#
参数：

  • id – str

  • size – QSize

  • requestedSize – QSize

返回类型：:

QPixmap

实现此方法以返回具有id的位图。默认实现返回空位图。

id 是请求的图片源，已移除 “image:” 方案和提供者标识符。例如，如果图像 source 为 “image://myprovider/icons/home”，则给定的 id 为 “icons/home”。

requestedSize 与 Image 项目请求的 Image::sourceSize 相对应。如果 requestedSize 是一个有效的大小，则返回的图片应为该大小。

在任何情况下，size必须设置为图像的原始大小。这用于设置相关宽度和高度，如果这些值尚未显式设置。

注意

该方法可能由多个线程调用，因此请确保该方法的实现是可重入的。

requestTexture(id, size, requestedSize)#
参数：

  • id – str

  • size – QSize

  • requestedSize – QSize

返回类型：:

QQuickTextureFactory

实现此方法以返回具有id的纹理。默认实现返回None。

id 是请求的图片源，已移除 “image:” 方案和提供者标识符。例如，如果图像 source 为 “image://myprovider/icons/home”，则给定的 id 为 “icons/home”。

requestedSize 与 Image 项目请求的 Image::sourceSize 相对应。如果 requestedSize 是一个有效的大小，则返回的图片应为该大小。

在任何情况下，size必须设置为图像的原始大小。这用于设置相关宽度和高度，如果这些值尚未显式设置。

注意

该方法可能由多个线程调用，因此请确保该方法的实现是可重入的。