En esta página

QQuickImageProvider Class

La clase QQuickImageProvider ofrece una interfaz para gestionar mapas de píxeles y solicitudes de imágenes en subprocesos en QML. Más información...

Encabezado: #include <QQuickImageProvider>
CMake: find_package(Qt6 REQUIRED COMPONENTS Quick)
target_link_libraries(mytarget PRIVATE Qt6::Quick)
qmake: QT += quick
Heredado de: QQmlImageProviderBase
Heredado por:

QQuickAsyncImageProvider

Funciones públicas

QQuickImageProvider(QQmlImageProviderBase::ImageType type, QQmlImageProviderBase::Flags flags = Flags())
virtual ~QQuickImageProvider() override
virtual QImage requestImage(const QString &id, QSize *size, const QSize &requestedSize)
virtual QPixmap requestPixmap(const QString &id, QSize *size, const QSize &requestedSize)
virtual QQuickTextureFactory *requestTexture(const QString &id, QSize *size, const QSize &requestedSize)

Funciones públicas reimplementadas

virtual QQmlImageProviderBase::Flags flags() const override
virtual QQmlImageProviderBase::ImageType imageType() const override

Descripción detallada

QQuickImageProvider se utiliza para proporcionar funciones avanzadas de carga de imágenes en aplicaciones QML. Permite que las imágenes en QML:

  • Carguen mediante QPixmaps en lugar de archivos de imagen reales
  • Carguen de forma asíncrona en un hilo independiente

Para especificar que una imagen debe ser cargada por un proveedor de imágenes, utiliza el esquema «image:» para la URL de origen de la imagen, seguido de los identificadores del proveedor de imágenes y de la imagen solicitada. Por ejemplo:

Image { source: "image://myimageprovider/image.png" }

Esto especifica que la imagen debe ser cargada por el proveedor de imágenes denominado «myimageprovider», y que la imagen que se va a cargar se llama «image.png». El motor QML invoca al proveedor de imágenes adecuado según los proveedores que se hayan registrado mediante QQmlEngine::addImageProvider().

Ten en cuenta que los identificadores no distinguen entre mayúsculas y minúsculas, pero el resto de la URL se transmitirá conservando las mayúsculas y minúsculas. Por ejemplo, el fragmento de código siguiente seguiría especificando que la imagen se carga mediante el proveedor de imágenes denominado «myimageprovider», pero solicitaría una imagen diferente a la del fragmento anterior («Image.png» en lugar de «image.png»).

Image { source: "image://MyImageProvider/Image.png" }

Si deseas que el resto de la URL no distinga entre mayúsculas y minúsculas, tendrás que encargarte de ello tú mismo dentro de tu proveedor de imágenes.

Un ejemplo

Aquí hay dos imágenes. Sus valores source indican que deben ser cargadas por un proveedor de imágenes llamado «colors», y las imágenes que se van a cargar son «yellow» y «red», respectivamente:

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

Cuando QML carga estas imágenes, busca un proveedor de imágenes que coincida y llama a su método requestImage() o requestPixmap() (dependiendo de su imageType()) para cargar la imagen. El método se invoca con el parámetro id establecido en «yellow» para la primera imagen y en «red» para la segunda.

A continuación se muestra una implementación del proveedor de imágenes capaz de cargar las imágenes solicitadas por el código QML anterior. Esta implementación genera dinámicamente imágenes QPixmap rellenas con el color solicitado:

class ColorImageProvider : public QQuickImageProvider
{
public:
    ColorImageProvider()
               : QQuickImageProvider(QQuickImageProvider::Pixmap)
    {
    }

    QPixmap requestPixmap(const QString &id, QSize *size, const QSize &requestedSize) override
    {
       int width = 100;
       int height = 50;

       if (size)
          *size = QSize(width, height);
       QPixmap pixmap(requestedSize.width() > 0 ? requestedSize.width() : width,
                      requestedSize.height() > 0 ? requestedSize.height() : height);
       pixmap.fill(QColor(id).rgba());
       return pixmap;
    }
};

Para que este proveedor sea accesible desde QML, se registra en el motor QML con el identificador «colors»:

int main(int argc, char *argv[])
{

    QQuickView view;
    QQmlEngine *engine = view.engine();
    engine->addImageProvider(QLatin1String("colors"), new ColorImageProvider);
    view.setSource(QUrl::fromLocalFile(QStringLiteral("imageprovider-example.qml")));
    view.show();
    return app.exec();
}

Ahora las imágenes se pueden cargar correctamente en QML:

Rectángulo con la mitad superior amarilla y la mitad inferior roja, procedente de un proveedor de imágenes

Consulta el ejemplo de proveedor de imágenes para ver la implementación completa. Ten en cuenta que el ejemplo registra el proveedor a través de un ` plugin `, en lugar de registrarlo en la función ` main() ` de la aplicación, como se muestra más arriba.

Es posible proporcionar un ` "@nx" high DPI syntax`.

Carga asíncrona de imágenes

Los proveedores de imágenes que admiten la carga de « QImage » o de texturas incluyen automáticamente la compatibilidad con la carga asíncrona de imágenes. Para habilitar la carga asíncrona de una fuente de imagen, establezca la propiedad ` asynchronous ` en ` true ` para el objeto ` Image ` o ` BorderImage ` correspondiente. Cuando esta opción está habilitada, la solicitud de imagen al proveedor se ejecuta en un hilo de baja prioridad, lo que permite que la carga de la imagen se realice en segundo plano y reduce el impacto en el rendimiento de la interfaz de usuario.

Para forzar la carga asíncrona de imágenes, incluso en el caso de fuentes de imágenes que no tengan la propiedad ` asynchronous ` establecida en ` true`, puede pasar el indicador ` QQmlImageProviderBase::ForceAsynchronousImageLoading ` al constructor del proveedor de imágenes. Esto garantiza que todas las solicitudes de imágenes para el proveedor se gestionen en un hilo independiente.

La carga asíncrona para proveedores de imágenes que ofrecen QPixmap solo es compatible en plataformas que cuenten con la función ThreadedPixmaps; en plataformas donde los pixmaps solo se pueden crear en el hilo principal (es decir, donde no se admite ThreadedPixmaps), si asynchronous está establecido en true, el valor se ignora y la imagen se carga de forma síncrona.

La carga asíncrona de imágenes para proveedores de un tipo distinto a ImageResponse se ejecuta en un único hilo por motor. Esto significa que un proveedor de imágenes lento bloqueará la carga de cualquier otra solicitud. Para evitarlo, recomendamos utilizar QQuickAsyncImageProvider e implementar el uso de hilos en el lado del proveedor mediante QThreadPool o similar. Consulte el ejemplo de proveedor de respuestas de imagen para ver una implementación completa.

Almacenamiento en caché de imágenes

Las imágenes devueltas por un QQuickImageProvider se almacenan automáticamente en caché, al igual que cualquier imagen cargada por el motor QML. Cuando se carga desde la caché una imagen con el prefijo «image://», no se llamarán a los métodos requestImage() ni requestPixmap() para el proveedor de imágenes correspondiente. Si se desea que una imagen se recupere siempre del proveedor de imágenes y no se almacene en caché en absoluto, establezca la propiedad « cache » en « false » para el objeto « Image » o « BorderImage » correspondiente.

Véase también QQmlEngine::addImageProvider().

Documentación de la función miembro

QQuickImageProvider::QQuickImageProvider(QQmlImageProviderBase::ImageType type, QQmlImageProviderBase::Flags flags = Flags())

Crea un proveedor de imágenes que proporcionará imágenes según la configuración especificada en type y se comportará de acuerdo con lo indicado en flags.

[override virtual noexcept] QQuickImageProvider::~QQuickImageProvider()

Destruye el QQuickImageProvider

Nota: El destructor de tu clase derivada debe ser seguro para subprocesos.

[override virtual] QQmlImageProviderBase::Flags QQuickImageProvider::flags() const

Reimplementa: ` QQmlImageProviderBase::flags()` const.

Devuelve los indicadores establecidos para este proveedor.

[override virtual] QQmlImageProviderBase::ImageType QQuickImageProvider::imageType() const

Reimplementa: ` QQmlImageProviderBase::imageType()` const.

Devuelve el tipo de imagen compatible con este proveedor.

[virtual] QImage QQuickImageProvider::requestImage(const QString &id, QSize *size, const QSize &requestedSize)

Implementa este método para devolver la imagen con id. La implementación por defecto devuelve una imagen vacía.

El id es la fuente de la imagen solicitada, sin el esquema «image:» ni el identificador del proveedor. Por ejemplo, si la imagen source fuera «image://myprovider/icons/home», el id dado sería «icons/home».

El parámetro « requestedSize » corresponde a la « Image::sourceSize » solicitada por un elemento «Image». Si « requestedSize » es un tamaño válido, la imagen devuelta debería tener ese tamaño.

En todos los casos, size debe establecerse en el tamaño original de la imagen. Esto se utiliza para establecer width e height de la Image correspondiente si estos valores no se han establecido explícitamente.

Nota: este método puede ser invocado por varios subprocesos, por lo que debe asegurarse de que su implementación sea reentrante.

[virtual] QPixmap QQuickImageProvider::requestPixmap(const QString &id, QSize *size, const QSize &requestedSize)

Implementa este método para devolver el mapa de píxeles con ` id`. La implementación por defecto devuelve un mapa de píxeles vacío.

El id es la fuente de la imagen solicitada, sin el esquema «image:» ni el identificador del proveedor. Por ejemplo, si la imagen source fuera «image://myprovider/icons/home», el id dado sería «icons/home».

El requestedSize corresponde al Image::sourceSize solicitado por un elemento Image. Si requestedSize es un tamaño válido, la imagen devuelta debería tener ese tamaño.

En todos los casos, size debe establecerse en el tamaño original de la imagen. Esto se utiliza para establecer width e height del Image correspondiente si estos valores no se han establecido explícitamente.

Nota: este método puede ser invocado por varios subprocesos, por lo que hay que asegurarse de que su implementación sea reentrante.

[virtual] QQuickTextureFactory *QQuickImageProvider::requestTexture(const QString &id, QSize *size, const QSize &requestedSize)

Implementa este método para devolver la textura con id. La implementación por defecto devuelve nullptr.

El id es la fuente de la imagen solicitada, sin el esquema «image:» ni el identificador del proveedor. Por ejemplo, si la imagen source fuera «image://myprovider/icons/home», el id resultante sería «icons/home».

La propiedad « requestedSize » corresponde a la propiedad « Image::sourceSize » solicitada por un elemento «Image». Si « requestedSize » es un tamaño válido, la imagen devuelta debería tener ese tamaño.

En todos los casos, size debe establecerse en el tamaño original de la imagen. Esto se utiliza para establecer width y height de la Image correspondiente si estos valores no se han establecido explícitamente.

Nota: este método puede ser invocado por varios subprocesos, por lo que hay que asegurarse de que su implementación sea reentrante.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.