Image QML Type
Muestra una imagen. Más...
| Import Statement: | import QtQuick |
| Inherits: | |
| Inherited By: |
Propiedades
- 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
Descripción detallada
El tipo «Imagen» muestra una imagen.
La fuente de la imagen se especifica como una URL mediante la propiedad ` source `. Las imágenes pueden proporcionarse en cualquiera de los formatos de imagen estándar compatibles con Qt, incluidos formatos de mapa de bits como PNG y JPEG, y formatos de gráficos vectoriales como SVG. Si necesitas mostrar imágenes animadas, utiliza ` AnimatedSprite ` o ` AnimatedImage`.
Si no se especifican las propiedades width y height, el objeto Image utiliza automáticamente el tamaño de la imagen cargada. De forma predeterminada, al especificar el ancho y la altura del elemento, la imagen se escala a ese tamaño. Este comportamiento puede modificarse configurando la propiedad fillMode, lo que permite que la imagen se estire y se repita en mosaico.
Es posible proporcionar un ` "@nx" high DPI syntax`.
Ejemplo de uso
El siguiente ejemplo muestra el uso más sencillo del tipo `Image`.
import QtQuick
Image {
source: "pics/qtlogo.png"
}
Archivos de textura comprimidos
Cuando la implementación de la API gráfica subyacente lo admite en tiempo de ejecución, las imágenes también pueden proporcionarse en archivos de textura comprimidos. El contenido debe ser una textura 2D en formato RGB(A) simple. Los esquemas de compresión admitidos solo están limitados por el controlador y la GPU subyacentes. Se admiten los siguientes formatos de archivo contenedor:
PKM(desde Qt 5.10)KTX(desde Qt 5.11)ASTC(desde Qt 5.13)
Nota: La orientación vertical prevista de una imagen en un archivo de textura no suele estar bien definida. Las diferentes herramientas de compresión de texturas tienen valores predeterminados y opciones distintos en cuanto a cuándo realizar el volteo vertical de la imagen de entrada. Si una imagen de un archivo de textura aparece al revés, puede que sea necesario activar o desactivar el volteo durante el proceso de acondicionamiento de los recursos. Como alternativa, el propio elemento «Image» puede voltearse aplicando una transformación adecuada mediante la propiedad «transform» o, de forma más cómoda, estableciendo la propiedad « mirrorVertically »:
transform: [ Translate { y: -myImage.height }, Scale { yScale: -1 } ]o
mirrorVertically: trueNota: Las imágenes originalessemitransparentes requieren una premultiplicación alfa antes de la compresión de la textura para que se muestren correctamente en Qt Quick. Esto se puede hacer con la siguiente línea de comandos de ImageMagick:
convert foo.png \( +clone -alpha Extract \) -channel RGB -compose Multiply -composite foo_pm.pngNo se deben confundir los formatos contenedores, como KTX, con el formato de los datos de textura reales almacenados en el archivo contenedor. Por ejemplo, la lectura de un archivo KTX es compatible en todas las plataformas, independientemente del controlador de GPU que se utilice en tiempo de ejecución. Sin embargo, esto no garantiza que el formato de textura comprimida, utilizado por los datos del archivo, sea compatible en tiempo de ejecución. Por ejemplo, si el archivo KTX contiene datos comprimidos con el formato ETC2 RGBA8 y la implementación de la API de gráficos 3D utilizada en tiempo de ejecución no admite texturas comprimidas ETC2, el elemento Image no mostrará nada.
Nota: La compatibilidad con el formato de texturacomprimida no está bajo el control de Qt, y corresponde al desarrollador de la aplicación o del dispositivo garantizar que los datos de textura comprimida se proporcionen en el formato adecuado para los entornos de destino.
No se debe dar por sentado que la compatibilidad con formatos comprimidos es específica de una plataforma. También puede depender del controlador y de la implementación de la API 3D que se utilice en esa plataforma concreta. En la práctica, las implementaciones de diferentes API de gráficos 3D (por ejemplo, Vulkan y OpenGL) en la misma plataforma (por ejemplo, Windows) del mismo proveedor para el mismo hardware pueden ofrecer un conjunto diferente de formatos de texturas comprimidas.
Cuando se dirigen únicamente a entornos de escritorio (Windows, macOS, Linux), una recomendación general es considerar el uso de los formatos DXTn/BCn, ya que estos suelen contar con la mayor compatibilidad entre las implementaciones de Direct 3D, Vulkan, OpenGL y Metal en estas plataformas. Por el contrario, cuando se trabaja con dispositivos móviles o integrados, es probable que los formatos ETC2 o ASTC sean una mejor opción, ya que suelen ser los formatos compatibles con las implementaciones de OpenGL ES en dicho hardware.
Una aplicación que pretenda ejecutarse en equipos de sobremesa, dispositivos móviles y hardware integrado debe planificar y diseñar cuidadosamente el uso de texturas comprimidas. Es muy probable que no basarse en un único formato resulte insuficiente y, por lo tanto, es probable que la aplicación tenga que adaptarse según la plataforma para utilizar texturas comprimidas en el formato adecuado para cada caso, o tal vez prescindir de ellas en algunos casos.
Detección automática de la extensión de archivo
Si la URL source apunta a un archivo o recurso local inexistente, el elemento Image intenta detectar automáticamente la extensión del archivo. Si se encuentra un archivo existente añadiendo cualquiera de las extensiones de archivo de imagen compatibles a la URL source, se cargará dicho archivo.
La búsqueda de archivos intenta buscar primero las extensiones de los archivos contenedores de texturas comprimidas. Si la búsqueda no da resultado, intenta buscar con las extensiones de archivo de conventional image file types. Por ejemplo:
// 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.
}Esta funcionalidad facilita la implementación de diferentes tipos de archivos de recursos de imagen en distintas plataformas de destino. Esto puede resultar útil para optimizar el rendimiento de la aplicación y adaptarse a diferentes tipos de hardware gráfico.
Esta funcionalidad se introdujo en Qt 5.11.
Rendimiento
Por defecto, las imágenes disponibles localmente se cargan inmediatamente y la interfaz de usuario queda bloqueada hasta que finaliza la carga. Si se va a cargar una imagen de gran tamaño, puede ser preferible cargarla en un hilo de baja prioridad, activando la propiedad ` asynchronous `.
Si la imagen se obtiene de una red en lugar de un recurso local, se carga automáticamente de forma asíncrona, y las propiedades ` progress ` y ` status ` se actualizan según corresponda.
Las imágenes se almacenan en caché y se comparten internamente, por lo que si varios elementos Image tienen el mismo source, solo se cargará una copia de la imagen.
Nota: Las imágenes suelen ser las que más memoria consumen en las interfaces de usuario de QML. Se recomienda limitar el tamaño de las imágenes que no forman parte de la interfaz de usuario mediante la propiedad sourceSize. Esto es especialmente importante para el contenido que se carga desde fuentes externas o que proporciona el usuario.
Véase también Ejemplos de «Qt Quick » - Elementos de imagen, QQuickImageProvider y QImageReader::setAutoDetectImageFormat().
Documentación de la propiedad
asynchronous : bool
Especifica que las imágenes del sistema de archivos local deben cargarse de forma asíncrona en un hilo independiente. El valor por defecto es «false», lo que provoca que el hilo de la interfaz de usuario se bloquee mientras se carga la imagen. Establecer « asynchronous » en «true» resulta útil cuando es más importante mantener una interfaz de usuario con buena capacidad de respuesta que tener las imágenes visibles de inmediato.
Ten en cuenta que esta propiedad solo es válida para imágenes leídas desde el sistema de archivos local. Las imágenes cargadas a través de un recurso de red (por ejemplo, HTTP) siempre se cargan de forma asíncrona.
autoTransform : bool
Esta propiedad determina si la imagen debe aplicar automáticamente metadatos de transformación de imagen, como la orientación EXIF.
Por defecto, esta propiedad está establecida en «false».
cache : bool
Especifica si la imagen debe almacenarse en caché. El valor por defecto es «true». Establecer « cache » en «false» resulta útil cuando se trabaja con imágenes de gran tamaño, para garantizar que no se almacenen en caché a expensas de las imágenes pequeñas de los «elementos de interfaz de usuario».
currentFrame es el fotograma que se ve actualmente. El valor por defecto es 0. Puedes establecerlo en un número comprendido entre 0 y frameCount - 1 para mostrar un fotograma diferente, si la imagen contiene varios fotogramas.
frameCount es el número de fotogramas de la imagen. La mayoría de las imágenes solo tienen un fotograma.
fillMode : enumeration
Establece esta propiedad para definir qué ocurre cuando la imagen de origen tiene un tamaño diferente al del elemento.
| Constante | Descripción |
|---|---|
Image.Stretch | la imagen se escala para ajustarse |
Image.PreserveAspectFit | la imagen se escala uniformemente para ajustarse sin recortarla |
Image.PreserveAspectCrop | la imagen se escala uniformemente para ocupar todo el espacio, recortándola si es necesario |
Image.Tile | la imagen se duplica horizontal y verticalmente |
Image.TileVertically | la imagen se estira horizontalmente y se repite verticalmente |
Image.TileHorizontally | la imagen se estira verticalmente y se repite horizontalmente |
Image.Pad | la imagen no se transforma |
| Estirar (por defecto) |
| Ajustar conservando la relación de aspecto |
| Recortar para conservar la relación de aspecto |
| Mosaico |
| Alinear verticalmente |
| Mosaico horizontal |
Ten en cuenta que ` clip ` es ` false ` por defecto, lo que significa que el elemento podría dibujarse fuera de su rectángulo delimitador incluso si el modo de relleno (`fillMode`) está establecido en ` PreserveAspectCrop`.
Véase también Ejemplos de «Qt Quick » - Elementos de imagen.
Establece la alineación horizontal y vertical de la imagen. Por defecto, la imagen se alinea en el centro.
Los valores válidos para « horizontalAlignment » son « Image.AlignLeft », « Image.AlignRight » y « Image.AlignHCenter ». Los valores válidos para « verticalAlignment » son « Image.AlignTop », « Image.AlignBottom » y « Image.AlignVCenter ».
mipmap : bool
Esta propiedad se mantiene independientemente de si la imagen utiliza filtrado mipmap al escalarse o transformarse.
El filtrado mipmap ofrece una mejor calidad visual al reducir la escala en comparación con el suavizado, pero puede suponer un coste en cuanto al rendimiento (tanto al inicializar la imagen como durante el renderizado).
Por defecto, esta propiedad está establecida en «false».
Véase también smooth.
mirror : bool
Esta propiedad determina si la imagen debe invertirse horizontalmente (mostrando, en la práctica, una imagen especular).
El valor por defecto es «false».
mirrorVertically : bool [since 6.2]
Esta propiedad determina si la imagen debe invertirse verticalmente (mostrando, en la práctica, una imagen especular).
El valor por defecto es «false».
Esta propiedad se introdujo en Qt 6.2.
Estas propiedades contienen el tamaño de la imagen que se dibuja realmente. En la mayoría de los casos, coincide con width y height, pero cuando se utiliza un Image.PreserveAspectFit o un Image.PreserveAspectCrop, paintedWidth o paintedHeight pueden ser más pequeños o más grandes que width y height del elemento «Imagen».
progress : real [read-only]
Esta propiedad indica el progreso de la carga de la imagen, desde 0,0 (no se ha cargado nada) hasta 1,0 (finalizada).
Véase también status.
retainWhileLoading : bool [since 6.8]
Esta propiedad define el comportamiento cuando se modifica la propiedad « source » y la carga se realiza de forma asíncrona. Esto ocurre cuando la propiedad « asynchronous » se establece en « true », o si la imagen no se encuentra en el sistema de archivos local.
Si retainWhileLoading es false (el valor por defecto), la imagen anterior se descarta inmediatamente y el componente se borra mientras se carga la nueva imagen. Si se establece en true, la imagen anterior se conserva y permanece visible hasta que la nueva esté lista.
Habilitar esta propiedad puede evitar el parpadeo en los casos en que la carga de la nueva imagen tarde mucho tiempo. Esto conlleva un mayor consumo de memoria debido al doble búfer mientras se carga la nueva imagen.
Esta propiedad se introdujo en Qt 6.8.
smooth : bool
Esta propiedad determina si la imagen se filtra de forma suave al escalarse o transformarse. El filtrado suave ofrece una mejor calidad visual, pero puede ralentizar el proceso en algunos equipos. Si la imagen se muestra a su tamaño natural, esta propiedad no tiene ningún efecto ni en la calidad visual ni en el rendimiento.
De forma predeterminada, esta propiedad está establecida en «true».
Véase también mipmap.
source : url
Image puede gestionar cualquier formato de imagen compatible con Qt, cargado desde cualquier esquema de URL compatible con Qt.
La URL puede ser absoluta o relativa a la URL del componente.
Véase también QQuickImageProvider, Compressed Texture Files y Automatic Detection of File Extension.
sourceClipRect : rect
Esta propiedad, si se configura, define la región rectangular de la imagen de origen que se va a cargar.
La propiedad « sourceClipRect » funciona junto con la propiedad « sourceSize » para ahorrar recursos del sistema cuando solo es necesario cargar una parte de la imagen.
Rectangle {
width: ...
height: ...
Image {
anchors.fill: parent
source: "reallyBigImage.svg"
sourceSize.width: 1024
sourceSize.height: 1024
sourceClipRect: Qt.rect(100, 100, 512, 512)
}
}En el ejemplo anterior, primero escalamos conceptualmente el gráfico SVG a 1024x1024 y, a continuación, recortamos una región de interés de 512x512 píxeles a partir de una ubicación situada a 100 píxeles de los bordes superior e izquierdo. De este modo, ` sourceSize ` determina la escala, pero la imagen de salida real es de 512x512 píxeles.
Algunos formatos de imagen permiten ahorrar tiempo de CPU al renderizar únicamente la región especificada. Otros necesitarán cargar primero la imagen completa y, a continuación, recortarla a la región especificada.
Esta propiedad se puede desactivar para recargar la imagen completa estableciendo sourceClipRect en undefined.
Nota: Cambiar esta propiedad de forma dinámica provoca que se vuelva a cargar la fuente de la imagen, incluso desde la red, si no se encuentra en la caché del disco.
Nota: No se admite el recortesubpíxel : el rectángulo indicado se pasará a ` QImageReader::setScaledClipRect()`.
sourceSize : size
Esta propiedad contiene el ancho y la altura, ya escalados, de la imagen a pantalla completa.
A diferencia de las propiedades ` width ` y ` height `, que escalan el dibujo de la imagen, esta propiedad establece el número máximo de píxeles almacenados para la imagen cargada, de modo que las imágenes grandes no utilicen más memoria de la necesaria. Por ejemplo, esto garantiza que la imagen en memoria no supere los 1024x1024 píxeles, independientemente de los valores de ` width ` y ` height ` del objeto `Image`:
Rectangle {
width: ...
height: ...
Image {
anchors.fill: parent
source: "reallyBigImage.jpg"
sourceSize.width: 1024
sourceSize.height: 1024
}
}Si el tamaño real de la imagen es mayor que sourceSize, la imagen se reduce. Si solo una de las dimensiones del tamaño se establece en un valor superior a 0, la otra dimensión se ajusta proporcionalmente para conservar la relación de aspecto de la imagen original. (La opción « fillMode » es independiente de esto.)
Si se establecen tanto sourceSize.width como sourceSize.height, la imagen se reducirá para ajustarse al tamaño especificado (a menos que se utilicen PreserveAspectCrop o PreserveAspectFit, en cuyo caso se escalará para adaptarse al tamaño óptimo para el recorte o el ajuste), manteniendo la relación de aspecto de la imagen. El tamaño real de la imagen tras el escalado se puede consultar mediante Item::implicitWidth y Item::implicitHeight.
Si la fuente es una imagen intrínsecamente escalable (por ejemplo, SVG), esta propiedad determina el tamaño de la imagen cargada independientemente de su tamaño intrínseco. Evita modificar esta propiedad de forma dinámica; la representación de un SVG es lenta en comparación con la de una imagen.
Si la fuente es una imagen no escalable (p. ej., JPEG), la imagen cargada no superará el tamaño especificado por esta propiedad. En algunos formatos (actualmente solo JPEG), la imagen completa nunca se cargará realmente en la memoria.
Si también se establece la propiedad « sourceClipRect », « sourceSize » determina la escala, pero se recortará al tamaño del rectángulo de recorte.
Se puede restablecer el tamaño natural de la imagen estableciendo `sourceSize` en ` undefined`.
Nota: Cambiar esta propiedad de forma dinámica provoca que se vuelva a cargar la fuente de la imagen, incluso desde la red si no se encuentra en la caché del disco.
Véase también Ejemplos de «Qt Quick »: controladores de puntero.
status : enumeration [read-only]
Esta propiedad indica el estado de la carga de la imagen. Puede adoptar uno de los siguientes valores:
| Constante | Descripción |
|---|---|
Image.Null | No se ha establecido ninguna imagen |
Image.Ready | La imagen se ha cargado |
Image.Loading | La imagen se está cargando actualmente |
Image.Error | Se ha producido un error al cargar la imagen |
Utiliza este estado para proporcionar una actualización o responder de alguna manera al cambio de estado. Por ejemplo, podrías:
- Provocar un cambio de estado:
State { name: 'loaded'; when: image.status == Image.Ready } - Implementar un controlador de señal `
onStatusChanged`:Image { id: image onStatusChanged: if (image.status == Image.Ready) console.log('Loaded') } - Vincularse al valor del estado:
Text { text: image.status == Image.Ready ? 'Loaded' : 'Not loaded' }
Véase también progress.
© 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.





