1# @ohos.arkui.shape (Shape) 2 3The **shape** module provides **clipShape** and **maskShape** APIs to allow you to pass in various shapes. 4 5 6> **NOTE** 7> 8> The initial APIs of this module are supported since API version 12. Newly added APIs will be marked with a superscript to indicate their earliest API version. 9> 10> You can preview how this component looks on a real device, but not in DevEco Studio Previewer. 11 12## Modules to Import 13 14```ts 15import { CircleShape, EllipseShape, PathShape, RectShape } from "@kit.ArkUI"; 16``` 17 18## CircleShape 19 20Represents a circle shape used in the **clipShape** and **maskShape** APIs. 21 22This API inherits from [BaseShape](#baseshape). 23 24**Widget capability**: This API can be used in ArkTS widgets since API version 12. 25 26**Atomic service API**: This API can be used in atomic services since API version 12. 27 28**System capability**: SystemCapability.ArkUI.ArkUI.Full 29 30### constructor 31 32constructor(options?: ShapeSize) 33 34A constructor used to create a **CircleShape** object. 35 36**Widget capability**: This API can be used in ArkTS widgets since API version 12. 37 38**Atomic service API**: This API can be used in atomic services since API version 12. 39 40**System capability**: SystemCapability.ArkUI.ArkUI.Full 41 42| Name | Type | Mandatory| Description | 43| ----------- | -------------------------------------------------- | ---- | -------------------------------------------- | 44| options | [ShapeSize](#shapesize) | No| Size of the shape.| 45 46## EllipseShape 47 48Represents an ellipse shape used in the **clipShape** and **maskShape** APIs. 49 50This API inherits from [BaseShape](#baseshape). 51 52**Widget capability**: This API can be used in ArkTS widgets since API version 12. 53 54**Atomic service API**: This API can be used in atomic services since API version 12. 55 56**System capability**: SystemCapability.ArkUI.ArkUI.Full 57 58### constructor 59 60constructor(options?: ShapeSize) 61 62A constructor used to create an **EllipseShape** object. 63 64**Widget capability**: This API can be used in ArkTS widgets since API version 12. 65 66**Atomic service API**: This API can be used in atomic services since API version 12. 67 68**System capability**: SystemCapability.ArkUI.ArkUI.Full 69 70| Name | Type | Mandatory| Description | 71| ----------- | -------------------------------------------------- | ---- | -------------------------------------------- | 72| options | [ShapeSize](#shapesize) | No| Size of the shape.| 73 74## PathShape 75 76Represents a path used in the **clipShape** and **maskShape** APIs. 77 78This API inherits from [CommonShapeMethod](#commonshapemethod). 79 80**Widget capability**: This API can be used in ArkTS widgets since API version 12. 81 82**Atomic service API**: This API can be used in atomic services since API version 12. 83 84**System capability**: SystemCapability.ArkUI.ArkUI.Full 85 86### constructor 87 88constructor(options?: PathShapeOptions) 89 90A constructor used to create a **PathShape** object. 91 92**System capability**: SystemCapability.ArkUI.ArkUI.Full 93 94**Atomic service API**: This API can be used in atomic services since API version 12. 95 96**Widget capability**: This API can be used in ArkTS widgets since API version 12. 97 98| Name | Type | Mandatory| Description | 99| ----------- | -------------------------------------------------- | ---- | -------------------------------------------- | 100| options | [PathShapeOptions](#pathshapeoptions) | No| Path parameters.| 101 102### commands 103 104commands(commands: string): PathShape 105 106Sets the path drawing commands. 107 108**Widget capability**: This API can be used in ArkTS widgets since API version 12. 109 110**Atomic service API**: This API can be used in atomic services since API version 12. 111 112**System capability**: SystemCapability.ArkUI.ArkUI.Full 113 114**Parameters** 115 116| Name | Type | Mandatory| Description | 117| ----------- | -------------------------------------------------- | ---- | -------------------------------------------- | 118| commands | string | Yes| Path drawing commands.| 119 120**Return value** 121 122| Type | Description | 123| ------ | ------------------------ | 124| PathShape | **PathShape** object.| 125 126## RectShape 127 128Represents a rectangle shape used in the **clipShape** and **maskShape** APIs. 129 130This API inherits from [BaseShape](#baseshape). 131 132**Widget capability**: This API can be used in ArkTS widgets since API version 12. 133 134**Atomic service API**: This API can be used in atomic services since API version 12. 135 136**System capability**: SystemCapability.ArkUI.ArkUI.Full 137 138### constructor 139 140constructor(options?: RectShapeOptions | RoundRectShapeOptions) 141 142A constructor used to create a **RectShape** object. 143 144**Widget capability**: This API can be used in ArkTS widgets since API version 12. 145 146**Atomic service API**: This API can be used in atomic services since API version 12. 147 148**System capability**: SystemCapability.ArkUI.ArkUI.Full 149 150| Name | Type | Mandatory| Description | 151| ----------- | -------------------------------------------------- | ---- | -------------------------------------------- | 152| options | [RectShapeOptions](#rectshapeoptions) \| [RoundRectShapeOptions](#roundrectshapeoptions) | No| Rectangle parameters.| 153 154### radiusWidth 155 156radiusWidth(rWidth: number | string): RectShape 157 158Sets the radius width of the rectangle border corners. 159 160**Widget capability**: This API can be used in ArkTS widgets since API version 12. 161 162**Atomic service API**: This API can be used in atomic services since API version 12. 163 164**System capability**: SystemCapability.ArkUI.ArkUI.Full 165 166**Parameters** 167 168| Name | Type | Mandatory| Description | 169| ----------- | -------------------------------------------------- | ---- | -------------------------------------------- | 170| rWidth | number \| string | Yes| Radius width of the rectangle border corners.<br> If the type is number, the value range is [0, +∞). If the type is string, the value represents a length.| 171 172**Return value** 173 174| Type | Description | 175| ------ | ------------------------ | 176| RectShape | **RectShape** object.| 177 178### radiusHeight 179 180radiusHeight(rHeight: number | string): RectShape 181 182Sets the radius height of the rectangle border corners. 183 184**Widget capability**: This API can be used in ArkTS widgets since API version 12. 185 186**Atomic service API**: This API can be used in atomic services since API version 12. 187 188**System capability**: SystemCapability.ArkUI.ArkUI.Full 189 190**Parameters** 191 192| Name | Type | Mandatory| Description | 193| ----------- | -------------------------------------------------- | ---- | -------------------------------------------- | 194| rHeight | number \| string | Yes| Radius height of the rectangle border corners.<br> If the type is number, the value range is [0, +∞). If the type is string, the value represents a length.| 195 196**Return value** 197 198| Type | Description | 199| ------ | ------------------------ | 200| RectShape | **RectShape** object.| 201 202### radius 203 204radius(radius: number | string | Array<number \| string>): RectShape 205 206Sets the radius of the rectangle border corners. 207 208**Widget capability**: This API can be used in ArkTS widgets since API version 12. 209 210**Atomic service API**: This API can be used in atomic services since API version 12. 211 212**System capability**: SystemCapability.ArkUI.ArkUI.Full 213 214**Parameters** 215 216| Name | Type | Mandatory| Description | 217| ----------- | -------------------------------------------------- | ---- | -------------------------------------------- | 218| radius | number \| string \| Array<number \| string> | Yes| Radius of the rectangle border corners. When an array is provided, it should contain exactly four elements, corresponding to the radius of the upper left, upper right, lower left, and lower right corners of the rectangle, respectively. If more than four elements are contained, only the first four are accepted.<br> If the type is number, the value range is [0, +∞). If the type is string, the value represents a length.| 219 220**Return value** 221 222| Type | Description | 223| ------ | ------------------------ | 224| RectShape | **RectShape** object.| 225 226 227## ShapeSize 228 229Describes the size of a shape. 230 231**Widget capability**: This API can be used in ArkTS widgets since API version 12. 232 233**Atomic service API**: This API can be used in atomic services since API version 12. 234 235**System capability**: SystemCapability.ArkUI.ArkUI.Full 236 237| Name | Type | Mandatory | Description | 238| ----------- | -------------------------------------------------- | -------------------------------------------- | -------------------------------------------- | 239| width | number \| string | No| Width of the shape.<br> If the type is number, the value range is [0, +∞). If the type is string, the value represents a length.<br>Unit: vp.| 240| height | number \| string | No| Height of the shape.<br> If the type is number, the value range is [0, +∞). If the type is string, the value represents a length.<br>Unit: vp.| 241 242## PathShapeOptions 243 244Represents the parameter of the constructor used to create a **PathShape** object. 245 246**Widget capability**: This API can be used in ArkTS widgets since API version 12. 247 248**Atomic service API**: This API can be used in atomic services since API version 12. 249 250**System capability**: SystemCapability.ArkUI.ArkUI.Full 251 252| Name | Type | Mandatory | Description | 253| ----------- | -------------------------------------------------- | -------------------------------------------- | -------------------------------------------- | 254| commands | string | No| Path drawing commands. For details, see [commands](./arkui-ts/ts-drawing-components-path.md#commands).| 255 256## RectShapeOptions 257 258Represents the parameter of the constructor used to create a **RectShape** object. 259 260This API inherits from [ShapeSize](#shapesize). 261 262**Widget capability**: This API can be used in ArkTS widgets since API version 12. 263 264**Atomic service API**: This API can be used in atomic services since API version 12. 265 266**System capability**: SystemCapability.ArkUI.ArkUI.Full 267 268| Name | Type | Mandatory | Description | 269| ----------- | -------------------------------------------------- | -------------------------------------------- | -------------------------------------------- | 270| radius | number \| string \| Array<number \| string> | No| Radius of the rectangle border corners.<br> If the type is number, the value range is [0, +∞). If the type is string, the value represents a length.| 271 272## RoundRectShapeOptions 273 274Represents the parameter of the constructor used to create a **RectShape** object with rounded corners. 275 276This API inherits from [ShapeSize](#shapesize). 277 278**Widget capability**: This API can be used in ArkTS widgets since API version 12. 279 280**Atomic service API**: This API can be used in atomic services since API version 12. 281 282**System capability**: SystemCapability.ArkUI.ArkUI.Full 283 284| Name | Type | Mandatory | Description | 285| ----------- | -------------------------------------------------- | -------------------------------------------- | -------------------------------------------- | 286| radiusWidth | number \| string | No| Radius width of the rectangle border corners.<br> If the type is number, the value range is [0, +∞). If the type is string, the value represents a length.| 287| radiusHeight | number \| string | No| Radius height of the rectangle border corners.<br> If the type is number, the value range is [0, +∞). If the type is string, the value represents a length.| 288 289## BaseShape 290 291This API inherits from [CommonShapeMethod](#commonshapemethod). 292 293**Widget capability**: This API can be used in ArkTS widgets since API version 12. 294 295**Atomic service API**: This API can be used in atomic services since API version 12. 296 297**System capability**: SystemCapability.ArkUI.ArkUI.Full 298 299### width 300 301width(width: Length): T 302 303Sets the width of a shape. 304 305**Widget capability**: This API can be used in ArkTS widgets since API version 12. 306 307**Atomic service API**: This API can be used in atomic services since API version 12. 308 309**System capability**: SystemCapability.ArkUI.ArkUI.Full 310 311**Parameters** 312 313| Name | Type | Mandatory| Description | 314| ----------- | -------------------------------------------------- | ---- | -------------------------------------------- | 315| width | [Length](arkui-ts/ts-types.md#length) | Yes| Width of the shape.| 316 317**Return value** 318 319| Type | Description | 320| ------ | ------------------------ | 321| T | Current object.| 322 323### height 324 325height(height: Length): T 326 327Sets the height of a shape. 328 329**Widget capability**: This API can be used in ArkTS widgets since API version 12. 330 331**Atomic service API**: This API can be used in atomic services since API version 12. 332 333**System capability**: SystemCapability.ArkUI.ArkUI.Full 334 335**Parameters** 336 337| Name | Type | Mandatory| Description | 338| ----------- | -------------------------------------------------- | ---- | -------------------------------------------- | 339| height | [Length](arkui-ts/ts-types.md#length) | Yes| Height of the shape.| 340 341**Return value** 342 343| Type | Description | 344| ------ | ------------------------ | 345| T | Current object.| 346 347### size 348 349size(size: SizeOptions): T 350 351Sets the size of a shape. 352 353**Widget capability**: This API can be used in ArkTS widgets since API version 12. 354 355**Atomic service API**: This API can be used in atomic services since API version 12. 356 357**System capability**: SystemCapability.ArkUI.ArkUI.Full 358 359**Parameters** 360 361| Name | Type | Mandatory| Description | 362| ----------- | -------------------------------------------------- | ---- | -------------------------------------------- | 363| size | [SizeOptions](arkui-ts/ts-types.md#sizeoptions) | Yes| Size of the shape.| 364 365**Return value** 366 367| Type | Description | 368| ------ | ------------------------ | 369| T | Current object.| 370 371## CommonShapeMethod 372 373Implements the common shape methods. 374 375**Widget capability**: This API can be used in ArkTS widgets since API version 12. 376 377**Atomic service API**: This API can be used in atomic services since API version 12. 378 379**System capability**: SystemCapability.ArkUI.ArkUI.Full 380 381### offset 382 383offset(offset: Position): T 384 385Sets the coordinate offset relative to the component's layout position. 386 387**Widget capability**: This API can be used in ArkTS widgets since API version 12. 388 389**Atomic service API**: This API can be used in atomic services since API version 12. 390 391**System capability**: SystemCapability.ArkUI.ArkUI.Full 392 393**Parameters** 394 395| Name | Type | Mandatory| Description | 396| ----------- | -------------------------------------------------- | ---- | -------------------------------------------- | 397| offset | [Position](arkui-ts/ts-types.md#position) | Yes| Coordinate offset relative to the component's layout position.| 398 399**Return value** 400 401| Type | Description | 402| ------ | ------------------------ | 403| T | Current object.| 404 405 406### fill 407 408fill(color: ResourceColor): T 409 410Sets the fill color of this shape, which determines its opacity, with black representing full transparency and white representing full opacity. 411 412**Widget capability**: This API can be used in ArkTS widgets since API version 12. 413 414**Atomic service API**: This API can be used in atomic services since API version 12. 415 416**System capability**: SystemCapability.ArkUI.ArkUI.Full 417 418**Parameters** 419 420| Name | Type | Mandatory| Description | 421| ----------- | -------------------------------------------------- | ---- | -------------------------------------------- | 422| color | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | Yes| Fill color of the shape, which represents the opacity of the fill area. The black color indicates full transparency, while white indicates full opacity.| 423 424**Return value** 425 426| Type | Description | 427| ------ | ------------------------ | 428| T | Current object.| 429 430 431### position 432 433position(position: Position): T 434 435Sets the position of a shape. 436 437**Widget capability**: This API can be used in ArkTS widgets since API version 12. 438 439**Atomic service API**: This API can be used in atomic services since API version 12. 440 441**System capability**: SystemCapability.ArkUI.ArkUI.Full 442 443**Parameters** 444 445| Name | Type | Mandatory| Description | 446| ----------- | -------------------------------------------------- | ---- | -------------------------------------------- | 447| position | [Position](arkui-ts/ts-types.md#position) | Yes| Position of the shape.| 448 449**Return value** 450 451| Type | Description | 452| ------ | ------------------------ | 453| T | Current object.| 454 455## **Example** 456 457```ts 458import { CircleShape, EllipseShape, PathShape, RectShape } from "@kit.ArkUI"; 459 460@Entry 461@Component 462struct ShapeExample { 463 build() { 464 Column({ space: 15 }) { 465 Text('CircleShape, position').fontSize(20).width('75%').fontColor('#DCDCDC') 466 Image($r('app.media.startIcon')) 467 .clipShape(new CircleShape({ width: '280px', height: '280px' }).position({ x: '20px', y: '20px' })) 468 .width('500px').height('280px') 469 470 Text('EllipseShape, offset').fontSize(20).width('75%').fontColor('#DCDCDC') 471 Image($r('app.media.startIcon')) 472 .clipShape(new EllipseShape({ width: '350px', height: '280px' }).offset({ x: '10px', y: '10px' })) 473 .width('500px').height('280px') 474 475 Text('PathShape, fill').fontSize(20).width('75%').fontColor('#DCDCDC') 476 Image($r('app.media.startIcon')) 477 .maskShape(new PathShape().commands('M100 0 L200 240 L0 240 Z').fill(Color.Red)) 478 .width('500px').height('280px') 479 480 Text('RectShape, width, height, fill').fontSize(20).width('75%').fontColor('#DCDCDC') 481 Image($r('app.media.startIcon')) 482 .maskShape(new RectShape().width('350px').height('280px').fill(Color.Red)) 483 .width('500px').height('280px') 484 } 485 .width('100%') 486 .margin({ top: 15 }) 487 } 488} 489``` 490