1# Polygon 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @zjsxstar--> 5<!--Designer: @sunbees--> 6<!--Tester: @liuli0427--> 7<!--Adviser: @HelloCrease--> 8 9多边形绘制组件。 10 11> **说明：** 12> 13> 该组件从API version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 14> 15> 该组件从API version 20开始支持使用[AttributeUpdater](../js-apis-arkui-AttributeUpdater.md)类的[updateConstructorParams](../js-apis-arkui-AttributeUpdater.md#updateconstructorparams)接口更新构造参数。 16 17 18## 子组件 19 20无 21 22 23## 接口 24 25Polygon(options?: PolygonOptions) 26 27**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 28 29**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 30 31**系统能力：** SystemCapability.ArkUI.ArkUI.Full 32 33**参数：** 34 35| 参数名 | 类型 | 必填 | 说明 | 36| -------- | -------- | -------- | -------- | 37| options | [PolygonOptions](ts-drawing-components-polygon.md#polygonoptions18对象说明) | 否 | Polygon绘制区域。 | 38 39## PolygonOptions<sup>18+</sup>对象说明 40 41用于描述Polygon组件绘制属性。 42 43> **说明：** 44> 45> 为规范匿名对象的定义，API 18版本修改了此处的元素定义。其中，保留了历史匿名对象的起始版本信息，会出现外层元素@since版本号高于内层元素版本号的情况，但这不影响接口的使用。 46 47**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 48 49**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 50 51**系统能力：** SystemCapability.ArkUI.ArkUI.Full 52 53| 名称 | 类型 | 只读 | 可选 | 说明 | 54| -------- | -------- | -------- | -------- | -------- | 55| width<sup>7+</sup> | [Length](ts-types.md#length) | 否 | 是 | 宽度，取值范围≥0。<br/>默认值：0<br/>默认单位：vp<br/>异常值按照默认值处理。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 56| height<sup>7+</sup> | [Length](ts-types.md#length) | 否 | 是 | 高度，取值范围≥0。<br/>默认值：0<br/>默认单位：vp<br/>异常值按照默认值处理。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 57 58## 属性 59 60除支持[通用属性](ts-component-general-attributes.md)外，还支持以下属性： 61 62### points 63 64points(value: Array<any>) 65 66设置多边形的顶点坐标列表，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。异常值按照默认值处理。 67 68**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 69 70**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 71 72**系统能力：** SystemCapability.ArkUI.ArkUI.Full 73 74**参数：** 75 76| 参数名 | 类型 | 必填 | 说明 | 77| ------ | ------------------------------------------------------------ | ---- | ------------------------------------- | 78| value | Array<any> | 是 | 多边形的顶点坐标列表。<br/>默认值：[]（空数组）<br/>默认单位：vp | 79 80### fill 81 82fill(value: ResourceColor) 83 84设置填充区域的颜色，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法，异常值按照默认值处理。与通用属性foregroundColor同时设置时，后设置的属性生效。 85 86**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 87 88**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 89 90**系统能力：** SystemCapability.ArkUI.ArkUI.Full 91 92**参数：** 93 94| 参数名 | 类型 | 必填 | 说明 | 95| ------ | ------------------------------------------ | ---- | -------------------------------------- | 96| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 填充区域颜色。<br/>默认值：Color.Black | 97 98### fillOpacity 99 100fillOpacity(value: number | string | Resource) 101 102设置填充区域透明度，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。 103 104**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 105 106**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 107 108**系统能力：** SystemCapability.ArkUI.ArkUI.Full 109 110**参数：** 111 112| 参数名 | 类型 | 必填 | 说明 | 113| ------ | ------------------------------------------------------------ | ---- | ------------------------------ | 114| value | number \| string \| [Resource](ts-types.md#resource) | 是 | 填充区域透明度。<br/>**说明：**<br/>number格式取值范围是[0.0, 1.0]，若给定值小于0.0，则取值为0.0；若给定值大于1.0，则取值为1.0，其余异常值按1.0处理。<br/>string格式支持number格式取值的字符串形式，取值范围与number格式相同。<br/>Resource格式支持系统资源或者应用资源中的字符串，取值范围和number格式相同。<br/>默认值：1 | 115 116### stroke 117 118stroke(value: ResourceColor) 119 120设置边框颜色，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。不设置时，默认边框透明度为0，即没有边框。异常值不会绘制边框。 121 122**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 123 124**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 125 126**系统能力：** SystemCapability.ArkUI.ArkUI.Full 127 128**参数：** 129 130| 参数名 | 类型 | 必填 | 说明 | 131| ------ | ------------------------------------------ | ---- | ---------- | 132| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 边框颜色。 | 133 134### strokeDashArray 135 136strokeDashArray(value: Array<any>) 137 138设置边框间隙，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。取值范围≥0。异常值按照默认值处理。 139 140**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 141 142**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 143 144**系统能力：** SystemCapability.ArkUI.ArkUI.Full 145 146**参数：** 147 148| 参数名 | 类型 | 必填 | 说明 | 149| ------ | ---------------- | ---- | ------------------------- | 150| value | Array<any> | 是 | 边框间隙。<br/>默认值：[]（空数组）<br/>默认单位：vp | 151 152### strokeDashOffset 153 154strokeDashOffset(value: number | string) 155 156设置边框绘制起点的偏移量，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。异常值按照默认值处理。 157 158**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 159 160**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 161 162**系统能力：** SystemCapability.ArkUI.ArkUI.Full 163 164**参数：** 165 166| 参数名 | 类型 | 必填 | 说明 | 167| ------ | -------------------------- | ---- | ------------------------------------ | 168| value | number \| string | 是 | 边框绘制起点的偏移量。<br/>默认值：0<br/>默认单位：vp | 169 170### strokeLineCap 171 172strokeLineCap(value: LineCapStyle) 173 174设置边框端点绘制样式，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。 175 176**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 177 178**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 179 180**系统能力：** SystemCapability.ArkUI.ArkUI.Full 181 182**参数：** 183 184| 参数名 | 类型 | 必填 | 说明 | 185| ------ | ------------------------------------------------- | ---- | ------------------------------------------------ | 186| value | [LineCapStyle](ts-appendix-enums.md#linecapstyle) | 是 | 边框端点绘制样式。<br/>默认值：LineCapStyle.Butt | 187 188### strokeLineJoin 189 190strokeLineJoin(value: LineJoinStyle) 191 192设置边框拐角绘制样式，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。 193 194**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 195 196**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 197 198**系统能力：** SystemCapability.ArkUI.ArkUI.Full 199 200**参数：** 201 202| 参数名 | 类型 | 必填 | 说明 | 203| ------ | --------------------------------------------------- | ---- | -------------------------------------------------- | 204| value | [LineJoinStyle](ts-appendix-enums.md#linejoinstyle) | 是 | 边框拐角绘制样式。<br/>默认值：LineJoinStyle.Miter | 205 206### strokeMiterLimit 207 208strokeMiterLimit(value: number | string) 209 210设置斜接长度与边框宽度比值的极限值，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。斜接长度表示外边框外边交点到内边交点的距离，边框宽度即strokeWidth属性的值。该属性取值需在strokeLineJoin属性取值LineJoinStyle.Miter时生效。 211 212该属性的合法值范围应当大于等于1.0，当取值范围在[0,1)时按1.0处理，其余异常值按默认值处理。 213 214**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 215 216**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 217 218**系统能力：** SystemCapability.ArkUI.ArkUI.Full 219 220**参数：** 221 222| 参数名 | 类型 | 必填 | 说明 | 223| ------ | -------------------------- | ---- | ---------------------------------------------- | 224| value | number \| string | 是 | 斜接长度与边框宽度比值的极限值。<br/>默认值：4 | 225 226### strokeOpacity 227 228strokeOpacity(value: number | string | Resource) 229 230设置边框透明度，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。该属性的取值范围是[0.0, 1.0]，若给定值小于0.0，则取值为0.0；若给定值大于1.0，则取值为1.0，其余异常值按1.0处理 。 231 232**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 233 234**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 235 236**系统能力：** SystemCapability.ArkUI.ArkUI.Full 237 238**参数：** 239 240| 参数名 | 类型 | 必填 | 说明 | 241| ------ | ------------------------------------------------------------ | ---- | -------------------------- | 242| value | number \| string \| [Resource](ts-types.md#resource) | 是 | 边框透明度。<br/>默认值：[stroke](#stroke)接口设置的透明度。 | 243 244### strokeWidth 245 246strokeWidth(value: Length) 247 248设置边框宽度，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。该属性若为string类型, 暂不支持百分比，百分比按照1px处理。 249 250**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 251 252**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 253 254**系统能力：** SystemCapability.ArkUI.ArkUI.Full 255 256**参数：** 257 258| 参数名 | 类型 | 必填 | 说明 | 259| ------ | ---------------------------- | ---- | ------------------------ | 260| value | [Length](ts-types.md#length) | 是 | 边框宽度，取值范围≥0。<br/>默认值：1<br/>默认单位：vp<br/>异常值按照默认值处理。 | 261 262### antiAlias 263 264antiAlias(value: boolean) 265 266设置是否开启抗锯齿效果，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。 267 268**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 269 270**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 271 272**系统能力：** SystemCapability.ArkUI.ArkUI.Full 273 274**参数：** 275 276| 参数名 | 类型 | 必填 | 说明 | 277| ------ | ------- | ---- | ------------------------------------- | 278| value | boolean | 是 | 是否开启抗锯齿效果。<br/>true：开启抗锯齿；false：关闭抗锯齿。<br/>默认值：true | 279 280## 示例 281 282### 示例1（组件属性绘制） 283 284通过points、fill、fillOpacity、stroke属性分别绘制多边形的经过坐标、填充颜色、透明度、边框颜色。 285 286```ts 287// xxx.ets 288@Entry 289@Component 290struct PolygonExample { 291 build() { 292 Column({ space: 10 }) { 293 // 在 100 * 100 的矩形框中绘制一个三角形，起点(0, 0)，经过(50, 100)，终点(100, 0) 294 Polygon({ width: 100, height: 100 }) 295 .points([[0, 0], [50, 100], [100, 0]]) 296 .fill(Color.Green) 297 // 在 100 * 100 的矩形框中绘制一个四边形，起点(0, 0)，经过(0, 100)和(100, 100)，终点(100, 0) 298 Polygon() 299 .width(100) 300 .height(100) 301 .points([[0, 0], [0, 100], [100, 100], [100, 0]]) 302 .fillOpacity(0) 303 .strokeWidth(5) 304 .stroke(Color.Blue) 305 // 在 100 * 100 的矩形框中绘制一个五边形，起点(50, 0)，依次经过(0, 50)、(20, 100)和(80, 100)，终点(100, 50) 306 Polygon() 307 .width(100) 308 .height(100) 309 .points([[50, 0], [0, 50], [20, 100], [80, 100], [100, 50]]) 310 .fill(Color.Red) 311 .fillOpacity(0.6) 312 }.width('100%').margin({ top: 10 }) 313 } 314} 315``` 316 317 318 319### 示例2（宽和高使用不同参数类型绘制多边形） 320 321width、height属性分别使用不同的长度类型绘制图形。 322 323```ts 324// xxx.ets 325@Entry 326@Component 327struct PolygonTypeExample { 328 build() { 329 Column({ space: 10 }) { 330 // 在 100 * 100 的矩形框中绘制一个三角形，起点(0, 0)，经过(50, 100)，终点(100, 0) 331 Polygon({ width: '100', height: '100' })//使用string类型 332 .points([[0, 0], [50, 100], [100, 0]]) 333 // 在 100 * 100 的矩形框中绘制一个四边形，起点(0, 0)，经过(0, 100)和(100, 100)，终点(100, 0) 334 Polygon({ width: 100, height: 100 })// 使用number类型 335 .points([[0, 0], [0, 100], [100, 100], [100, 0]]) 336 .fillOpacity(0) 337 .strokeWidth(5) 338 .stroke(Color.Blue) 339 // 在 100 * 100 的矩形框中绘制一个五边形，起点(50, 0)，依次经过(0, 50)、(20, 100)和(80, 100)，终点(100, 50) 340 Polygon({ width: $r('app.string.PolygonWidth'), height: $r('app.string.PolygonHeight') })// 使用Resource类型，需用户自定义 341 .points([[50, 0], [0, 50], [20, 100], [80, 100], [100, 50]]) 342 .fillOpacity(0.6) 343 }.width('100%').margin({ top: 10 }) 344 } 345} 346``` 347 348 349 350### 示例3（使用attributeModifier动态设置Polygon组件的属性） 351 352以下示例展示了如何使用attributeModifier动态设置Polygon组件的points、fill、fillOpacity、stroke、strokeDashArray、strokeDashOffset、strokeLineCap、strokeLineJoin、strokeMiterLimit、strokeOpacity、strokeWidth和antiAlias属性。 353 354```ts 355// xxx.ets 356class MyPolygonModifier implements AttributeModifier<PolygonAttribute> { 357 applyNormalAttribute(instance: PolygonAttribute): void { 358 // 三角形，起点(0, 0)，经过(50, 100)，终点(100, 0)，填充颜色#707070，填充透明度0.5，边框颜色#2787D9，边框间隙[20]，向左偏移15，线条两端样式为半圆，拐角样式使用尖角连接路径段，斜接长度与边框宽度比值的极限值为5，边框透明度0.5，边框宽度10，抗锯齿开启 359 instance.points([[0, 0], [50, 100], [100, 0]]) 360 instance.fill("#707070") 361 instance.fillOpacity(0.5) 362 instance.stroke("#2787D9") 363 instance.strokeDashArray([20]) 364 instance.strokeDashOffset("15") 365 instance.strokeLineCap(LineCapStyle.Round) 366 instance.strokeLineJoin(LineJoinStyle.Miter) 367 instance.strokeMiterLimit(5) 368 instance.strokeOpacity(0.5) 369 instance.strokeWidth(10) 370 instance.antiAlias(true) 371 } 372} 373 374@Entry 375@Component 376struct PolygonModifierDemo { 377 @State modifier: MyPolygonModifier = new MyPolygonModifier() 378 379 build() { 380 Column() { 381 Polygon() 382 .width(100) 383 .height(100) 384 .attributeModifier(this.modifier) 385 .offset({ x: 20, y: 20 }) 386 } 387 } 388} 389``` 390 391 392
