1# Path 2 3The **Path** component is used to define a closed shape. 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(value?: { width?: number | string; height?: number | string; commands?: string }) 17 18**Widget capability**: This API can be used in ArkTS widgets since API version 9. 19 20**Parameters** 21 22| Name | Type | Mandatory| Description | 23| -------------------------------------------------- | ---------------- | ---- | ------------------------------------------------------------ | 24| width | number \| string | No | Width of the rectangle where the path is located.<br>**NOTE**<br>If the value is invalid or the default value is used, the width required for the content is used.| 25| height | number \| string | No | Height of the rectangle where the path is located.<br>**NOTE**<br>If the value is invalid or the default value is used, the height required for the content is used.| 26| [commands](ts-drawing-components-path.md#commands) | string | No | Command for drawing the path.<br>Default value: **''**<br>**NOTE**<br>An invalid value is handled as the default value.| 27 28## Attributes 29 30In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported. 31 32### commands 33 34commands(value: string) 35 36Sets the command string for path drawing. The unit is px. For details about how to convert pixel units, see [Pixel Units](ts-pixel-units.md). 37 38**Widget capability**: This API can be used in ArkTS widgets since API version 9. 39 40**System capability**: SystemCapability.ArkUI.ArkUI.Full 41 42**Parameters** 43 44| Name| Type | Mandatory| Description | 45| ------ | ------ | ---- | ----------------------------- | 46| value | string | Yes | Path for drawing a line.<br>Default value: **''**| 47 48### fill 49 50fill(value: ResourceColor) 51 52Sets the color of the fill area. An invalid value is handled as the default value. 53 54**Widget capability**: This API can be used in ArkTS widgets since API version 9. 55 56**System capability**: SystemCapability.ArkUI.ArkUI.Full 57 58**Parameters** 59 60| Name| Type | Mandatory| Description | 61| ------ | ------------------------------------------ | ---- | -------------------------------------- | 62| value | [ResourceColor](ts-types.md#resourcecolor) | Yes | Color of the fill area.<br>Default value: **Color.Black**| 63 64### fillOpacity 65 66fillOpacity(value: number | string | Resource) 67 68Sets 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**. 69 70**Widget capability**: This API can be used in ArkTS widgets since API version 9. 71 72**System capability**: SystemCapability.ArkUI.ArkUI.Full 73 74**Parameters** 75 76| Name| Type | Mandatory| Description | 77| ------ | ------------------------------------------------------------ | ---- | ------------------------------ | 78| value | number \| string \| [Resource](ts-types.md#resource) | Yes | Opacity of the fill area.<br>Default value: **1**| 79 80### stroke 81 82stroke(value: ResourceColor) 83 84Sets 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. 85 86**Widget capability**: This API can be used in ArkTS widgets since API version 9. 87 88**System capability**: SystemCapability.ArkUI.ArkUI.Full 89 90**Parameters** 91 92| Name| Type | Mandatory| Description | 93| ------ | ------------------------------------------ | ---- | ---------- | 94| value | [ResourceColor](ts-types.md#resourcecolor) | Yes | Stroke color.| 95 96### strokeDashArray 97 98strokeDashArray(value: Array<any>) 99 100Sets the stroke dashes. Line segments may overlap when they intersect. An invalid value is handled as the default value. 101 102**Widget capability**: This API can be used in ArkTS widgets since API version 9. 103 104**System capability**: SystemCapability.ArkUI.ArkUI.Full 105 106**Parameters** 107 108| Name| Type | Mandatory| Description | 109| ------ | ---------------- | ---- | ------------------------- | 110| value | Array<any> | Yes | Stroke dashes.<br>Default value: **[]**| 111 112### strokeDashOffset 113 114strokeDashOffset(value: number | string) 115 116Sets the line dash offset. An invalid value is handled as the default value. 117 118**Widget capability**: This API can be used in ArkTS widgets since API version 9. 119 120**System capability**: SystemCapability.ArkUI.ArkUI.Full 121 122**Parameters** 123 124| Name| Type | Mandatory| Description | 125| ------ | -------------------------- | ---- | ------------------------------------ | 126| value | number \| string | Yes | Line dash offset.<br>Default value: **0**| 127 128### strokeLineCap 129 130strokeLineCap(value: LineCapStyle) 131 132Sets the style of end points of lines. 133 134**Widget capability**: This API can be used in ArkTS widgets since API version 9. 135 136**System capability**: SystemCapability.ArkUI.ArkUI.Full 137 138**Parameters** 139 140| Name| Type | Mandatory| Description | 141| ------ | ------------------------------------------------- | ---- | ------------------------------------------------ | 142| value | [LineCapStyle](ts-appendix-enums.md#linecapstyle) | Yes | Style of the end points of lines.<br>Default value: **LineCapStyle.Butt**| 143 144### strokeLineJoin 145 146strokeLineJoin(value: LineJoinStyle) 147 148Sets the join style of lines. 149 150**Widget capability**: This API can be used in ArkTS widgets since API version 9. 151 152**System capability**: SystemCapability.ArkUI.ArkUI.Full 153 154**Parameters** 155 156| Name| Type | Mandatory| Description | 157| ------ | --------------------------------------------------- | ---- | -------------------------------------------------- | 158| value | [LineJoinStyle](ts-appendix-enums.md#linejoinstyle) | Yes | Join style of lines.<br>Default value: **LineJoinStyle.Miter**| 159 160### strokeMiterLimit 161 162strokeMiterLimit(value: number | string) 163 164Sets 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**. 165 166The 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. 167 168**Widget capability**: This API can be used in ArkTS widgets since API version 9. 169 170**System capability**: SystemCapability.ArkUI.ArkUI.Full 171 172**Parameters** 173 174| Name| Type | Mandatory| Description | 175| ------ | -------------------------- | ---- | ---------------------------------------------- | 176| 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**| 177 178### strokeOpacity 179 180strokeOpacity(value: number | string | Resource) 181 182Sets 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**. 183 184**Widget capability**: This API can be used in ArkTS widgets since API version 9. 185 186**System capability**: SystemCapability.ArkUI.ArkUI.Full 187 188**Parameters** 189 190| Name| Type | Mandatory| Description | 191| ------ | ------------------------------------------------------------ | ---- | -------------------------- | 192| value | number \| string \| [Resource](ts-types.md#resource) | Yes | Stroke opacity.<br>Default value: **1**| 193 194### strokeWidth 195 196strokeWidth(value: Length) 197 198Sets the stroke width. If of the string type, this attribute cannot be set in percentage. A percentage is processed as 1 px. 199 200**Widget capability**: This API can be used in ArkTS widgets since API version 9. 201 202**System capability**: SystemCapability.ArkUI.ArkUI.Full 203 204**Parameters** 205 206| Name| Type | Mandatory| Description | 207| ------ | ---------------------------- | ---- | ------------------------ | 208| value | [Length](ts-types.md#length) | Yes | Stroke width.<br>Default value: **1**| 209 210### antiAlias 211 212antiAlias(value: boolean) 213 214Specifies whether anti-aliasing is enabled. 215 216**Widget capability**: This API can be used in ArkTS widgets since API version 9. 217 218**System capability**: SystemCapability.ArkUI.ArkUI.Full 219 220**Parameters** 221 222| Name| Type | Mandatory| Description | 223| ------ | ------- | ---- | ------------------------------------- | 224| value | boolean | Yes | Whether anti-aliasing is enabled.<br>Default value: **true**| 225 226## Commands 227 228The supported commands are as follows: 229 230| Command | Name | Parameter | Description | 231| ---- | -------------------------------- | ---------------------------------------- | ---------------------------------------- | 232| 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).| 233| 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.| 234| H | horizontal lineto | x | Draws a horizontal line from the current point. This command is equivalent to the **L** command where the y-coordinate is 0. For example, `H 50 ` draws a line from the current point to point (50, 0), which is the start point of the new subpath.| 235| V | vertical lineto | y | Draws a vertical line from the current point. This command is equivalent to the **L** command where the x-coordinate is 0. For example, `V 50 ` draws a line from the current point to point (0, 50), which is the start point of the new subpath.| 236| 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.| 237| 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.| 238| 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.| 239| 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.| 240| 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.| 241| Z | closepath | none | Closes the current subpath by connecting the current path back to the initial point of the current subpath. | 242 243For 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). 244 245## Example 246 247```ts 248// xxx.ets 249@Entry 250@Component 251struct PathExample { 252 build() { 253 Column({ space: 10 }) { 254 Text('Straight line') 255 .fontSize(11) 256 .fontColor(0xCCCCCC) 257 .width('90%') 258 // Draw a straight line whose length is 600 px and width is 3 vp. 259 Path() 260 .width('600px') 261 .height('10px') 262 .commands('M0 0 L600 0') 263 .stroke(Color.Black) 264 .strokeWidth(3) 265 266 Text('Straight line graph') 267 .fontSize(11) 268 .fontColor(0xCCCCCC) 269 .width('90%') 270 // Draw a straight line. 271 Flex({ justifyContent: FlexAlign.SpaceBetween }) { 272 Path() 273 .width('210px') 274 .height('310px') 275 .commands('M100 0 L200 240 L0 240 Z') 276 .fillOpacity(0) 277 .stroke(Color.Black) 278 .strokeWidth(3) 279 Path() 280 .width('210px') 281 .height('310px') 282 .commands('M0 0 H200 V200 H0 Z') 283 .fillOpacity(0) 284 .stroke(Color.Black) 285 .strokeWidth(3) 286 Path() 287 .width('210px') 288 .height('310px') 289 .commands('M100 0 L0 100 L50 200 L150 200 L200 100 Z') 290 .fillOpacity(0) 291 .stroke(Color.Black) 292 .strokeWidth(3) 293 }.width('95%') 294 295 Text('Curve graphics').fontSize(11).fontColor(0xCCCCCC).width('90%') 296 // Draw an arc. 297 Flex({ justifyContent: FlexAlign.SpaceBetween }) { 298 Path() 299 .width('250px') 300 .height('310px') 301 .commands("M0 300 S100 0 240 300 Z") 302 .fillOpacity(0) 303 .stroke(Color.Black) 304 .strokeWidth(3) 305 Path() 306 .width('210px') 307 .height('310px') 308 .commands('M0 150 C0 100 140 0 200 150 L100 300 Z') 309 .fillOpacity(0) 310 .stroke(Color.Black) 311 .strokeWidth(3) 312 Path() 313 .width('210px') 314 .height('310px') 315 .commands('M0 100 A30 20 20 0 0 200 100 Z') 316 .fillOpacity(0) 317 .stroke(Color.Black) 318 .strokeWidth(3) 319 }.width('95%') 320 }.width('100%') 321 .margin({ top: 5 }) 322 } 323} 324``` 325 326 327
