En esta página

RectangularShadow QML Type

Crea un rectángulo suavizado, ideal, por ejemplo, para efectos de sombra y resplandor. Más...

Import Statement: import QtQuick.Effects
Inherits:

Item

Propiedades

Descripción detallada

RectangularShadow es un rectángulo redondeado al que se le ha aplicado un efecto de desenfoque. El rendimiento de RectangularShadow es mucho mejor que el de un elemento genérico que crea sombras o resplandores desenfocados en elementos de cualquier forma.

El siguiente ejemplo muestra cómo añadir una sombra a un elemento « Rectangle »:

Rectángulo redondeado con una sombra suave desplazada hacia la esquina superior izquierda

import QtQuick
import QtQuick.Effects

...
RectangularShadow {
    anchors.fill: myRectangle
    offset.x: -10
    offset.y: -5
    radius: myRectangle.radius
    blur: 30
    spread: 10
    color: Qt.darker(myRectangle.color, 1.6)
}
Rectangle {
    id: myRectangle
    anchors.centerIn: parent
    width: 200
    height: 100
    radius: 50
    color: "#c0d0f0"
}

La API de RectangularShadow es similar a la propiedad CSS `box-shadow`, con valores de color, desplazamiento, extensión y desenfoque. Además, la API de RectangularShadow incluye:

  • real radius: Controla el radio de redondeo aplicado a las esquinas del rectángulo. A diferencia de la propiedad `box-shadow` de CSS, que hereda el radio del elemento padre, RectangularShadow espera que el usuario lo establezca. Esto permite utilizar diferentes radios y mover la sombra rectangular de forma independiente de su elemento padre.
  • bool cached: Permite almacenar en caché la textura de la sombra desenfocada. Esto aumenta el uso de memoria, aunque puede mejorar el rendimiento del renderizado, especialmente con sombras más grandes que no cambian dinámicamente.
  • item material: Contiene el elemento ` ` de RectangularShadow para usos avanzados. Esto permite, por ejemplo, ampliar el efecto con un sombreador personalizado. ShaderEffect

El resultado del renderizado también coincide con el de «box-shadow» de CSS, con algunas diferencias notables. Estas diferencias existen para que RectangularShadow ofrezca el mayor rendimiento posible.

  • El desenfoque se calcula matemáticamente en el sombreador en lugar de utilizar el desenfoque gaussiano, que suelen emplear las implementaciones de `box-shadow` de CSS. Esto hace que la sombra tenga un aspecto ligeramente diferente, especialmente con valores de desenfoque más altos.
  • Desde Qt 6.11, RectangularShadow también admite valores de radio de esquina individuales. Cuando no sea necesario, para obtener el mejor rendimiento, configura solo el valor común « radius ».

A continuación se muestra una tabla con capturas de pantalla para comparar el resultado de renderizado de RectangularShadow y la sombra de cuadro CSS en el navegador Chrome. El elemento situado más a la derecha es RectangularShadow con desenfoque multiplicado por 1.2 (es decir, 24, 48, 48) para lograr una correspondencia más cercana.

tipoSombra de cuadro CSSRectangularShadowRectangularShadow + desenfoque adicional
desplazamiento: (0, 0)
desenfoque: 20
extensión: 0

Sombra de cuadro (box-shadow) en CSS con un valor de desenfoque de 20

Sombra rectangular con desenfoque de 20

«RectangularShadow» con un desenfoque de 24 para que se ajuste mejor al CSS

desplazamiento: (-10, -20)
desenfoque: 40
extensión: 0

Sombra de cuadro CSS con desplazamiento y desenfoque de 40

Sombra rectangular con desplazamiento y desenfoque de 40

«RectangularShadow» con un desenfoque de 48 para que se ajuste mejor al CSS

offset: (-10, -20)
blur: 40
spread: 10

Sombra de cuadro CSS con desplazamiento, desenfoque de 40 y extensión de 10

Sombra rectangular con desplazamiento, desenfoque de 40 y extensión de 10

«RectangularShadow» con un desenfoque de 48 y una extensión de 10 para que se ajuste mejor al CSS

RectangularShadow amplía el tamaño de la sombra en una cantidad exacta en función del valor de desenfoque, mientras que otras sombras (incluida la sombra de cuadro de CSS) aplican un multiplicador al tamaño. El tamaño del elemento de sombra dentro de un RectangularShadow es:

width = rectangularShadow.width + 2 * blur +  2 * spread
height = rectangularShadow.height + 2 * blur + 2 * spread

Por ejemplo, el tamaño del elemento de sombra del código siguiente es de 280 x 180 píxeles. Los valores de radio o desplazamiento no afectan al tamaño del elemento de sombra.

RectangularShadow {
    width: 200
    height: 100
    blur: 30
    spread: 10
    radius: 20
}

Documentación de propiedades

antialiasing : bool

Se utiliza para determinar si la sombra debe aplicar suavizado o no. Cuando este valor es « true », se aplica un suavizado de un solo píxel, incluso cuando el valor de « blur » es « 0 ».

El valor por defecto es « true ».

blur : real

Esta propiedad define cuántos píxeles fuera del área del elemento alcanza la sombra.

El valor oscila entre 0,0 (sin desenfoque) e inf (desenfoque infinito). El valor por defecto es 10.0.

Nota: Para que coincida con el resultado de la representación de «box-shadow» en CSS, el grado óptimo de desenfoque es aproximadamente: 1.2 * cssBlur

bottomLeftRadius : real [since 6.11]

Esta propiedad establece el radio que se utiliza para dibujar la esquina inferior izquierda.

Si no se establece «bottomLeftRadius», se utilizará en su lugar « radius ». Si «bottomLeftRadius» es cero, la esquina será afilada.

Esta propiedad se introdujo en Qt 6.11.

Véase también « radius », « topLeftRadius », « topRightRadius » y « bottomRightRadius ».

bottomRightRadius : real [since 6.11]

Esta propiedad define el radio que se utiliza para dibujar la esquina inferior derecha.

Si no se establece «bottomRightRadius», se utilizará en su lugar « radius ». Si «bottomRightRadius» es cero, la esquina será aguda.

Esta propiedad se introdujo en Qt 6.11.

Véase también « radius », « topLeftRadius », « topRightRadius » y « bottomLeftRadius ».

cached : bool

Esta propiedad permite almacenar en caché los píxeles de salida del efecto con el fin de mejorar el rendimiento del renderizado.

Cada vez que se modifican las propiedades del efecto, es necesario actualizar los píxeles de la caché. El consumo de memoria aumenta, ya que se requiere un búfer de memoria adicional para almacenar el resultado del efecto.

Se recomienda desactivar la caché cuando se animen las propiedades de la fuente o del efecto.

El valor por defecto es « false ».

color : color

Esta propiedad define el valor de color RGBA que se utiliza para la sombra.

El valor por defecto es Qt.rgba(0.0, 0.0, 0.0, 1.0) (negro).

material : item

Esta propiedad contiene el elemento « ShaderEffect » de la sombra. Puedes utilizar esta propiedad para visualizar el alcance de la sombra, ya que el elemento de efecto suele tener una posición y un tamaño diferentes a los del elemento « RectangularShadow », debido a blur, offset y spread.

El material también se puede sustituir por uno personalizado. El material predeterminado cuando no se utiliza el radio de esquina individual es un « ShaderEffect » con el siguiente « fragmentShader »:

#version 440

layout(location = 0) in vec2 texCoord;
layout(location = 1) in vec2 fragCoord;
layout(location = 0) out vec4 fragColor;

layout(std140, binding = 0) uniform buf {
    mat4 qt_Matrix;
    float qt_Opacity;
    vec4 color;
    vec3 iResolution;
    vec2 rectSize;
    float radius;
    float blur;
};

float roundedBox(vec2 centerPos, vec2 size, float radii) {
    return length(max(abs(centerPos) - size + radii, 0.0)) - radii;
}

void main()
{
    float box = roundedBox(fragCoord - iResolution.xy * 0.5, rectSize, radius);
    float a = 1.0 - smoothstep(0.0, blur, box);
    fragColor = color * qt_Opacity * a * a;
}

Cuando se utilizan radios de esquina individuales, el valor del uniforme «float radius» es < 0 y hay un uniforme adicional «vec4 radius4». El orden de los valores de los radios de esquina en el vec4 es: superior izquierdo, superior derecho, inferior izquierdo e inferior derecho.

Qt Quick Effect Maker contiene el nodo RectangularShadow, que puede utilizarse como punto de partida para crear un material personalizado. Puedes utilizar directamente el efecto exportado que contiene ese nodo como material RectangularShadow.

RectangularShadow {
    ...
    material: MyShadowEffect { }
}

Para volver a utilizar el material predeterminado, configura la propiedad del material en « null ».

offset : vector2d

Esta propiedad define el desplazamiento de posición que se utiliza para la sombra. Este desplazamiento se suma a la posición de la sombra, en relación con la posición del elemento « RectangularShadow ».

El valor por defecto es « Qt.vector2d(0.0, 0.0) » (sin desplazamiento).

radius : real

Esta propiedad define el radio de las esquinas que se utiliza para dibujar una sombra con esquinas redondeadas.

El valor oscila entre 0,0 y la mitad del ancho o la altura efectiva del elemento, el que sea menor.

El valor por defecto es « 0 ».

spread : real

Esta propiedad define cuánto se extiende la sombra en píxeles. Esta extensión se suma al tamaño de la sombra, en relación con el tamaño del elemento RectangularShadow.

El valor oscila entre -inf e inf. El valor por defecto es 0.0.

Nota: El comportamiento del radio con la extensión se ajusta al estándar CSS «box-shadow». Así pues, cuando la extensión es menor que el radio, el radio de la sombra aumenta en la cantidad correspondiente a la extensión. Cuando la extensión aumenta, el radio solo crece parcialmente. Consulta https://www.w3.org/TR/css-backgrounds-3/#shadow-shape. Si deseas que el radio de la sombra aumente de forma sincronizada al aumentar el tamaño de la sombra (como ocurre con la implementación de «box-shadow» en CSS de Firefox), aumenta los valores de RectangularShadow, width y height en lugar de utilizar spread.

topLeftRadius : real [since 6.11]

Esta propiedad contiene el radio que se utiliza para dibujar la esquina superior izquierda.

Si no se establece «topLeftRadius», se utilizará en su lugar « radius ». Si «topLeftRadius» es cero, la esquina será puntiaguda.

Esta propiedad se introdujo en Qt 6.11.

Véase también radius, topRightRadius, bottomLeftRadius y bottomRightRadius.

topRightRadius : real [since 6.11]

Esta propiedad define el radio que se utiliza para dibujar la esquina superior derecha.

Si no se establece el valor de `topRightRadius`, se utilizará en su lugar ` radius `. Si `topRightRadius` es cero, la esquina será aguda.

Esta propiedad se introdujo en Qt 6.11.

Véase también « radius », « topLeftRadius », « bottomLeftRadius » y « bottomRightRadius ».

© 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.