ShapePath QML Type

描述了路径及其相关的描边和填充属性。更多内容...

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

属性

• capStyle : enumeration
• cosmeticStroke : bool (since 6.11)
• dashOffset : real
• dashPattern : list<real>
• fillColor : color
• fillGradient : ShapeGradient
• fillItem : Item (since 6.8)
• fillRule : enumeration
• fillTransform : matrix4x4 (since 6.8)
• joinStyle : enumeration
• miterLimit : int
• pathHints : PathHints (since 6.7)
• strokeColor : color
• strokeGradient : ShapeGradient (since 6.12)
• strokeStyle : enumeration
• strokeWidth : real
• trim (since 6.10)
  • trim.end : real (since 6.10)
  • trim.offset : real (since 6.10)
  • trim.start : real (since 6.10)

详细说明

一个Shape 包含一个或多个ShapePath元素。Shape要输出任何可见内容，至少需要一个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 }
}

一旦与 Shape 关联，当 joinStyleIndex 设为 2（ShapePath.RoundJoin）时，输出效果如下：

另请参阅 《Qt Quick 示例——形状》、 《天气预报示例》以及《Shape 》。

属性文档

capStyle : enumeration

此属性定义了线条端点的绘制方式。默认值为ShapePath.SquareCap 。

cosmeticStroke : bool [since 6.11]

该属性控制线条宽度是否在渲染缩放时保持不变。

当此属性设置为true 时，形状的轮廓将按照strokeWidth 中指定的、以设备独立像素为单位的恒定宽度进行绘制，无论对形状应用了何种变换（例如QtQuick::Item::scale ）。

默认值为false 。

该属性在 Qt 6.11 中引入。

另请参阅 strokeWidth 。

dashOffset : real

此属性定义了虚线图案的起始点，其测量单位与指定虚线图案时所用的单位相同。

默认值为0 。

另请参阅 QPen::setDashOffset()。

dashPattern : list<real>

当strokeStyle 设置为ShapePath.DashLine时，此属性用于定义连线图案。图案必须指定为偶数个正数项，其中第1、3、5…项为连线，第2、4、6…项为空格。图案以笔宽为单位进行指定。

默认值为 (4, 2)，表示一个长度为 4 *strokeWidth 像素的短划线，后跟一个长度为 2 *strokeWidth 像素的空格。

另请参阅 QPen::setDashPattern()。

fillColor : color

该属性用于指定填充颜色。

当设置为transparent 时，不会进行填充。

默认值为white 。

fillGradient : ShapeGradient

此属性用于定义填充渐变。默认情况下未启用渐变，且值为null 。在此情况下，填充将基于fillItem 属性（如果已设置），否则将使用fillColor 属性。

默认情况下，最多可同时显示 256 种不同的渐变。此限制可通过环境变量QT_QUICKSHAPES_MAX_GRADIENTS 进行自定义。

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
}

默认情况下未设置任何填充项，其值为 `null`。

该属性是在 Qt 6.8 中引入的。

fillRule : enumeration

此属性用于指定填充规则。默认值为ShapePath.OddEvenFill 。有关填充规则的说明，请参阅QPainterPath::setFillRule()。

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 。

miterLimit : int

当“joinStyle ”设置为“ShapePath.MiterJoin ”时，此属性指定斜接接头可从接合点延伸多远。

默认值为 2。

pathHints : PathHints [since 6.7]

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

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

pathHints 属性描述了一组已知为真的陈述；提示的缺失并不一定意味着相应的陈述为假。

该属性在 Qt 6.7 中引入。

strokeColor : color

此属性用于指定描边颜色。

当设置为transparent 时，不会显示描边。如果设置了strokeGradient 属性，它将优先于strokeColor 。

默认值为white 。

strokeGradient : ShapeGradient [since 6.12]

此属性用于定义描边渐变。默认情况下未启用渐变，且值为null 。此时，描边将基于strokeColor 属性。

默认情况下，最多可同时显示 256 种不同的渐变。此限制可通过环境变量QT_QUICKSHAPES_MAX_GRADIENTS 进行自定义。

该属性于 Qt 6.12 中引入。

strokeStyle : enumeration

此属性定义了线条的样式。默认值为ShapePath.SolidLine。

strokeWidth : real

该属性用于指定描边宽度。

当设置为负值时，不会进行描边。

默认值为 1。

另请参阅 cosmeticStroke 。

trim group

指定要显示的该路径的段落。

该部分由路径长度分数start 和end 定义。默认情况下，start 为 0（表示路径的起始位置），end 为 1（表示路径的结束位置），因此将显示整个路径。

offset 的值将被加到start 和end 上。如果这导致超出[0, 1]范围，这些值将进行循环递增或递减，生成的路径片段也会随之调整。offset 的有效范围在-1到1之间。默认值为0。

这些属性在 Qt 6.10 中引入。