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
22**Widget capability**: This API can be used in ArkTS widgets since API version 12.
23
24**System capability**: SystemCapability.ArkUI.ArkUI.Full
25
26### constructor
27
28constructor(options?: ShapeSize)
29
30**Widget capability**: This API can be used in ArkTS widgets since API version 12.
31
32**Atomic service API**: This API can be used in atomic services since API version 12.
33
34**System capability**: SystemCapability.ArkUI.ArkUI.Full
35
36| Name        | Type                                              | Mandatory| Description                                        |
37| ----------- | -------------------------------------------------- | ---- | -------------------------------------------- |
38| options | [ShapeSize](#shapesize) | No| Size of the shape.|
39
40This API inherits from [BaseShape](#baseshape).
41
42## EllipseShape
43
44Represents an ellipse shape used in the **clipShape** and **maskShape** APIs.
45
46**Widget capability**: This API can be used in ArkTS widgets since API version 12.
47
48**System capability**: SystemCapability.ArkUI.ArkUI.Full
49
50### constructor
51
52constructor(options?: ShapeSize)
53
54**Widget capability**: This API can be used in ArkTS widgets since API version 12.
55
56**Atomic service API**: This API can be used in atomic services since API version 12.
57
58**System capability**: SystemCapability.ArkUI.ArkUI.Full
59
60| Name        | Type                                              | Mandatory| Description                                        |
61| ----------- | -------------------------------------------------- | ---- | -------------------------------------------- |
62| options | [ShapeSize](#shapesize) | No| Size of the shape.|
63
64This API inherits from [BaseShape](#baseshape).
65
66## PathShape
67
68Represents a path used in the **clipShape** and **maskShape** APIs.
69
70**Widget capability**: This API can be used in ArkTS widgets since API version 12.
71
72**System capability**: SystemCapability.ArkUI.ArkUI.Full
73
74### constructor
75
76constructor(options?: PathShapeOptions)
77
78**System capability**: SystemCapability.ArkUI.ArkUI.Full
79
80**Atomic service API**: This API can be used in atomic services since API version 12.
81
82**Widget capability**: This API can be used in ArkTS widgets since API version 12.
83
84| Name        | Type                                              | Mandatory| Description                                        |
85| ----------- | -------------------------------------------------- | ---- | -------------------------------------------- |
86| options | [PathShapeOptions](#pathshapeoptions) | No| Path parameters.|
87
88This API inherits from [CommonShapeMethod](#commonshapemethod).
89
90### commands
91
92commands(commands: string): PathShape
93
94Sets the path drawing commands.
95
96**Widget capability**: This API can be used in ArkTS widgets since API version 12.
97
98**Atomic service API**: This API can be used in atomic services since API version 12.
99
100**System capability**: SystemCapability.ArkUI.ArkUI.Full
101
102| Name        | Type                                              | Mandatory| Description                                        |
103| ----------- | -------------------------------------------------- | ---- | -------------------------------------------- |
104| commands | string | Yes| Path drawing commands.|
105
106## RectShape
107
108Represents a rectangle shape used in the **clipShape** and **maskShape** APIs.
109
110**Widget capability**: This API can be used in ArkTS widgets since API version 12.
111
112**System capability**: SystemCapability.ArkUI.ArkUI.Full
113
114### constructor
115
116constructor(options?: RectShapeOptions | RoundRectShapeOptions)
117
118**Widget capability**: This API can be used in ArkTS widgets since API version 12.
119
120**Atomic service API**: This API can be used in atomic services since API version 12.
121
122**System capability**: SystemCapability.ArkUI.ArkUI.Full
123
124| Name        | Type                                              | Mandatory| Description                                        |
125| ----------- | -------------------------------------------------- | ---- | -------------------------------------------- |
126| options | [RectShapeOptions](#rectshapeoptions)  \|  [RoundRectShapeOptions](#roundrectshapeoptions) | No| Rectangle parameters.|
127
128This API inherits from [BaseShape](#baseshape).
129
130### radiusWidth
131
132radiusWidth(rWidth: number | string): RectShape
133
134Sets the radius width of the rectangle border corners.
135
136**Widget capability**: This API can be used in ArkTS widgets since API version 12.
137
138**Atomic service API**: This API can be used in atomic services since API version 12.
139
140**System capability**: SystemCapability.ArkUI.ArkUI.Full
141
142| Name        | Type                                              | Mandatory| Description                                        |
143| ----------- | -------------------------------------------------- | ---- | -------------------------------------------- |
144| rWidth | number  \|  string | Yes| Radius width of the rectangle border corners.|
145
146### radiusHeight
147
148radiusHeight(rHeight: number | string): RectShape
149
150Sets the radius height of the rectangle border corners.
151
152**Widget capability**: This API can be used in ArkTS widgets since API version 12.
153
154**Atomic service API**: This API can be used in atomic services since API version 12.
155
156**System capability**: SystemCapability.ArkUI.ArkUI.Full
157
158| Name        | Type                                              | Mandatory| Description                                        |
159| ----------- | -------------------------------------------------- | ---- | -------------------------------------------- |
160| rHeight | number  \|  string | Yes| Radius height of the rectangle border corners.|
161
162### radius
163
164radius(radius: number | string | Array<number  \|  string>): RectShape
165
166Sets the radius of the rectangle border corners.
167
168**Widget capability**: This API can be used in ArkTS widgets since API version 12.
169
170**Atomic service API**: This API can be used in atomic services since API version 12.
171
172**System capability**: SystemCapability.ArkUI.ArkUI.Full
173
174| Name        | Type                                              | Mandatory| Description                                        |
175| ----------- | -------------------------------------------------- | ---- | -------------------------------------------- |
176| 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.|
177
178
179## ShapeSize
180
181Describes the size of a shape.
182
183**Widget capability**: This API can be used in ArkTS widgets since API version 12.
184
185**Atomic service API**: This API can be used in atomic services since API version 12.
186
187**System capability**: SystemCapability.ArkUI.ArkUI.Full
188
189| Name        | Type                                              | Mandatory                                            | Description                                        |
190| ----------- | -------------------------------------------------- | -------------------------------------------- | -------------------------------------------- |
191| width | number  \|  string | No| Width of the shape.|
192| height | number  \|  string | No| Height of the shape.|
193
194## PathShapeOptions
195
196Represents the parameter of the constructor used to create a **PathShape** object.
197
198**Widget capability**: This API can be used in ArkTS widgets since API version 12.
199
200**Atomic service API**: This API can be used in atomic services since API version 12.
201
202**System capability**: SystemCapability.ArkUI.ArkUI.Full
203
204| Name        | Type                                              | Mandatory                                            | Description                                        |
205| ----------- | -------------------------------------------------- | -------------------------------------------- | -------------------------------------------- |
206| commands | string | No| Path drawing commands. For details, see [commands](./arkui-ts/ts-drawing-components-path.md#commands-1).|
207
208## RectShapeOptions
209
210Represents the parameter of the constructor used to create a **RectShape** object.
211
212**Widget capability**: This API can be used in ArkTS widgets since API version 12.
213
214**Atomic service API**: This API can be used in atomic services since API version 12.
215
216**System capability**: SystemCapability.ArkUI.ArkUI.Full
217
218This API inherits from [ShapeSize](#shapesize).
219
220| Name        | Type                                              | Mandatory                                            | Description                                        |
221| ----------- | -------------------------------------------------- | -------------------------------------------- | -------------------------------------------- |
222| radius | number  \|  string  \|  Array<number  \|  string> | No| Radius of the rectangle border corners.|
223
224## RoundRectShapeOptions
225
226Represents the parameter of the constructor used to create a **RectShape** object with rounded corners.
227
228**Widget capability**: This API can be used in ArkTS widgets since API version 12.
229
230**Atomic service API**: This API can be used in atomic services since API version 12.
231
232**System capability**: SystemCapability.ArkUI.ArkUI.Full
233
234This API inherits from [ShapeSize](#shapesize).
235
236| Name        | Type                                              | Mandatory                                            | Description                                        |
237| ----------- | -------------------------------------------------- | -------------------------------------------- | -------------------------------------------- |
238| radiusWidth | number  \|  string | No| Radius width of the rectangle border corners.|
239| radiusHeight | number  \|  string | No| Radius height of the rectangle border corners.|
240
241## BaseShape
242
243**Widget capability**: This API can be used in ArkTS widgets since API version 12.
244
245**System capability**: SystemCapability.ArkUI.ArkUI.Full
246
247This API inherits from [CommonShapeMethod](#commonshapemethod).
248
249### width
250
251width(width: Length): T
252
253Sets the width of a shape.
254
255**Widget capability**: This API can be used in ArkTS widgets since API version 12.
256
257**Atomic service API**: This API can be used in atomic services since API version 12.
258
259**System capability**: SystemCapability.ArkUI.ArkUI.Full
260
261| Name        | Type                                              | Mandatory| Description                                        |
262| ----------- | -------------------------------------------------- | ---- | -------------------------------------------- |
263| width | [Length](arkui-ts/ts-types.md#length) | Yes| Width of the shape.|
264
265### height
266
267height(height: Length): T
268
269Sets the height of a shape.
270
271**Widget capability**: This API can be used in ArkTS widgets since API version 12.
272
273**Atomic service API**: This API can be used in atomic services since API version 12.
274
275**System capability**: SystemCapability.ArkUI.ArkUI.Full
276
277| Name        | Type                                              | Mandatory| Description                                        |
278| ----------- | -------------------------------------------------- | ---- | -------------------------------------------- |
279| height | [Length](arkui-ts/ts-types.md#length) | Yes| Height of the shape.|
280
281### size
282
283size(size: SizeOptions): T
284
285Sets the size of a shape.
286
287**Widget capability**: This API can be used in ArkTS widgets since API version 12.
288
289**Atomic service API**: This API can be used in atomic services since API version 12.
290
291**System capability**: SystemCapability.ArkUI.ArkUI.Full
292
293| Name        | Type                                              | Mandatory| Description                                        |
294| ----------- | -------------------------------------------------- | ---- | -------------------------------------------- |
295| size | [SizeOptions](arkui-ts/ts-types.md#sizeoptions) | Yes| Size of the shape.|
296
297## CommonShapeMethod
298
299**Widget capability**: This API can be used in ArkTS widgets since API version 12.
300
301**System capability**: SystemCapability.ArkUI.ArkUI.Full
302
303### offset
304
305offset(offset: Position): T
306
307Sets the coordinate offset relative to the component's layout position.
308
309**Widget capability**: This API can be used in ArkTS widgets since API version 12.
310
311**Atomic service API**: This API can be used in atomic services since API version 12.
312
313**System capability**: SystemCapability.ArkUI.ArkUI.Full
314
315| Name        | Type                                              | Mandatory| Description                                        |
316| ----------- | -------------------------------------------------- | ---- | -------------------------------------------- |
317| offset | [Position](arkui-ts/ts-types.md#position) | Yes| Coordinate offset relative to the component's layout position.|
318
319### fill
320
321fill(color: ResourceColor): T
322
323Sets the fill color of this shape, which determines its opacity, with black representing full transparency and white representing full opacity.
324
325**Widget capability**: This API can be used in ArkTS widgets since API version 12.
326
327**Atomic service API**: This API can be used in atomic services since API version 12.
328
329**System capability**: SystemCapability.ArkUI.ArkUI.Full
330
331| Name        | Type                                              | Mandatory| Description                                        |
332| ----------- | -------------------------------------------------- | ---- | -------------------------------------------- |
333| 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.|
334
335### position
336
337position(position: Position): T
338
339Sets the position of a shape.
340
341**Widget capability**: This API can be used in ArkTS widgets since API version 12.
342
343**Atomic service API**: This API can be used in atomic services since API version 12.
344
345**System capability**: SystemCapability.ArkUI.ArkUI.Full
346
347| Name        | Type                                              | Mandatory| Description                                        |
348| ----------- | -------------------------------------------------- | ---- | -------------------------------------------- |
349| position | [Position](arkui-ts/ts-types.md#position) | Yes| Position of the shape.|
350
351## **Example**
352
353```ts
354import { CircleShape, EllipseShape, PathShape, RectShape } from "@kit.ArkUI";
355
356@Entry
357@Component
358struct ShapeExample {
359  build() {
360    Column({ space: 15 }) {
361      Text('CircleShape, position').fontSize(20).width('75%').fontColor('#DCDCDC')
362      Image($r('app.media.startIcon'))
363        .clipShape(new CircleShape({ width: '280px', height: '280px' }).position({ x: '20px', y: '20px' }))
364        .width('500px').height('280px')
365
366      Text('EllipseShape, offset').fontSize(20).width('75%').fontColor('#DCDCDC')
367      Image($r('app.media.startIcon'))
368        .clipShape(new EllipseShape({ width: '350px', height: '280px' }).offset({ x: '10px', y: '10px' }))
369        .width('500px').height('280px')
370
371      Text('PathShape, fill').fontSize(20).width('75%').fontColor('#DCDCDC')
372      Image($r('app.media.startIcon'))
373        .maskShape(new PathShape().commands('M100 0 L200 240 L0 240 Z').fill(Color.Red))
374        .width('500px').height('280px')
375
376      Text('RectShape, width, height, fill').fontSize(20).width('75%').fontColor('#DCDCDC')
377      Image($r('app.media.startIcon'))
378        .maskShape(new RectShape().width('350px').height('280px').fill(Color.Red))
379        .width('500px').height('280px')
380    }
381    .width('100%')
382    .margin({ top: 15 })
383  }
384}
385```
386