目录

Polygon

多边形绘制组件。该组件通过设置顶点坐标列表来定义多边形的形状,支持填充颜色、边框样式等属性配置。组件采用二维坐标系统,按照顶点顺序依次连接形成封闭多边形区域。适用于绘制三角形、四边形、五边形等自定义多边形形状,以及实现图表、图标等需要多边形元素的可视化场景。

该组件从API version 7开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。

该组件从API version 20开始支持使用AttributeUpdater类的updateConstructorParams接口更新构造参数。

子组件

无

接口

[h2]Polygon

new Polygon(options?: PolygonOptions)

用于绘制多边形的构造函数。

卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名 类型 必填 说明
options PolygonOptions 否 Polygon组件的配置选项,用于定义绘制区域的宽度和高度。需要指定多边形尺寸时传入此参数,不传入时使用默认宽度和高度(均为0)。当传入undefined或null时,参数设置无效,组件属性维持原值。

[h2]Polygon

Polygon(options?: PolygonOptions)

用于绘制多边形的构造函数。

卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名 类型 必填 说明
options PolygonOptions 否 Polygon组件的配置选项,用于定义绘制区域的宽度和高度。需要指定多边形尺寸时传入此参数,不传入时使用默认宽度和高度(均为0)。当传入undefined或null时,参数设置无效,组件属性维持原值。

PolygonOptions18+对象说明

用于描述Polygon组件绘制属性。

为规范匿名对象的定义,API 18版本修改了此处的元素定义。其中,保留了历史匿名对象的起始版本信息,会出现外层元素@since版本号高于内层元素版本号的情况,但这不影响接口的使用。

卡片能力: 从API version 18开始,该接口支持在ArkTS卡片中使用。

元服务API: 从API version 18开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

名称 类型 只读 可选 说明
width7+ Length 否 是

宽度,取值范围≥0。

默认值:0

默认单位:vp

若给定值小于0,则按默认值处理。异常值undefined、null、NaN和Infinity按照默认值处理。

卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

height7+ Length 否 是

高度,取值范围≥0。

默认值:0

默认单位:vp

若给定值小于0,则按默认值处理。异常值undefined、null、NaN和Infinity按照默认值处理。

卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

属性

除支持通用属性以及图形绘制通用属性外,还支持以下属性:

[h2]points

points(value: Array<any>)

设置多边形的顶点坐标列表,支持attributeModifier动态设置属性方法。异常值按照默认值处理。

卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名 类型 必填 说明
value Array<any> 是

多边形的顶点坐标列表。使用时传入一个二维数组,每个子数组表示一个顶点的[x, y]坐标。

默认值:[](空数组)

默认单位:vp

异常值undefined和null按照默认值处理。

示例

[h2]示例1(组件属性绘制)

通过points、fill、fillOpacity、stroke、strokeWidth属性分别绘制多边形的顶点坐标、填充颜色、填充透明度、边框颜色和边框宽度。

// xxx.ets
@Entry
@Component
struct PolygonExample {
  build() {
    Column({ space: 10 }) {
      // 在 100 * 100 的矩形框中绘制一个三角形,起点(0, 0),经过(50, 100),终点(100, 0)
      Polygon({ width: 100, height: 100 })
        .points([[0, 0], [50, 100], [100, 0]])
        .fill(Color.Green)
      // 在 100 * 100 的矩形框中绘制一个四边形,起点(0, 0),经过(0, 100)和(100, 100),终点(100, 0)
      Polygon()
        .width(100)
        .height(100)
        .points([[0, 0], [0, 100], [100, 100], [100, 0]])
        .fillOpacity(0)
        .strokeWidth(5)
        .stroke(Color.Blue)
      // 在 100 * 100 的矩形框中绘制一个五边形,起点(50, 0),依次经过(0, 50)、(20, 100)和(80, 100),终点(100, 50)
      Polygon()
        .width(100)
        .height(100)
        .points([[50, 0], [0, 50], [20, 100], [80, 100], [100, 50]])
        .fill(Color.Red)
        .fillOpacity(0.6)
    }.width('100%').margin({ top: 10 })
  }
}

[h2]示例2(宽和高使用不同参数类型绘制多边形)

width、height属性分别使用不同的长度类型绘制图形。

// xxx.ets
@Entry
@Component
struct PolygonTypeExample {
  build() {
    Column({ space: 10 }) {
      // 在 100 * 100 的矩形框中绘制一个三角形,起点(0, 0),经过(50, 100),终点(100, 0)
      Polygon({ width: '100', height: '100' }) // 使用string类型
        .points([[0, 0], [50, 100], [100, 0]])
      // 在 100 * 100 的矩形框中绘制一个四边形,起点(0, 0),经过(0, 100)和(100, 100),终点(100, 0)
      Polygon({ width: 100, height: 100 })// 使用number类型
        .points([[0, 0], [0, 100], [100, 100], [100, 0]])
        .fillOpacity(0)
        .strokeWidth(5)
        .stroke(Color.Blue)
      // 在 100 * 100 的矩形框中绘制一个五边形,起点(50, 0),依次经过(0, 50)、(20, 100)和(80, 100),终点(100, 50)
      Polygon({ width: $r('app.string.PolygonWidth'), height: $r('app.string.PolygonHeight') }) // 使用Resource类型,需用户自定义
        .points([[50, 0], [0, 50], [20, 100], [80, 100], [100, 50]])
        .fillOpacity(0.6)
    }.width('100%').margin({ top: 10 })
  }
}

[h2]示例3(使用attributeModifier动态设置Polygon组件的属性)

以下示例展示了如何使用attributeModifier动态设置Polygon组件的points、fill、fillOpacity、stroke、strokeDashArray、strokeDashOffset、strokeLineCap、strokeLineJoin、strokeMiterLimit、strokeOpacity、strokeWidth和antiAlias属性。

// xxx.ets
class MyPolygonModifier implements AttributeModifier<PolygonAttribute> {
  applyNormalAttribute(instance: PolygonAttribute): void {
    // 三角形,起点(0, 0),经过(50, 100),终点(100, 0),填充颜色#707070,填充透明度0.5,边框颜色#2787D9,边框间隙[20],向左偏移15,线条两端样式为半圆,拐角样式使用尖角连接路径段,斜接长度与边框宽度比值的极限值为5,边框透明度0.5,边框宽度10,抗锯齿开启
    instance.points([[0, 0], [50, 100], [100, 0]])
    instance.fill("#707070")
    instance.fillOpacity(0.5)
    instance.stroke("#2787D9")
    instance.strokeDashArray([20])
    instance.strokeDashOffset("15")
    instance.strokeLineCap(LineCapStyle.Round)
    instance.strokeLineJoin(LineJoinStyle.Miter)
    instance.strokeMiterLimit(5)
    instance.strokeOpacity(0.5)
    instance.strokeWidth(10)
    instance.antiAlias(true)
  }
}

@Entry
@Component
struct PolygonModifierDemo {
  @State modifier: MyPolygonModifier = new MyPolygonModifier()

  build() {
    Column() {
      Polygon()
        .width(100)
        .height(100)
        .attributeModifier(this.modifier)
        .offset({ x: 20, y: 20 })
    }
  }
}