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