• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Rect
2
3The **Rect** component is used to draw a rectangle.
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
15## APIs
16
17Rect(options?: RectOptions | RoundedRectOptions)
18
19**Widget capability**: This API can be used in ArkTS widgets since API version 9.
20
21**Atomic service API**: This API can be used in atomic services since API version 11.
22
23**System capability**: SystemCapability.ArkUI.ArkUI.Full
24
25**Parameters**
26
27| Name| Type| Mandatory| Description|
28| -------- | -------- | -------- | -------- |
29| options | [RectOptions](ts-drawing-components-rect.md#rectoptions18) \| [RoundedRectOptions](ts-drawing-components-rect.md#roundedrectoptions18)  | No| Options for drawing a rectangle.|
30
31## RectOptions<sup>18+</sup>
32Describes the options for drawing a rectangle.
33
34**Widget capability**: This API can be used in ArkTS widgets since API version 18.
35
36**Atomic service API**: This API can be used in atomic services since API version 18.
37
38**System capability**: SystemCapability.ArkUI.ArkUI.Full
39
40| Name| Type| Mandatory| Description|
41| -------- | -------- | -------- | -------- |
42| width | string \| number | No| Width. The value must be greater than or equal to 0.<br>Default value: **0**<br>Default unit: vp<br>An invalid value is handled as the default value.|
43| height | string \| number | No| Height. The value must be greater than or equal to 0.<br>Default value: **0**<br>Default unit: vp<br>An invalid value is handled as the default value.|
44| radius | string \| number \| Array&lt;string \| number&gt; | No| Radius of the rounded corner. You can set separate radii for the four rounded corners. The value must be greater than or equal to 0. <br>This property takes precedence over **radiusWidth** and **radiusHeight** when used together.<br>Default value: **0**<br>Default unit: vp<br>An invalid value is handled as the default value.|
45
46## RoundedRectOptions<sup>18+</sup>
47Describes the options for drawing a rounded rectangle.
48
49**Widget capability**: This API can be used in ArkTS widgets since API version 18.
50
51**Atomic service API**: This API can be used in atomic services since API version 18.
52
53**System capability**: SystemCapability.ArkUI.ArkUI.Full
54
55| Name| Type| Mandatory| Description|
56| -------- | -------- | -------- | -------- |
57| width | string \| number | No| Width. The value must be greater than or equal to 0.<br>Default value: **0**<br>Default unit: vp<br>An invalid value is handled as the default value.|
58| height | string \| number | No| Height. The value must be greater than or equal to 0.<br>Default value: **0**<br>Default unit: vp<br>An invalid value is handled as the default value.|
59| radiusWidth | string \| number | No| Width of the rounded corner. The value must be greater than or equal to 0.<br>Default value: **0**<br>Default unit: vp<br>An invalid value is handled as the default value.|Width of the rounded corner.<br>Default value: **0**<br>An invalid value is handled as the default value.
60| radiusHeight | string \| number | No| Height of the rounded corner. The value must be greater than or equal to 0.<br>Default value: **0**<br>Default unit: vp<br>An invalid value is handled as the default value.|Height of the rounded corner.<br>Default value: **0**<br>An invalid value is handled as the default value.
61
62## Attributes
63
64In addition to the [universal attributes](ts-component-general-attributes.md), the following attributes are supported.
65
66### radiusWidth
67
68radiusWidth(value: number | string)
69
70Sets the width of the rounded corner. If not set, the height of the rounded corner is the same as its width. An invalid value is handled as the default value.
71
72**Widget capability**: This API can be used in ArkTS widgets since API version 7.
73
74**Atomic service API**: This API can be used in atomic services since API version 11.
75
76**System capability**: SystemCapability.ArkUI.ArkUI.Full
77
78**Parameters**
79
80| Name| Type                      | Mandatory| Description                      |
81| ------ | -------------------------- | ---- | -------------------------- |
82| value  | number \| string | Yes  | Width of the rounded corner. The value must be greater than or equal to 0.<br>Default value: **0**<br>Default unit: vp|
83
84### radiusHeight
85
86radiusHeight(value: number | string)
87
88Height of the rounded corner. If not set, the width of the rounded corner is the same as its height.  An invalid value is handled as the default value.
89
90**Widget capability**: This API can be used in ArkTS widgets since API version 7.
91
92**Atomic service API**: This API can be used in atomic services since API version 11.
93
94**System capability**: SystemCapability.ArkUI.ArkUI.Full
95
96**Parameters**
97
98| Name| Type                      | Mandatory| Description                      |
99| ------ | -------------------------- | ---- | -------------------------- |
100| value  | number \| string | Yes  | Height of the rounded corner. The value must be greater than or equal to 0.<br>Default value: **0**<br>Default unit: vp|
101
102### radius
103
104radius(value: number | string | Array&lt;string | number&gt;)
105
106Sets the radius of the rounded corner. The value must be greater than or equal to 0.  An invalid value is handled as the default value.
107
108**Widget capability**: This API can be used in ArkTS widgets since API version 9.
109
110**Atomic service API**: This API can be used in atomic services since API version 11.
111
112**System capability**: SystemCapability.ArkUI.ArkUI.Full
113
114**Parameters**
115
116| Name| Type                                                        | Mandatory| Description                        |
117| ------ | ------------------------------------------------------------ | ---- | ---------------------------- |
118| value  | number \| string \| Array&lt;string \| number&gt; | Yes  | Radius of the rounded corner. You can set separate radiuses for the four rounded corners.<br>Default value: **0**<br>Default unit: vp|
119
120### fill
121
122fill(value: ResourceColor)
123
124Sets 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.
125
126**Widget capability**: This API can be used in ArkTS widgets since API version 9.
127
128**Atomic service API**: This API can be used in atomic services since API version 11.
129
130**System capability**: SystemCapability.ArkUI.ArkUI.Full
131
132**Parameters**
133
134| Name| Type                                      | Mandatory| Description                                  |
135| ------ | ------------------------------------------ | ---- | -------------------------------------- |
136| value  | [ResourceColor](ts-types.md#resourcecolor) | Yes  | Color of the fill area.<br>Default value: **Color.Black**|
137
138### fillOpacity
139
140fillOpacity(value: number | string | Resource)
141
142Opacity of the fill area. The value range is [0.0, 1.0]. A value less than 0.0 evaluates to the value **0.0**. A value greater than 1.0 evaluates to the value **1.0**. Any other value evaluates to the value **1.0**.
143
144**Widget capability**: This API can be used in ArkTS widgets since API version 9.
145
146**Atomic service API**: This API can be used in atomic services since API version 11.
147
148**System capability**: SystemCapability.ArkUI.ArkUI.Full
149
150**Parameters**
151
152| Name| Type                                                        | Mandatory| Description                          |
153| ------ | ------------------------------------------------------------ | ---- | ------------------------------ |
154| value  | number \| string \| [Resource](ts-types.md#resource) | Yes  | Opacity of the fill area.<br>Default value: **1**|
155
156### stroke
157
158stroke(value: ResourceColor)
159
160Stroke color. If this attribute is not set, the component does not have any stroke. If the value is invalid, no stroke will be drawn.
161
162**Widget capability**: This API can be used in ArkTS widgets since API version 9.
163
164**Atomic service API**: This API can be used in atomic services since API version 11.
165
166**System capability**: SystemCapability.ArkUI.ArkUI.Full
167
168**Parameters**
169
170| Name| Type                                      | Mandatory| Description      |
171| ------ | ------------------------------------------ | ---- | ---------- |
172| value  | [ResourceColor](ts-types.md#resourcecolor) | Yes  | Stroke color.|
173
174### strokeDashArray
175
176strokeDashArray(value: Array&lt;any&gt;)
177
178Sets the stroke dashes. The value must be greater than or equal to 0. Invalid values are treated as the default value.
179
180**Widget capability**: This API can be used in ArkTS widgets since API version 9.
181
182**Atomic service API**: This API can be used in atomic services since API version 11.
183
184**System capability**: SystemCapability.ArkUI.ArkUI.Full
185
186**Parameters**
187
188| Name| Type            | Mandatory| Description                     |
189| ------ | ---------------- | ---- | ------------------------- |
190| value  | Array&lt;any&gt; | Yes  | Stroke dashes.<br>Default value: **[]**<br>Default unit: vp|
191
192### strokeDashOffset
193
194strokeDashOffset(value: number | string)
195
196Sets the offset of the start point for drawing the stroke. An invalid value is handled as the default value.
197
198**Widget capability**: This API can be used in ArkTS widgets since API version 9.
199
200**Atomic service API**: This API can be used in atomic services since API version 11.
201
202**System capability**: SystemCapability.ArkUI.ArkUI.Full
203
204**Parameters**
205
206| Name| Type                      | Mandatory| Description                                |
207| ------ | -------------------------- | ---- | ------------------------------------ |
208| value  | number \| string | Yes  | Offset of the start point for drawing the stroke.<br>Default value: **0**<br>Default unit: vp|
209
210### strokeLineCap
211
212strokeLineCap(value: LineCapStyle)
213
214Sets the cap style of the stroke.
215
216**Widget capability**: This API can be used in ArkTS widgets since API version 9.
217
218**Atomic service API**: This API can be used in atomic services since API version 11.
219
220**System capability**: SystemCapability.ArkUI.ArkUI.Full
221
222**Parameters**
223
224| Name| Type                                             | Mandatory| Description                                            |
225| ------ | ------------------------------------------------- | ---- | ------------------------------------------------ |
226| value  | [LineCapStyle](ts-appendix-enums.md#linecapstyle) | Yes  | Cap style of the stroke.<br>Default value: **LineCapStyle.Butt**|
227
228### strokeLineJoin
229
230strokeLineJoin(value: LineJoinStyle)
231
232Sets the join style of the stroke.
233
234**Widget capability**: This API can be used in ArkTS widgets since API version 9.
235
236**Atomic service API**: This API can be used in atomic services since API version 11.
237
238**System capability**: SystemCapability.ArkUI.ArkUI.Full
239
240**Parameters**
241
242| Name| Type                                               | Mandatory| Description                                              |
243| ------ | --------------------------------------------------- | ---- | -------------------------------------------------- |
244| value  | [LineJoinStyle](ts-appendix-enums.md#linejoinstyle) | Yes  | Join style of the stroke.<br>Default value: **LineJoinStyle.Miter**|
245
246### strokeMiterLimit
247
248strokeMiterLimit(value: number | string)
249
250Sets 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**.
251
252The 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.
253
254**Widget capability**: This API can be used in ArkTS widgets since API version 9.
255
256**Atomic service API**: This API can be used in atomic services since API version 11.
257
258**System capability**: SystemCapability.ArkUI.ArkUI.Full
259
260**Parameters**
261
262| Name| Type                      | Mandatory| Description                                          |
263| ------ | -------------------------- | ---- | ---------------------------------------------- |
264| 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**|
265
266### strokeOpacity
267
268strokeOpacity(value: number | string | Resource)
269
270Sets the stroke opacity. The value range is [0.0, 1.0]. A value less than 0.0 is treated as **0.0**. A value greater than 1.0 is treated as **1.0**. Any other value is treated as **1.0**.
271
272**Widget capability**: This API can be used in ArkTS widgets since API version 9.
273
274**Atomic service API**: This API can be used in atomic services since API version 11.
275
276**System capability**: SystemCapability.ArkUI.ArkUI.Full
277
278**Parameters**
279
280| Name| Type                                                        | Mandatory| Description                      |
281| ------ | ------------------------------------------------------------ | ---- | -------------------------- |
282| value  | number \| string \| [Resource](ts-types.md#resource) | Yes  | Stroke opacity.<br>Default value: **1**|
283
284### strokeWidth
285
286strokeWidth(value: Length)
287
288Sets the stroke width. If of the string type, this parameter cannot be set in percentage. A percentage is processed as 1 px.
289
290**Widget capability**: This API can be used in ArkTS widgets since API version 9.
291
292**Atomic service API**: This API can be used in atomic services since API version 11.
293
294**System capability**: SystemCapability.ArkUI.ArkUI.Full
295
296**Parameters**
297
298| Name| Type                        | Mandatory| Description                    |
299| ------ | ---------------------------- | ---- | ------------------------ |
300| 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.|
301
302### antiAlias
303
304antiAlias(value: boolean)
305
306Specifies whether anti-aliasing is enabled.
307
308**Widget capability**: This API can be used in ArkTS widgets since API version 9.
309
310**Atomic service API**: This API can be used in atomic services since API version 11.
311
312**System capability**: SystemCapability.ArkUI.ArkUI.Full
313
314**Parameters**
315
316| Name| Type   | Mandatory| Description                                 |
317| ------ | ------- | ---- | ------------------------------------- |
318| value  | boolean | Yes  | Whether anti-aliasing is enabled.<br>**true**: Anti-aliasing is enabled.<br>**false**: Anti-aliasing is disabled.<br>Default value: **true**|
319
320## Example
321### Example 1: Drawing Rectangles
322
323This example demonstrates how to use **fill**, **fillOpacity**, **stroke**, and **radius** to draw rectangles with specific fill colors, opacity, stroke colors, and rounded corners.
324
325```ts
326// xxx.ets
327@Entry
328@Component
329struct RectExample {
330  build() {
331    Column({ space: 10 }) {
332      Text('normal').fontSize(11).fontColor(0xCCCCCC).width('90%')
333      // Draw a 90% x 50 rectangle.
334      Column({ space: 5 }) {
335        Text('normal').fontSize(9).fontColor(0xCCCCCC).width('90%')
336        // Draw a 90% x 50 rectangle.
337        Rect({ width: '90%', height: 50 })
338          .fill(Color.Pink)
339        // Draw a 90% x 50 rectangle.
340        Rect()
341          .width('90%')
342          .height(50)
343          .fillOpacity(0)
344          .stroke(Color.Red)
345          .strokeWidth(3)
346
347        Text('with rounded corners').fontSize(11).fontColor(0xCCCCCC).width('90%')
348        // Draw a 90% x 80 rectangle, with the width and height of its rounded corners being 40 and 20, respectively.
349        Rect({ width: '90%', height: 80 })
350          .radiusHeight(20)
351          .radiusWidth(40)
352          .fill(Color.Pink)
353        // Draw a 90% x 80 rectangle, with the width and height of its rounded corners being both 20.
354        Rect({ width: '90%', height: 80 })
355          .radius(20)
356          .fill(Color.Pink)
357          .stroke(Color.Transparent)
358      }.width('100%').margin({ top: 10 })
359
360      // Draw a 90% x 50 rectangle, with the width and height of its rounded corners as follows: 40 for the upper left rounded corner, 20 for the upper right rounded corner, 40 for the lower right rounded corner, and 20 for the lower left rounded corner.
361      Rect({ width: '90%', height: 80 })
362        .radius([[40, 40], [20, 20], [40, 40], [20, 20]])
363        .fill(Color.Pink)
364    }.width('100%').margin({ top: 5 })
365  }
366}
367```
368
369![en-us_image_0000001174264386](figures/en-us_image_0000001174264386.png)
370
371### Example 2: Drawing a Gradient Rectangle
372
373This example demonstrates how to use the universal attributes **linearGradient** and **clipShape** to draw a gradient rectangle.
374
375```ts
376// xxx.ets
377@Entry
378@Component
379struct RectExample {
380  build() {
381    Column({ space: 10 }) {
382      Column()
383        .width(100)
384        .height(100)
385        .linearGradient({
386          direction: GradientDirection.Right,
387          colors: [[0xff0000, 0.0], [0x0000ff, 0.3], [0xffff00, 1.0]]
388        })
389        .clipShape(new Rect({ width: 100, height: 100, radius: 40 }))
390      Rect()
391        .width(100)
392        .height(100)
393        // Set the color of the fill area. To display the color gradient of the background, set .fillOpacity(0.0).
394        .fill(Color.Pink)
395        // Set the radius of the rounded corner to 40.
396        .radius(40)
397        .stroke(Color.Black)
398        // Set the color gradient. It takes effect only for a 100 x 100 rectangular area. The boundary of the gradient does not contain rounded corners.
399        .linearGradient({
400          direction: GradientDirection.Right,
401          colors: [[0xff0000, 0.0], [0x0000ff, 0.3], [0xffff00, 1.0]]
402        })
403    }
404  }
405}
406```
407
408![en-us_image_0000001174264386](figures/en-us_image_0000001174264387.jpeg)
409