1# Path 2 3The **Path** component is used to draw a custom closed shape based on a specified drawing path. 4 5> **NOTE** 6> 7> This component is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. 8 9 10## Child Components 11 12Not supported 13 14## APIs 15 16Path(options?: PathOptions) 17 18**Widget capability**: This API can be used in ArkTS widgets since API version 9. 19 20**Atomic service API**: This API can be used in atomic services since API version 11. 21 22**System capability**: SystemCapability.ArkUI.ArkUI.Full 23 24**Parameters** 25 26| Name | Type | Mandatory| Description | 27| ------ | ---------------- | ---- | ------------------------------------------------------------ | 28| options | [PathOptions](ts-drawing-components-path.md#pathoptions18) | No | Options for path drawing.| 29 30## PathOptions<sup>18+</sup> 31Describes the options for path drawing. 32 33**Widget capability**: This API can be used in ArkTS widgets since API version 18. 34 35**Atomic service API**: This API can be used in atomic services since API version 18. 36 37**System capability**: SystemCapability.ArkUI.ArkUI.Full 38 39| Name| Type| Mandatory| Description| 40| -------- | -------- | -------- | -------- | 41| width | string \| number | No| Width of the rectangle where the path is located.<br>If the value is invalid or the default value is used, the width required for the content is used.<br>Default unit: vp| 42| height | string \| number | No| Height of the rectangle where the path is located.<br>If the value is invalid or the default value is used, the width required for the content is used.<br>Default unit: vp| 43| [commands](ts-drawing-components-path.md#commands) | string | No| Command string for drawing the path.<br>If the value is invalid or the default value is used, the width required for the content is used. Default value: **''**<br>An invalid value is handled as the default value.| 44 45## Attributes 46 47In addition to the [universal attributes](ts-component-general-attributes.md), the following attributes are supported. 48 49### commands 50 51commands(value: string) 52 53Sets a string of path commands that comply with the [SVG path syntax](ts-drawing-components-path.md#svg-path-syntax). The unit is px. For details about how to convert pixel units, see [Pixel Units](ts-pixel-units.md). 54 55**Widget capability**: This API can be used in ArkTS widgets since API version 9. 56 57**Atomic service API**: This API can be used in atomic services since API version 11. 58 59**System capability**: SystemCapability.ArkUI.ArkUI.Full 60 61**Parameters** 62 63| Name| Type | Mandatory| Description | 64| ------ | ------ | ---- | ----------------------------- | 65| value | string | Yes | Path for drawing a line.<br>Default value: **''**<br>Default unit: px| 66 67### fill 68 69fill(value: ResourceColor) 70 71Sets the color of the fill area. An invalid value is handled as the default value. If this attribute and the universal attribute **foregroundColor** are both set, whichever is set later takes effect. 72 73**Widget capability**: This API can be used in ArkTS widgets since API version 9. 74 75**Atomic service API**: This API can be used in atomic services since API version 11. 76 77**System capability**: SystemCapability.ArkUI.ArkUI.Full 78 79**Parameters** 80 81| Name| Type | Mandatory| Description | 82| ------ | ------------------------------------------ | ---- | -------------------------------------- | 83| value | [ResourceColor](ts-types.md#resourcecolor) | Yes | Color of the fill area.<br>Default value: **Color.Black**| 84 85### fillOpacity 86 87fillOpacity(value: number | string | Resource) 88 89Sets the opacity of the fill area. The value range is [0.0, 1.0]. If the value passed in is less than **0.0**, the opacity is set to **0.0**. If the value passed in is greater than **1.0**, the opacity is set to **1.0**. Any other value is regarded as **1.0**. 90 91**Widget capability**: This API can be used in ArkTS widgets since API version 9. 92 93**Atomic service API**: This API can be used in atomic services since API version 11. 94 95**System capability**: SystemCapability.ArkUI.ArkUI.Full 96 97**Parameters** 98 99| Name| Type | Mandatory| Description | 100| ------ | ------------------------------------------------------------ | ---- | ------------------------------ | 101| value | number \| string \| [Resource](ts-types.md#resource) | Yes | Opacity of the fill area.<br>Default value: **1**| 102 103### stroke 104 105stroke(value: ResourceColor) 106 107Sets the stroke color. If this attribute is not set, the component does not have any stroke. If the value is invalid, no stroke will be drawn. 108 109**Widget capability**: This API can be used in ArkTS widgets since API version 9. 110 111**Atomic service API**: This API can be used in atomic services since API version 11. 112 113**System capability**: SystemCapability.ArkUI.ArkUI.Full 114 115**Parameters** 116 117| Name| Type | Mandatory| Description | 118| ------ | ------------------------------------------ | ---- | ---------- | 119| value | [ResourceColor](ts-types.md#resourcecolor) | Yes | Stroke color.| 120 121### strokeDashArray 122 123strokeDashArray(value: Array<any>) 124 125Sets the stroke dashes. Line segments may overlap when they intersect. The value must be greater than or equal to 0. Invalid values are treated as the default value. 126 127**Widget capability**: This API can be used in ArkTS widgets since API version 9. 128 129**Atomic service API**: This API can be used in atomic services since API version 11. 130 131**System capability**: SystemCapability.ArkUI.ArkUI.Full 132 133**Parameters** 134 135| Name| Type | Mandatory| Description | 136| ------ | ---------------- | ---- | ------------------------- | 137| value | Array<any> | Yes | Stroke dashes.<br>Default value: **[]**<br>Default unit: vp| 138 139### strokeDashOffset 140 141strokeDashOffset(value: number | string) 142 143Sets the line dash offset. An invalid value is handled as the default value. 144 145**Widget capability**: This API can be used in ArkTS widgets since API version 9. 146 147**Atomic service API**: This API can be used in atomic services since API version 11. 148 149**System capability**: SystemCapability.ArkUI.ArkUI.Full 150 151**Parameters** 152 153| Name| Type | Mandatory| Description | 154| ------ | -------------------------- | ---- | ------------------------------------ | 155| value | number \| string | Yes | Line dash offset.<br>Default value: **0**<br>Default unit: vp| 156 157### strokeLineCap 158 159strokeLineCap(value: LineCapStyle) 160 161Sets the style of end points of lines. 162 163**Widget capability**: This API can be used in ArkTS widgets since API version 9. 164 165**Atomic service API**: This API can be used in atomic services since API version 11. 166 167**System capability**: SystemCapability.ArkUI.ArkUI.Full 168 169**Parameters** 170 171| Name| Type | Mandatory| Description | 172| ------ | ------------------------------------------------- | ---- | ------------------------------------------------ | 173| value | [LineCapStyle](ts-appendix-enums.md#linecapstyle) | Yes | Style of the end points of lines.<br>Default value: **LineCapStyle.Butt**| 174 175### strokeLineJoin 176 177strokeLineJoin(value: LineJoinStyle) 178 179Sets the join style of lines. 180 181**Widget capability**: This API can be used in ArkTS widgets since API version 9. 182 183**Atomic service API**: This API can be used in atomic services since API version 11. 184 185**System capability**: SystemCapability.ArkUI.ArkUI.Full 186 187**Parameters** 188 189| Name| Type | Mandatory| Description | 190| ------ | --------------------------------------------------- | ---- | -------------------------------------------------- | 191| value | [LineJoinStyle](ts-appendix-enums.md#linejoinstyle) | Yes | Join style of lines.<br>Default value: **LineJoinStyle.Miter**| 192 193### strokeMiterLimit 194 195strokeMiterLimit(value: number | string) 196 197Sets the limit on the ratio of the miter length to the value of **strokeWidth** used to draw a miter join. The miter length indicates the distance from the outer tip to the inner corner of the miter. This attribute works only when **strokeLineJoin** is set to **LineJoinStyle.Miter**. 198 199The value must be greater than or equal to 1.0. If the value is in the [0, 1) range, the value **1.0** will be used. In other cases, the default value will be used. 200 201**Widget capability**: This API can be used in ArkTS widgets since API version 9. 202 203**Atomic service API**: This API can be used in atomic services since API version 11. 204 205**System capability**: SystemCapability.ArkUI.ArkUI.Full 206 207**Parameters** 208 209| Name| Type | Mandatory| Description | 210| ------ | -------------------------- | ---- | ---------------------------------------------- | 211| value | number \| string | Yes | Limit on the ratio of the miter length to the value of **strokeWidth** used to draw a miter join.<br>Default value: **4**| 212 213### strokeOpacity 214 215strokeOpacity(value: number | string | Resource) 216 217Sets the stroke opacity. The value range is [0.0, 1.0]. If the value passed in is less than **0.0**, the opacity is set to **0.0**. If the value passed in is greater than **1.0**, the opacity is set to **1.0**. Any other value is regarded as **1.0**. 218 219**Widget capability**: This API can be used in ArkTS widgets since API version 9. 220 221**Atomic service API**: This API can be used in atomic services since API version 11. 222 223**System capability**: SystemCapability.ArkUI.ArkUI.Full 224 225**Parameters** 226 227| Name| Type | Mandatory| Description | 228| ------ | ------------------------------------------------------------ | ---- | -------------------------- | 229| value | number \| string \| [Resource](ts-types.md#resource) | Yes | Stroke opacity.<br>Default value: **1**| 230 231### strokeWidth 232 233strokeWidth(value: Length) 234 235Sets the stroke width. If this attribute is of the string type, percentage values are not supported and will be treated as 1 px. 236 237**Widget capability**: This API can be used in ArkTS widgets since API version 9. 238 239**Atomic service API**: This API can be used in atomic services since API version 11. 240 241**System capability**: SystemCapability.ArkUI.ArkUI.Full 242 243**Parameters** 244 245| Name| Type | Mandatory| Description | 246| ------ | ---------------------------- | ---- | ------------------------ | 247| value | [Length](ts-types.md#length) | Yes | Stroke width. The value must be greater than or equal to 0.<br>Default value: **1**<br>Default unit: vp<br>An invalid value is handled as the default value.| 248 249### antiAlias 250 251antiAlias(value: boolean) 252 253Specifies whether anti-aliasing is enabled. 254 255**Widget capability**: This API can be used in ArkTS widgets since API version 9. 256 257**Atomic service API**: This API can be used in atomic services since API version 11. 258 259**System capability**: SystemCapability.ArkUI.ArkUI.Full 260 261**Parameters** 262 263| Name| Type | Mandatory| Description | 264| ------ | ------- | ---- | ------------------------------------- | 265| value | boolean | Yes | Whether anti-aliasing is enabled.<br>**true**: Anti-aliasing is enabled.<br>**false**: Anti-aliasing is disabled.<br>Default value: **true**| 266 267## SVG Path Syntax 268 269The table below lists the supported SVG path commands. 270 271| Command | Name | Parameter | Description | 272| ---- | -------------------------------- | ---------------------------------------- | ---------------------------------------- | 273| M | moveto | (x y) | Starts a new subpath at the point specified by the given (x, y) coordinates. For example, `M 0 0` starts a new subpath at point (0, 0).| 274| L | lineto | (x y) | Draws a line from the current point to the point specified by the given (x, y) coordinates. The specified point becomes the start point of the new subpath. For example, `L 50 50` draws a line from the current point to point (50, 50), which is the start point of the new subpath.| 275| H | horizontal lineto | x | Draws a horizontal line to the given X coordinate. This command is equivalent to an **L** command with the current Y coordinate. For example, **H 50** draws a horizontal line from the current point to (50, current y).| 276| V | vertical lineto | y | Draws a vertical line to the given Y coordinate. This command is equivalent to an **L** command with the current X coordinate. For example, **V 50** draws a vertical line from the current point to (current x, 50).| 277| C | curveto | (x1 y1 x2 y2 x y) | Draws a cubic Bezier curve from the current point to the point specified by the given (x, y) coordinates, with (x1, y1) as the control point of the curve start point and (x2, y2) as the control point of the curve end point. For example, **C100 100 250 100 250 200** draws a cubic Bezier curve from the current point to point (250, 200), which is the start point of the new subpath.| 278| S | smooth curveto | (x2 y2 x y) | Draws a cubic Bezier curve from the current point to the point specified by the given (x, y) coordinates, with (x2, y2) as the control point of the curve end point. If the previous command is **C** or **S**, the control point of the curve start point is the mapping of the control point of the curve end point in the previous command relative to the start point. For example, in **C100 100 250 100 250 200 S400 300 400 200**, the second segment of the cubic Bezier curve uses point (250, 300) as the control point of the curve start point. If there is no previous command or the previous command is not **C** or **S**, the control point of the curve start point coincides with the current point.| 279| Q | quadratic Belzier curve | (x1 y1 x y) | Draws a quadratic Bezier curve from the current point to the point specified by the given (x, y) coordinates, with (x1, y1) as the control point. For example, **Q400 50 600 300** draws a quadratic Bezier curve from the current point to point (600, 300), which is the start point of the new subpath.| 280| T | smooth quadratic Belzier curveto | (x y) | Draws a quadratic Bezier curve from the current point to the point specified by the given (x, y) coordinates. If the previous command is **Q** or **T**, the control point is the mapping of the control point of the curve end point in the previous command relative to the start point. For example, in **Q400 50 600 300 T1000 300**, the second segment of the quadratic Bezier curve uses point (800, 350) as the control point. If there is no previous command or the previous command is not **Q** or **T**, the control point of the curve start point coincides with the current point.| 281| A | elliptical Arc | (rx ry x-axis-rotation large-arc-flag sweep-flag x y) | Draws an elliptical arc from the current point to the point specified by the given (x, y) coordinates. **(rx, ry)** and **x-axis-rotation** define the size and direction of the arc, indicating how the arc rotates relative to the current coordinate system (in degrees). **large-arc-flag** and **sweep-flag** define how the arc is drawn.| 282| Z | closepath | none | Closes the current subpath by connecting the current path back to the initial point of the current subpath. | 283 284For example, **commands('M0 20 L50 50 L50 100 Z')** defines a triangle that starts from position (0, 20), by drawing a line from point (0, 20) to point (50, 50), then a line from point (50, 50) to point (50, 100), and finally a line from point (50, 100) to point (0, 20). 285 286## Example 287 288This example demonstrates how to use **commands**, **fillOpacity**, and **stroke** to draw a closed shape with the specified path, opacity, and stroke color. 289 290```ts 291// xxx.ets 292@Entry 293@Component 294struct PathExample { 295 build() { 296 Column({ space: 10 }) { 297 Text('Straight line') 298 .fontSize(11) 299 .fontColor(0xCCCCCC) 300 .width('90%') 301 // Draw a straight line whose length is 600 px and width is 3 vp. 302 Path() 303 .width('600px') 304 .height('10px') 305 .commands('M0 0 L600 0') 306 .stroke(Color.Black) 307 .strokeWidth(3) 308 309 Text('Straight line graph') 310 .fontSize(11) 311 .fontColor(0xCCCCCC) 312 .width('90%') 313 // Draw a straight line. 314 Flex({ justifyContent: FlexAlign.SpaceBetween }) { 315 Path() 316 .width('210px') 317 .height('310px') 318 .commands('M100 0 L200 240 L0 240 Z') 319 .fillOpacity(0) 320 .stroke(Color.Black) 321 .strokeWidth(3) 322 Path() 323 .width('210px') 324 .height('310px') 325 .commands('M0 0 H200 V200 H0 Z') 326 .fillOpacity(0) 327 .stroke(Color.Black) 328 .strokeWidth(3) 329 Path() 330 .width('210px') 331 .height('310px') 332 .commands('M100 0 L0 100 L50 200 L150 200 L200 100 Z') 333 .fillOpacity(0) 334 .stroke(Color.Black) 335 .strokeWidth(3) 336 }.width('95%') 337 338 Text('Curve graphics').fontSize(11).fontColor(0xCCCCCC).width('90%') 339 // Draw an arc. 340 Flex({ justifyContent: FlexAlign.SpaceBetween }) { 341 Path() 342 .width('250px') 343 .height('310px') 344 .commands("M0 300 S100 0 240 300 Z") 345 .fillOpacity(0) 346 .stroke(Color.Black) 347 .strokeWidth(3) 348 Path() 349 .width('210px') 350 .height('310px') 351 .commands('M0 150 C0 100 140 0 200 150 L100 300 Z') 352 .fillOpacity(0) 353 .stroke(Color.Black) 354 .strokeWidth(3) 355 Path() 356 .width('210px') 357 .height('310px') 358 .commands('M0 100 A30 20 20 0 0 200 100 Z') 359 .fillOpacity(0) 360 .stroke(Color.Black) 361 .strokeWidth(3) 362 }.width('95%') 363 }.width('100%') 364 .margin({ top: 5 }) 365 } 366} 367``` 368 369 370
