多边形绘制组件。该组件通过设置顶点坐标列表来定义多边形的形状,支持填充颜色、边框样式等属性配置。组件采用二维坐标系统,按照顶点顺序依次连接形成封闭多边形区域。适用于绘制三角形、四边形、五边形等自定义多边形形状,以及实现图表、图标等需要多边形元素的可视化场景。
该组件从API version 7开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
该组件从API version 20开始支持使用AttributeUpdater类的updateConstructorParams接口更新构造参数。
new Polygon(options?: PolygonOptions)
用于绘制多边形的构造函数。
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| options | PolygonOptions | 否 | Polygon组件的配置选项,用于定义绘制区域的宽度和高度。需要指定多边形尺寸时传入此参数,不传入时使用默认宽度和高度(均为0)。当传入undefined或null时,参数设置无效,组件属性维持原值。 |
Polygon(options?: PolygonOptions)
用于绘制多边形的构造函数。
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| options | PolygonOptions | 否 | Polygon组件的配置选项,用于定义绘制区域的宽度和高度。需要指定多边形尺寸时传入此参数,不传入时使用默认宽度和高度(均为0)。当传入undefined或null时,参数设置无效,组件属性维持原值。 |
用于描述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开始,该接口支持在元服务中使用。 |
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按照默认值处理。 |
通过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 })
}
} 
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 })
}
} 
以下示例展示了如何使用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 })
}
}
} 