Back to Qt.io
Contact Us Blog Download Qt

Shape QML Type

渲染路径。更多

Import Statement: import QtQuick.Shapes 1.9
Inherits:

Item

Inherited By:

EllipseShape and MaskShape

属性

详细说明

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

这种方法不同于通过QQuickPaintedItem 或 2D 画布渲染形状，因为路径永远不会在软件中光栅化。因此，"形状 "适用于创建遍布屏幕较大区域的形状，避免了纹理上传或帧缓存闪烁对性能造成的影响。此外，声明式 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 API 的数据驱动和声明性质通常意味着底层 CPU 和 GPU 资源具有更好的缓存能力。一个ShapePath 中的属性变化只会导致重新处理受影响的ShapePath ，而形状的其他部分则保持不变。因此，与命令式绘制方法（如QPainter ）相比，频繁变化的属性仍可降低整体系统负载。
  • 同时，必须注意场景中 Shape 元素的数量。这种形状项在场景图中的表示方式不同于普通的基于几何图形的项，在 OpenGL 状态改变时会产生一定的代价。
  • 一般来说，在没有绝对必要的情况下，场景应避免使用单独的 "形状 "项。与多个 "形状 "项相比，更倾向于使用一个包含多个ShapePath 元素的 "形状 "项。

另请参阅 Qt Quick 示例 - 形状、天气预报示例、Path,PathMove,PathLine,PathQuad,PathCubic,PathArc 和PathSvg 。

属性文档

horizontalAlignment : enumeration [since 6.7]

verticalAlignment : enumeration [since 6.7]

设置项目中形状的水平和垂直对齐方式。默认情况下，形状与(0,0) 左上角对齐。

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

此 QML 属性在 Qt 6.7 中引入。


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]

该属性决定了形状的contains() 的定义。如果您添加了Qt Quick 输入处理程序，并且只想在鼠标或触摸点完全位于形状内部时才做出反应，那么该属性将非常有用。

常量说明
Shape.BoundingRectContainsQQuickItem::contains() 的默认实现只检查给定点是否在矩形边框内。这是最有效的实现方式，因此是默认设置。
Shape.FillContains检查构成此 Shape 的任何ShapePath 的内部（如果使用填充渲染，则会填充的部分）是否包含给定的点。添加的 ShapePaths 越复杂、数量越多，检查的效率就越低，这可能会降低应用程序中的事件交付速度。因此，在使用时应小心谨慎。

加快FillContains 检查速度的一种方法是生成一个点数尽可能少的近似轮廓，将其放置在透明形状的顶部，然后将指针处理程序添加到该轮廓中，这样在事件交付过程中进行包含检查的成本会更低。

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


data : list<Object> [default]

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


fillMode : enumeration [since QtQuick.Shapes 6.7]

设置该属性可定义当路径的尺寸与项目的尺寸不同时会发生的情况。

常数说明
Shape.NoResize形状将以其原始大小呈现，与项目的大小无关。这是默认值
Shape.Stretch按比例缩放形状以适应项目，必要时可更改纵横比。请注意，在使用曲线渲染器时，非均匀缩放可能会导致抗锯齿质量下降
Shape.PreserveAspectFit形状按均匀比例缩放以适应项目内部
Shape.PreserveAspectCrop对形状进行均匀缩放，使其完全填满项目，必要时可扩展到项目外部。请注意，只有当clip为 true 时才会实际裁剪内容。

此属性在 QtQuick.Shapes 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.UnknownRenderer渲染器未知。
Shape.GeometryRenderer通用的、独立于驱动程序的 GPU 渲染解决方案。使用与QPainter 的 OpenGL 2 绘画引擎相同的基于 CPU 的三角测量方法。当使用基于 RHI 的Qt Quick 场景图后端时，这是默认设置。
Shape.SoftwareRenderer使用光栅绘图引擎进行纯QPainter 绘图。当Qt Quick 场景图与software 后端一起运行时，这是默认选项，也是唯一选项。
Shape.CurveRenderer基于 GPU 的渲染器，旨在保留任何比例的曲率。与Shape.GeometryRenderer 不同的是，曲线不是通过短直线来近似的。相反，曲线是通过专门的片段着色器来渲染的。这不仅提高了视觉质量，还避免了缩放时重新分层对性能造成的影响。此外，Shape.CurveRenderer 还提供了原生的高质量抗锯齿功能，而不会因为多重采样或超采样造成性能损失。

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

注： Shape.CurveRenderer 将用二次曲线近似三次曲线，因此可能会与数学上正确的形状可视化略有偏差。此外，如果要将形状渲染到Qt Quick 3D 场景中，且 RHI 的 OpenGL 后端处于活动状态，则需要对 OpenGL 进行GL_OES_standard_derivatives 扩展（默认情况下，OpenGL ES 3 及更高版本可使用此扩展，但在 OpenGL ES 2 中为可选项）。


status : enumeration [read-only]

此属性决定了 "形状 "的状态，当 Shape.asynchronous 设置为true 时与之相关。

常量说明
Shape.Null尚未初始化。
Shape.Ready形状已完成处理。
Shape.Processing路径正在处理中。

vendorExtensionsEnabled : bool

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

默认值为false 。

截至 Qt 6.0，没有实现特定于供应商的渲染路径。


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