RectangularShadow QML Type

创建平滑矩形，适用于阴影和光晕效果等。更多...

• 所有成员列表，包括继承的成员

属性

• antialiasing : bool
• blur : real
• bottomLeftRadius : real (since 6.11)
• bottomRightRadius : real (since 6.11)
• cached : bool
• color : color
• material : item
• offset : vector2d
• radius : real
• spread : real
• topLeftRadius : real (since 6.11)
• topRightRadius : real (since 6.11)

详细说明

RectangularShadow 是一个应用了模糊效果的圆角矩形。与通常用于为任意形状对象生成模糊阴影/光晕的效果相比，RectangularShadow 的性能要好得多。

以下示例演示了如何为Rectangle 添加阴影：

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"
}

RectangularShadow 的 API 与 CSS box-shadow 类似，包含颜色、偏移、扩散和模糊等参数。此外，RectangularShadow API 还包含：

• real radius: 控制应用于矩形角部的圆角半径。与从父元素继承半径的 CSS box-shadow 不同，RectangularShadow 需要用户自行设置该值。这使您可以使用不同的半径，并独立于父元素移动 RectangularShadow。
• bool cached: 允许缓存模糊的阴影纹理。这会增加内存占用，但可能提升渲染性能，特别是在处理不会动态变化的较大阴影时。
• item material: 包含 RectangularShadow 的 ` ` 元素，供高级用途使用。例如，这允许通过自定义着色器来扩展效果。ShaderEffect

渲染效果也与 CSS 的 box-shadow 相匹配，仅有少数值得注意的差异。这些差异的存在是为了使 RectangularShadow 尽可能高效。

• 模糊效果是在着色器中通过数学计算实现的，而非使用 CSS box-shadow 实现中常用的高斯模糊。这使得阴影的外观略有不同，特别是在使用较大的模糊值时。
• 自 Qt 6.11 起，RectangularShadow 还支持单独设置各角的圆角半径值。若无需此功能，为获得最佳性能，请仅设置通用参数 `radius`。

下表通过截图对比了 Chrome 浏览器中 RectangularShadow 与 CSS box-shadow 的渲染效果。最右侧的元素是应用了模糊效果并乘以1.2 （即24 、48 、48 ）的 RectangularShadow，以实现更接近的匹配效果。

RectangularShadow 会根据模糊程度精确扩展阴影尺寸，而其他一些阴影（包括 CSS 的 box-shadow）则采用尺寸倍数计算。RectangularShadow 内部阴影元素的尺寸为：

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

例如，以下代码中的阴影元素尺寸为 280x180 像素。半径或偏移量值不会影响阴影元素的尺寸。

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

属性文档

antialiasing : bool

用于决定阴影是否应使用抗锯齿。当该参数设置为true 时，即使blur 设置为0 ，也会使用单像素抗锯齿。

默认值为true 。

blur : real

该属性定义了阴影延伸到项目区域外多少像素。

取值范围从 0.0（无模糊）到 inf（无限模糊）。默认值为10.0 。

bottomLeftRadius : real [since 6.11]

该属性用于指定绘制左下角时使用的半径。

如果未设置 `bottomLeftRadius`，则将使用 `radius `。如果 `bottomLeftRadius` 为零，则该角将呈锐角。

该属性自 Qt 6.11 起引入。

另请参阅 radius 、topLeftRadius 、topRightRadius 以及bottomRightRadius 。

bottomRightRadius : real [since 6.11]

该属性用于指定绘制右下角时使用的半径。

如果未设置 bottomRightRadius，则将使用radius 。如果 bottomRightRadius 为零，则该角将呈锐角。

该属性在 Qt 6.11 中引入。

另请参阅 radius 、topLeftRadius 、topRightRadius 以及bottomLeftRadius 。

cached : bool

此属性允许将效果输出像素缓存起来，以提升渲染性能。

每次更改效果属性时，都必须更新缓存中的像素。由于需要额外的内存缓冲区来存储效果输出，因此会增加内存消耗。

当源或效果属性进行动画处理时，建议禁用缓存。

默认值为false 。

color : color

此属性定义了用于阴影的 RGBA 颜色值。

默认值为Qt.rgba(0.0, 0.0, 0.0, 1.0) （黑色）。

material : item

该属性包含阴影的“ShaderEffect ”对象。您可以利用此属性直观地展示阴影的覆盖范围，因为受blur 、offset 和spread 影响，效果对象的位置和大小通常与“RectangularShadow ”对象不同。

该材质也可以替换为自定义材质。当不使用单独的角半径时，默认材质为ShaderEffect ，其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;
}

当使用独立边角半径时，“float radius”统一变量的值小于 0，并且会增加一个额外的“vec4 radius4”统一变量。vec4 中边角半径值的顺序为：左上、右上、左下、右下。

Qt Quick Effect Maker 其中包含RectangularShadow 节点，可作为自定义材质的起点。您可以直接使用包含该节点的导出效果作为RectangularShadow 材质。

RectangularShadow {
    ...
    material: MyShadowEffect { }
}

若要恢复使用默认材质，请将材质属性设置为null 。

offset : vector2d

此属性定义了用于阴影的位置偏移量。该偏移量将附加到阴影位置上，相对于“RectangularShadow ”项的位置。

默认值为 `Qt.vector2d(0.0, 0.0) `（无偏移）。

radius : real

此属性定义了用于绘制圆角阴影的圆角半径。

该值的取值范围为 0.0 到该项的有效宽度或高度的一半，以较小者为准。

默认值为0 。

spread : real

此属性定义阴影在像素单位上的扩散（延伸）程度。该扩散量将附加到阴影尺寸上，其大小以“RectangularShadow ”项的尺寸为基准。

取值范围为 -inf 到 inf。默认值为0.0 。

topLeftRadius : real [since 6.11]

该属性存储用于绘制左上角的半径值。

如果未设置 topLeftRadius，则将使用radius 。如果 topLeftRadius 为零，则角将呈锐角。

该属性于 Qt 6.11 版本中引入。

另请参阅 radius 、topRightRadius 、bottomLeftRadius 以及bottomRightRadius 。

topRightRadius : real [since 6.11]

该属性用于存储绘制右上角时所用的半径。

如果未设置 topRightRadius，则将使用radius 。如果 topRightRadius 为零，则该角将呈锐角。

该属性在 Qt 6.11 中引入。

另请参阅 radius 、topLeftRadius 、bottomLeftRadius 以及bottomRightRadius 。