Shape QML Type

渲染路径。更多...

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

属性

• asynchronous : bool
• boundingRect : rect (since 6.6)
• containsMode : enumeration (since QtQuick.Shapes 1.11)
• data : list<Object>
• fillMode : enumeration (since QtQuick.Shapes 6.7)
• horizontalAlignment : enumeration (since 6.7)
• preferredRendererType : enumeration (since 6.6)
• rendererType : enumeration
• status : enumeration
• vendorExtensionsEnabled : bool
• verticalAlignment : enumeration (since 6.7)

详细说明

通过将QPainterPath 中的几何体进行三角剖分来渲染路径。

这种方法与通过QQuickPaintedItem 或2D Canvas渲染形状不同，因为路径在软件中不会被光栅化。 因此，Shape 适用于创建覆盖屏幕较大区域的形状，从而避免了纹理上传或帧缓冲区复制带来的性能损失。此外，声明式 API 允许对路径元素属性（如起始和结束位置、控制点等）进行操作、绑定，甚至动画处理。

用于指定路径元素的类型在PathView 和Shape之间是通用的。但是，并非所有的Shape实现都支持所有路径元素类型，而有些类型对于PathView 来说可能没有意义。Shape当前支持的子集包括：PathMove 、PathLine 、PathQuad 、PathCubic 、PathArc 、PathText 和PathSvg 。

有关支持的路径元素的详细概述，请参阅Path 。

Shape {
    width: 200
    height: 150
    anchors.centerIn: parent
    ShapePath {
        strokeWidth: 4
        strokeColor: "red"
        fillGradient: LinearGradient {
            x1: 20; y1: 20
            x2: 180; y2: 130
            GradientStop { position: 0; color: "blue" }
            GradientStop { position: 0.2; color: "green" }
            GradientStop { position: 0.4; color: "red" }
            GradientStop { position: 0.6; color: "yellow" }
            GradientStop { position: 1; color: "cyan" }
        }
        strokeStyle: ShapePath.DashLine
        dashPattern: [ 1, 4 ]
        startX: 20; startY: 20
        PathLine { x: 180; y: 130 }
        PathLine { x: 20; y: 130 }
        PathLine { x: 20; y: 20 }
    }
}

与Item 类似，Shape 也允许将任何视觉或非视觉对象声明为其子元素。ShapePath 对象会得到特殊处理。这非常有用，因为它允许将视觉元素（如Rectangle 或Image ）和非视觉对象（如Timer ）直接作为 Shape 的子元素添加。

以下列表总结了可用的 Shape 渲染方法：

• 当Qt Quick 使用默认的硬件加速后端（RHI）运行时，将使用通用形状渲染器。该渲染器会将形状转换为三角形，并将其传递给渲染器。
• software 后端已得到全面支持。在此情况下，路径通过QPainter::strokePath()和QPainter::fillPath()进行渲染。
• 目前不支持 OpenVG 后端。

使用 Shape 时，必须注意其可能带来的性能影响：

• 当应用程序使用基于三角剖分的通用 Shape 实现运行时，几何体的生成完全在 CPU 上进行。这可能消耗大量资源。更改路径元素集、更改这些元素的属性，或更改 Shape 本身的某些属性，都会导致每次更改时受影响路径都需要重新进行三角剖分。 因此，在性能较弱的系统上，对这些属性应用动画可能会影响性能。
• 不过，Shape API 数据驱动、声明式的特性通常意味着底层 CPU 和 GPU 资源具有更好的缓存效率。某个 `ShapePath ` 中的属性变更只会导致受影响的 `ShapePath` 被重新处理，而 Shape 的其他部分保持不变。 因此，与命令式绘制方法（例如QPainter ）相比，频繁更改的属性仍可带来更低的整体系统负载。
• 同时，必须注意场景中“Shape”元素的数量。此类“Shape”项在场景图中的表示方式与普通的基于几何体的项不同，在 OpenGL 状态变更时会产生一定的开销。
• 一般而言，除非绝对必要，场景应避免使用独立的Shape元素。建议使用一个包含多个ShapePath 元素的Shape元素，而不是多个Shape元素。

另请参阅 《Qt Quick 示例——Shapes》、 天气预报示例、Path 、PathMove 、PathLine 、PathQuad 、PathCubic 、PathArc 以及PathSvg 。

属性文档

asynchronous : bool

当rendererType 的值为Shape.GeometryRenderer 或Shape.CurveRenderer 时，在Shape的抛光阶段，CPU会对输入路径进行一定程度的预处理。这可能会消耗大量资源。若要将此工作卸载到单独的工作线程上，请将此属性设置为true 。

启用此选项后，将形状设为可见时不会等待内容就绪。相反，GUI/主线程不会被阻塞，且路径渲染的结果仅在所有异步工作完成后才会显示。

默认值为false 。

boundingRect : rect [read-only, since 6.6]

包含该形状中所有子路径的合并边界矩形。

该属性自 Qt 6.6 起引入。

containsMode : enumeration [since QtQuick.Shapes 1.11]

该属性用于定义形状（Shape）的contains()方法。当您添加“Qt Quick ”输入处理程序，且希望仅在鼠标或触点完全位于形状内部时才做出响应时，此属性非常有用。

加快FillContains 检查速度的一种方法是：生成一个包含尽可能少控制点的近似轮廓，将其放置在顶层的透明Shape中，并将指针处理程序添加到该Shape上，这样在事件传递过程中，包含性检查的开销就会更小。

该属性在 QtQuick.Shapes 1.11 版本中引入。

data : list<Object> [default]

该属性存储定义 Shape 内容的ShapePath 对象。它还可以包含任何其他类型的对象，因为 Shape 与 Item 一样，允许将任何视觉或非视觉对象作为子对象添加。

fillMode : enumeration [since QtQuick.Shapes 6.7]

设置此属性以定义当路径与项目大小不一致时应如何处理。

该属性在 QtQuick.Shapes 6.7 中引入。

设置形状在项目内的水平和垂直对齐方式。默认情况下，形状会以(0,0) 为基准对齐于左上角。

horizontalAlignment 的有效值为：Shape.AlignLeft 、Shape.AlignRight 和Shape.AlignHCenter 。verticalAlignment 的有效值为：Shape.AlignTop 、Shape.AlignBottom 和Shape.AlignVCenter 。

这些属性是在 Qt 6.7 中引入的。

preferredRendererType : enumeration [since 6.6]

指定用于渲染形状的特定后端。可选值与rendererType 中的相同。默认值为Shape.UnknownRenderer ，表示无特定偏好。

如果当前的Qt Quick 后端不支持所请求的渲染器类型，则将改用该后端的默认渲染器。当后端初始化时，这一情况将反映在rendererType 中。

Shape.SoftwareRenderer 目前，若未通过software 后端运行场景图，则无法选择该渲染器；若通过该后端运行，则无论preferredRendererType 的设置如何，该渲染器都将被选中。

有关其影响的更多信息，请参阅rendererType 。

该属性在 Qt 6.6 中引入。

rendererType : enumeration [read-only]

该属性用于确定哪个路径渲染后端处于活动状态。

默认情况下，将选择Shape.GeometryRenderer ，除非Qt Quick 场景图在software 后端上运行。在这种情况下，将使用Shape.SoftwareRenderer 。可通过preferredRendererType 属性请求Shape.CurveRenderer 。

status : enumeration [read-only]

该属性用于确定 Shape 的状态，当 Shape.asynchronous 设置为true 时，该属性才起作用。

vendorExtensionsEnabled : bool

此属性控制非标准 OpenGL 扩展的使用。

默认值为false 。

截至 Qt 6.0 版本，尚未实现任何供应商专有的渲染路径。