Back to Qt.io
Contact Us Blog Download Qt

ShapePath QML Type

描述用于描边和填充的路径及相关属性。更多

Import Statement: import QtQuick.Shapes 1.9
Inherits:

Path

属性

详细说明

Shape 包含一个或多个 ShapePath 元素。要使 "形状 "输出任何可见内容，至少需要一个 ShapePath。ShapePath 本身是一个Path ，具有描述描边和填充参数的附加属性，如描边宽度和颜色、填充颜色或渐变、连接和盖帽样式等。与普通的Path 对象一样，ShapePath 也包含路径元素列表，如PathMove,PathLine,PathCubic,PathQuad,PathArc ，以及起始位置。

这些数据集的任何属性变化都会产生气泡，并改变 Shape 的输出。这意味着，使用常用的 QML 绑定和动画类型（如NumberAnimation ），可以简单轻松地更改起始和终止位置、控制点或任何描边或填充参数，甚至制作动画。

在下面的示例中，线条连接样式会根据 joinStyleIndex 的值自动改变：

ShapePath {
    strokeColor: "black"
    strokeWidth: 16
    fillColor: "transparent"
    capStyle: ShapePath.RoundCap

    property int joinStyleIndex: 0

    property variant styles: [
        ShapePath.BevelJoin,
        ShapePath.MiterJoin,
        ShapePath.RoundJoin
    ]

    joinStyle: styles[joinStyleIndex]

    startX: 30
    startY: 30
    PathLine { x: 100; y: 100 }
    PathLine { x: 30; y: 100 }
}

与形状关联后，以下是 joinStyleIndex 为 2 的输出（ShapePath.RoundJoin）：

另请参阅 Qt Quick 示例 - 形状、天气预报示例和Shape 。

属性文档

capStyle : enumeration

该属性定义如何绘制线条的端点。默认值为ShapePath.SquareCap 。

常量说明
ShapePath.FlatCap不覆盖直线端点的正方形线端。
ShapePath.SquareCap正方形线端，覆盖端点并超出一半线宽。
ShapePath.RoundCap圆角线端。

dashOffset : real

该属性定义破折号图案的起点，以指定破折号图案的单位为单位。

默认值为 0。

另请参阅 QPen::setDashOffset()。


dashPattern : list<real>

当ShapePath.strokeStyle 设置为ShapePath.DashLine 时，该属性定义了破折号图案。该模式必须指定为偶数个正条目，其中 1、3、5...... 条目为破折号，2、4、6...... 条目为空格。图案以钢笔宽度为单位指定。

默认值为 (4，2)，即 4 *ShapePath.strokeWidth 像素的破折号后跟 2 *ShapePath.strokeWidth 像素的空格。

另请参阅 QPen::setDashPattern().


fillColor : color

该属性用于保存填充颜色。

当设置为transparent 时，不会发生填充。

默认值为white 。

注意： 如果fillGradient 或fillItem 被设置为null 以外的值，它们将优先于fillColor 。在这种情况下，fillColor 将被忽略。


fillGradient : ShapeGradient

该属性定义了填充梯度。默认情况下不启用渐变，值为null 。在这种情况下，如果设置了fillItem 属性，填充将基于该属性，否则将使用fillColor 属性。

注： 此处不能使用渐变类型。相反，最好使用高级子类型，如LinearGradient 。

注： 如果设置为null 以外的内容，fillGradient 将优先于fillItem 和fillColor 。


fillItem : Item [since 6.8]

该属性定义了另一个Qt Quick 项目，用于填充形状。该项目必须是纹理提供者（如layered item 、ShaderEffectSource 或Image ）。如果不是有效的纹理提供者，该属性将被忽略。

fillItem 的视觉父对象必须是Qt Quick Item 。特别是，由于ShapePath 不是Item ，因此其子项不能用作填充项。当fillItem 作为ShapePath 的子对象创建时，需要手动设置它的父对象。

例如，直接在fillItem 属性赋值中创建Image 对象将使其成为ShapePath 的子对象。在这种情况下，必须手动设置其父对象。在下面的示例中，我们使用窗口的contentItem 作为父对象。

fillItem: Image {
    visible: false
    source: "contents.png"
    parent: window.contentItem
}

注意： 将分层项用作fillItem 时，在变换填充时可能会出现像素化效果。在这种情况下，将layer.smooth 属性设置为 true 会带来更好的视觉效果。

默认情况下不设置填充项，值为null 。

注意： 如果设置为null 以外的值，则fillItem 属性优先于fillColor 属性。fillGradient 属性则优先于fillItem 和fillColor 属性。

此属性在 Qt 6.8 中引入。


fillRule : enumeration

该属性保存填充规则。默认值为ShapePath.OddEvenFill 。有关填充规则的解释，请参阅QPainterPath::setFillRule() 。

常量说明
ShapePath.OddEvenFill奇偶填充规则。
ShapePath.WindingFill非零缠绕填充规则。

fillTransform : matrix4x4 [since 6.8]

该属性定义了应用于路径填充图案的变换（fillGradient 或fillItem ）。如果填充为纯色或透明，则该属性无效。默认情况下不启用填充变换，该属性的值为identity 矩阵。

此示例显示的矩形填充了myImageItem 的内容，并围绕myShape 的中心点旋转了 45 度：

ShapePath {
    fillItem: myImageItem
    fillTransform: PlanarTransform.fromRotate(45, myShape.width / 2, myShape.height / 2)
    PathRectangle { x: 10; y: 10; width: myShape.width - 20; height: myShape.height - 20 }
}

此属性在 Qt 6.8 中引入。


joinStyle : enumeration

该属性定义如何绘制两条连接线之间的连接。默认值为ShapePath.BevelJoin 。

常量说明
ShapePath.MiterJoin两条直线的外缘会延伸到一个角度相交，该区域会被填充。
ShapePath.BevelJoin填充两条直线之间的三角形凹槽。
ShapePath.RoundJoin填充两条直线之间的圆弧。

miterLimit : int

当joinStyle 设置为ShapePath.MiterJoin 时，此属性用于指定从连接点开始，斜切连接可以延伸多远。

默认值为 2。


pathHints : PathHints [since 6.7]

该属性描述形状的特征。如果设置，这些提示可以优化渲染。默认情况下，不设置任何提示。它可以是以下值的组合：

常量说明
ShapePath.PathLinear路径只有直线，没有曲线。
ShapePath.PathQuadratic路径没有任何立方曲线：只有直线和二次贝塞尔曲线。
ShapePath.PathConvex路径没有任何凹痕或孔洞。形状内部两点之间的所有直线都将完全位于形状内部。
ShapePath.PathFillOnRight路径遵循 TrueType 惯例，即实体填充周围的轮廓按顺时针方向排列控制点，形状中孔周围的轮廓按逆时针方向排列控制点。
ShapePath.PathSolid路径没有孔洞，或者从数学角度讲，它只是简单地连接在一起。
ShapePath.PathNonIntersecting路径轮廓不会与自身交叉。
ShapePath.PathNonOverlappingControlPointTriangles由曲线控制点定义的三角形不会相互重叠，也不会与任何线段重叠。此外，也没有线段相交。这意味着PathNonIntersecting 。

并非所有提示在逻辑上都是独立的，但并不强制执行依赖关系。例如，PathLinear 意味着PathQuadratic ，但有PathLinear 而没有PathQuadratic 也是有效的。

pathHints 属性描述了一组已知为真的语句；没有提示并不一定意味着相应的语句是假的。

此属性在 Qt 6.7 中引入。


strokeColor : color

该属性用于保存描边颜色。

当设置为transparent 时，不会出现描边。

默认值为white 。


strokeStyle : enumeration

该属性定义了描边样式。默认值为ShapePath.SolidLine。

常数说明
ShapePath.SolidLine普通线条。
ShapePath.DashLine由几个像素分隔的虚线。

strokeWidth : real

该属性用于保存描边宽度。

当设置为负值时，不会出现描边。

默认值为 1。


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