BorderImage QML Type
Dibuja un borde a partir de una imagen. Más...
| Import Statement: | import QtQuick |
| Inherits: |
Propiedades
- asynchronous : bool
- border
- border.bottom : int
- border.left : int
- border.right : int
- border.top : int
- cache : bool
- currentFrame : int
- frameCount : int
- horizontalTileMode : enumeration
- mirror : bool
- progress : real
- retainWhileLoading : bool
(since 6.8) - smooth : bool
- source : url
- sourceSize : size
- status : enumeration
- verticalTileMode : enumeration
Descripción detallada
El tipo BorderImage se utiliza para crear bordes a partir de imágenes mediante el escalado o el mosaico de partes de cada imagen.
Un BorderImage divide una imagen de origen, especificada mediante la propiedad « source », en 9 regiones, tal y como se muestra a continuación:

Cuando se escala la imagen, las regiones de la imagen de origen se escalan o se repiten para crear la imagen de borde que se muestra de la siguiente manera:
- Las esquinas (regiones 1, 3, 7 y 9) no se escalan en absoluto.
- Las regiones 2 y 8 se escalan según horizontalTileMode.
- Las regiones 4 y 6 se escalan según verticalTileMode.
- La parte central (región 5) se escala según horizontalTileMode y verticalTileMode.
Las regiones de la imagen se definen mediante el grupo de propiedades border, que describe la distancia desde cada borde de la imagen de origen que se utilizará como borde.
Ejemplo de uso
Los siguientes ejemplos muestran los efectos de los distintos modos en una imagen. Se superponen líneas de guía sobre la imagen para mostrar las distintas regiones de la misma, tal y como se ha descrito anteriormente.

A modo de comparación, se muestra una imagen sin escalar utilizando un elemento Image simple. Aquí hemos superpuesto líneas para mostrar cómo nos gustaría dividirla con BorderImage:
Image {
source: "pics/borderframe.png"
anchors.centerIn: parent
}
Pero cuando se utiliza BorderImage para mostrar la imagen, la propiedad « border » se emplea para determinar las partes de la imagen que quedarán dentro de las zonas de las esquinas sin escalar, y las partes que se estirarán horizontal y verticalmente. A continuación, se le puede asignar un tamaño mayor que el de la imagen original. Dado que la propiedad « horizontalTileMode » está establecida en « BorderImage.Stretch », las partes de la imagen en las regiones 2 y 8 se estiran horizontalmente. Dado que la propiedad « verticalTileMode » está establecida en « BorderImage.Stretch », las partes de la imagen en las regiones 4 y 6 se estiran verticalmente:
BorderImage {
anchors { fill: parent; margins: 1 }
border { left: 30; top: 30; right: 30; bottom: 30 }
horizontalTileMode: BorderImage.Stretch
verticalTileMode: BorderImage.Stretch
source: "pics/borderframe.png"
}
De nuevo, se utiliza un BorderImage de gran tamaño para mostrar la imagen. Con la propiedad horizontalTileMode establecida en BorderImage.Repeat, las partes de la imagen de las regiones 2 y 8 se repiten en mosaico para que ocupen el espacio de la parte superior e inferior del elemento. Del mismo modo, la propiedad ` verticalTileMode ` se establece en ` BorderImage.Repeat`, de modo que las partes de la imagen de las regiones 4 y 6 se repiten para rellenar el espacio a la izquierda y a la derecha del elemento:
BorderImage {
anchors { fill: parent; margins: 1 }
border { left: 30; top: 30; right: 30; bottom: 30 }
horizontalTileMode: BorderImage.Repeat
verticalTileMode: BorderImage.Repeat
source: "pics/borderframe.png"
}
En algunas situaciones, es posible que el ancho de las regiones 2 y 8 no sea un múltiplo exacto del ancho de las regiones correspondientes en la imagen de origen. Del mismo modo, es posible que la altura de las regiones 4 y 6 no sea un múltiplo exacto de la altura de las regiones correspondientes. Si utilizas el modo « BorderImage.Round », este seleccionará un número entero de mosaicos y los reducirá para que encajen:
BorderImage {
anchors { fill: parent; margins: 6 }
border { left: 30; top: 30; right: 30; bottom: 30 }
horizontalTileMode: BorderImage.Round
verticalTileMode: BorderImage.Round
source: "pics/borderframe.png"
}El ejemplo «BorderImage» de la sección «Qt Quick Examples - Image Elements» muestra cómo se puede utilizar un BorderImage para simular un efecto de sombra en un elemento rectangular.
Carga de imágenes
Es posible que la imagen de origen no se cargue al instante, dependiendo de su ubicación original. El progreso de la carga se puede supervisar mediante la propiedad « progress ».
Véase también Image y AnimatedImage.
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.
border group
Las 4 líneas de borde (2 horizontales y 2 verticales) dividen la imagen en 9 secciones, tal y como se muestra a continuación:

Cada línea de borde (izquierda, derecha, superior e inferior) especifica un desplazamiento en píxeles desde el borde correspondiente de la imagen original. Por defecto, cada línea de borde tiene un valor de 0.
Por ejemplo, la siguiente definición establece la línea inferior a 10 píxeles por encima de la parte inferior de la imagen:
BorderImage {
border.bottom: 10
// ...
}Las líneas de borde también se pueden especificar utilizando un « .sci file ».
cache : bool
Especifica si la imagen debe almacenarse en la 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 la caché a expensas de las imágenes pequeñas de los «elementos de interfaz de usuario».
currentFrame es el fotograma que está visible 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.
Esta propiedad describe cómo repetir o estirar las partes centrales de la imagen del borde.
| Constante | Descripción |
|---|---|
BorderImage.Stretch | Escala la imagen para que se ajuste al área disponible. |
BorderImage.Repeat | Repite la imagen hasta que no quede más espacio. Puede recortar la última imagen. |
BorderImage.Round | Igual que «Repetir», pero reduce las imágenes para garantizar que la última imagen no se recorte. |
El modo de mosaico predeterminado para cada propiedad es « BorderImage.Stretch».
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».
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 (carga completada).
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 » está establecida en « true », o si la imagen no se encuentra en el sistema de archivos local.
Si retainWhileLoading es false (el valor predeterminado), la imagen antigua se descarta inmediatamente y el componente se borra mientras se carga la nueva imagen. Si se establece en true, la imagen antigua 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 rendimiento 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».
source : url
Esta propiedad contiene la URL que hace referencia a la imagen original.
BorderImage Puede admitir cualquier formato de imagen compatible con Qt, cargado desde cualquier esquema de URL compatible con Qt.
Esta propiedad también puede hacer referencia a un archivo .sci, un formato específico de QML basado en texto que incrusta los valores de los bordes, la imagen de origen y las reglas de mosaico directamente en el propio archivo. Al utilizar un archivo .sci, el BorderImage lee la información de los bordes directamente del archivo, por lo que no es necesario especificar las propiedades de los bordes en QML.
El siguiente archivo .sci establece los márgenes en 10 por cada lado para la imagen picture.png:
border.left: 10
border.top: 10
border.bottom: 10
border.right: 10
source: "picture.png"La URL puede ser absoluta o relativa a la URL del componente.
Véase también QQuickImageProvider.
sourceSize : size [read-only]
Esta propiedad contiene la anchura y la altura reales de la imagen cargada.
En BorderImage, esta propiedad es de solo lectura.
Véase también Image::sourceSize.
status : enumeration [read-only]
Esta propiedad describe el estado de la carga de la imagen. Puede adoptar uno de los siguientes valores:
| Constante | Descripción |
|---|---|
BorderImage.Null | No se ha establecido ninguna imagen |
BorderImage.Ready | La imagen se ha cargado |
BorderImage.Loading | La imagen se está cargando actualmente |
BorderImage.Error | Se ha producido un error al cargar la imagen |
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.