1# Path 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 24Path(options?: PathOptions) 25 26**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 27 28**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 29 30**系统能力：** SystemCapability.ArkUI.ArkUI.Full 31 32**参数:** 33 34| 参数名 | 类型 | 必填 | 说明 | 35| ------ | ---------------- | ---- | ------------------------------------------------------------ | 36| options | [PathOptions](ts-drawing-components-path.md#pathoptions18对象说明) | 否 | Path绘制区域。| 37 38## PathOptions<sup>18+</sup>对象说明 39 40用于描述Path组件绘制属性。 41 42> **说明：** 43> 44> 为规范匿名对象的定义，API 18版本修改了此处的元素定义。其中，保留了历史匿名对象的起始版本信息，会出现外层元素@since版本号高于内层元素版本号的情况，但这不影响接口的使用。 45 46**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 47 48**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 49 50**系统能力：** SystemCapability.ArkUI.ArkUI.Full 51 52| 名称 | 类型 | 只读 | 可选 | 说明 | 53| -------- | -------- | -------- | -------- | -------- | 54| width<sup>7+</sup> | [Length](ts-types.md#length) | 否 | 是 | 路径所在矩形的宽度。<br/>值为异常值或缺省时按照自身内容需要的宽度处理。<br/>默认单位：vp<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 55| height<sup>7+</sup> | [Length](ts-types.md#length) | 否 | 是 | 路径所在矩形的高度。<br/>值为异常值或缺省时按照自身内容需要的高度处理。<br/>默认单位：vp<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 56| [commands<sup>7+</sup>](ts-drawing-components-path.md#commands) | [ResourceStr](ts-types.md#resourcestr) | 否 | 是 | 路径绘制的命令字符串。<br/>值为异常值或缺省时按照自身内容需要的宽高处理。默认值：空字符串<br/>异常值按照默认值处理。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 57 58## 属性 59 60除支持[通用属性](ts-component-general-attributes.md)外，还支持以下属性： 61 62### commands 63 64commands(value: [ResourceStr](ts-types.md#resourcestr)) 65 66设置符合[SVG路径描述规范](ts-drawing-components-path.md#svg路径描述规范)的命令字符串，单位为px。像素单位转换方法请参考[像素单位转换](ts-pixel-units.md)。 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 | [ResourceStr](ts-types.md#resourcestr) | 是 | 线条绘制的路径。<br/>默认值：空字符串<br/>默认单位：px | 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)动态设置属性方法，不设置时，默认边框颜色为不透明的黑色。异常值不会绘制边框线条。 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/>默认值：1 | 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## SVG路径描述规范 281 282SVG路径描述规范支持的命令如下： 283 284| 命令 | 名称 | 参数 | 说明 | 285| ---- | -------------------------------- | ---------------------------------------- | ---------------------------------------- | 286| M | moveto | （x y） | 在给定的 (x, y) 坐标处开始一个新的子路径。例如，`M 0 0` 表示将（0, 0）点作为新子路径的起始点。 | 287| L | lineto | （x y） | 从当前点到给定的 (x, y) 坐标画一条线，该坐标成为新的当前点。例如，`L 50 50` 表示绘制当前点到（50, 50）点的直线，并将（50, 50）点作为新子路径的起始点。 | 288| H | horizontal lineto | x | 从当前点绘制一条水平线到给定的x坐标，等效于将y坐标指定为当前点y坐标的L命令。例如，当前点为(100, 100)，`H 50 ` 表示绘制当前点到（50, 100）点的直线，并将（50, 100）点作为新子路径的起始点。 | 289| V | vertical lineto | y | 从当前点绘制一条垂直线到给定的y坐标，等效于将x坐标指定为当前点x坐标的L命令。例如，当前点为(100, 100)，`V 50 ` 表示绘制当前点到（100, 50）点的直线，并将（100, 50）点作为新子路径的起始点。 | 290| C | curveto | (x1 y1 x2 y2 x y) | 使用 (x1, y1) 作为曲线起点的控制点， (x2, y2) 作为曲线终点的控制点，从当前点到 (x, y) 绘制三次贝塞尔曲线。例如，`C100 100 250 100 250 200 ` 表示绘制当前点到（250, 200）点的三次贝塞尔曲线，并将（250, 200）点作为新子路径的起始点。 | 291| S | smooth curveto | (x2 y2 x y) | (x2, y2) 作为曲线终点的控制点，绘制从当前点到 (x, y) 绘制三次贝塞尔曲线。若前一个命令是C或S，则起点控制点是上一个命令的终点控制点相对于起点的映射。 例如，`C100 100 250 100 250 200 S400 300 400 200`第二段贝塞尔曲线的起点控制点为（250, 300）。如果没有前一个命令或者前一个命令不是 C或S，则第一个控制点与当前点重合。 | 292| Q | quadratic Belzier curve | (x1 y1 x y) | 使用 (x1, y1) 作为控制点，从当前点到 (x, y) 绘制二次贝塞尔曲线。例如，`Q400 50 600 300 ` 表示绘制当前点到（600, 300）点的二次贝塞尔曲线，并将（600, 300）点作为新子路径的起始点。 | 293| T | smooth quadratic Belzier curveto | (x y) | 绘制从当前点到 (x, y) 绘制二次贝塞尔曲线。若前一个命令是Q或T，则控制点是上一个命令的终点控制点相对于起点的映射。 例如，`Q400 50 600 300 T1000 300`第二段贝塞尔曲线的控制点为（800, 350）。 如果没有前一个命令或者前一个命令不是 Q或T，则第一个控制点与当前点重合。 | 294| A | elliptical Arc | (rx ry x-axis-rotation large-arc-flag sweep-flag x y) | 从当前点到 (x, y) 绘制一条椭圆弧。椭圆的大小和方向由两个半径 (rx, ry) 和x-axis-rotation定义，指示整个椭圆相对于当前坐标系如何旋转（以度为单位）。 large-arc-flag 和 sweep-flag确定弧的绘制方式。 | 295| Z | closepath | none | 通过将当前路径连接回当前子路径的初始点来关闭当前子路径。 | 296 297例如： commands('M0 20 L50 50 L50 100 Z')定义了一个三角形，起始于位置（0，20），接着绘制点（0，20）到点（50，50）的直线，再绘制从点（50，50）到点（50，100）的直线，最后绘制从点（50，100）到（0，20）的直线关闭路径，形成封闭三角形。 298 299## 示例 300 301### 示例1（组件属性绘制） 302 303通过commands、fillOpacity、stroke属性分别绘制路径、透明度、边框颜色。 304 305```ts 306// xxx.ets 307@Entry 308@Component 309struct PathExample { 310 build() { 311 Column({ space: 10 }) { 312 Text('Straight line') 313 .fontSize(11) 314 .fontColor(0xCCCCCC) 315 .width('90%') 316 // 绘制一条长600px，宽3vp的直线 317 Path() 318 .width('600px') 319 .height('10px') 320 .commands('M0 0 L600 0') 321 .stroke(Color.Black) 322 .strokeWidth(3) 323 324 Text('Straight line graph') 325 .fontSize(11) 326 .fontColor(0xCCCCCC) 327 .width('90%') 328 // 绘制直线图形 329 Flex({ justifyContent: FlexAlign.SpaceBetween }) { 330 Path() 331 .width('210px') 332 .height('310px') 333 .commands('M100 0 L200 240 L0 240 Z') 334 .fillOpacity(0) 335 .stroke(Color.Black) 336 .strokeWidth(3) 337 Path() 338 .width('210px') 339 .height('310px') 340 .commands('M0 0 H200 V200 H0 Z') 341 .fillOpacity(0) 342 .stroke(Color.Black) 343 .strokeWidth(3) 344 Path() 345 .width('210px') 346 .height('310px') 347 .commands('M100 0 L0 100 L50 200 L150 200 L200 100 Z') 348 .fillOpacity(0) 349 .stroke(Color.Black) 350 .strokeWidth(3) 351 }.width('95%') 352 353 Text('Curve graphics').fontSize(11).fontColor(0xCCCCCC).width('90%') 354 // 绘制弧线图形 355 Flex({ justifyContent: FlexAlign.SpaceBetween }) { 356 Path() 357 .width('250px') 358 .height('310px') 359 .commands("M0 300 S100 0 240 300 Z") 360 .fillOpacity(0) 361 .stroke(Color.Black) 362 .strokeWidth(3) 363 Path() 364 .width('210px') 365 .height('310px') 366 .commands('M0 150 C0 100 140 0 200 150 L100 300 Z') 367 .fillOpacity(0) 368 .stroke(Color.Black) 369 .strokeWidth(3) 370 Path() 371 .width('210px') 372 .height('310px') 373 .commands('M0 100 A30 20 20 0 0 200 100 Z') 374 .fillOpacity(0) 375 .stroke(Color.Black) 376 .strokeWidth(3) 377 }.width('95%') 378 }.width('100%') 379 .margin({ top: 5 }) 380 } 381} 382``` 383 384 385 386### 示例2（使用不同参数类型绘制路径） 387 388width、height、commands属性分别使用不同的长度类型绘制图形。 389 390```ts 391// xxx.ets 392@Entry 393@Component 394struct PathTypeExample { 395 build() { 396 Column({ space: 10 }) { 397 // 宽、高、命令字符串使用string类型，绘制一条直线 398 Path({ width: '600px', height: '10px' }) 399 .commands('M0 0 L600 0') 400 .fillOpacity(0) 401 .stroke(Color.Black) 402 .strokeWidth(3) 403 // 宽、高使用number类型，绘制一个弧线图形 404 Path({ width: 200, height: 200 }) 405 .commands('M0 0 H200 V200 H0 Z') 406 .fillOpacity(0) 407 .stroke(Color.Black) 408 .strokeWidth(3) 409 // 宽、高、命令字符串使用Resource类型（需用户自定义），绘制一个弧线图形 410 Path({ width: $r('app.string.PathWidth'), height: $r('app.string.PathHeight') }) 411 .commands($r('app.string.PathCommands')) 412 .fillOpacity(0) 413 .stroke(Color.Black) 414 .strokeWidth(3) 415 }.width('100%') 416 .margin({ top: 5 }) 417 } 418} 419``` 420 421 422 423### 示例3（使用attributeModifier动态设置Path组件的属性） 424 425以下示例展示了如何使用attributeModifier动态设置Path组件的commands、fill、fillOpacity、stroke、strokeDashArray、strokeDashOffset、strokeLineCap、strokeLineJoin、strokeMiterLimit、strokeOpacity、strokeWidth和antiAlias属性。 426 427```ts 428// xxx.ets 429class MyPathModifier implements AttributeModifier<PathAttribute> { 430 applyNormalAttribute(instance: PathAttribute): void { 431 // 使用字符串commands绘制一个三角形，填充颜色#707070，填充透明度0.5，边框颜色#2787D9，边框间隙[20]，向左偏移15，线条两端样式为半圆，拐角样式使用尖角连接路径段，斜接长度与边框宽度比值的极限值为5，边框透明度0.5，边框宽度10，抗锯齿开启 432 instance.commands('M100 0 L200 240 L0 240 Z') 433 instance.fill("#707070") 434 instance.fillOpacity(0.5) 435 instance.stroke("#2787D9") 436 instance.strokeDashArray([20]) 437 instance.strokeDashOffset("15") 438 instance.strokeLineCap(LineCapStyle.Round) 439 instance.strokeLineJoin(LineJoinStyle.Miter) 440 instance.strokeMiterLimit(5) 441 instance.strokeOpacity(0.5) 442 instance.strokeWidth(10) 443 instance.antiAlias(true) 444 } 445} 446 447@Entry 448@Component 449struct PathModifierDemo { 450 @State modifier: MyPathModifier = new MyPathModifier() 451 452 build() { 453 Column() { 454 Path() 455 .attributeModifier(this.modifier) 456 .offset({ x: 20, y: 20 }) 457 } 458 } 459} 460``` 461 462 463
