• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Shape
2
3The **Shape** component is the parent component of the drawing components. The attributes described in this topic are universal attributes supported by all the drawing components.
4
51. Drawing components use **Shape** as their parent to implement the effect similar to SVG.
6
72. The **Shape** component is used independently to draw a specific shape.
8
9>  **NOTE**
10>
11>  This component is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.
12
13
14## Child Components
15
16The following child components are supported: Rect](ts-drawing-components-rect.md), [Path](ts-drawing-components-path.md), [Circle](ts-drawing-components-circle.md), [Ellipse](ts-drawing-components-ellipse.md), [Polyline](ts-drawing-components-polyline.md), [Polygon](ts-drawing-components-polygon.md), [Image](ts-basic-components-image.md), [Text](ts-basic-components-text.md), [Column](ts-container-column.md), [Row](ts-container-row.md), Shape
17
18
19## APIs
20
21Shape(value?: PixelMap)
22
23Since API version 9, this API is supported in ArkTS widgets, except that **PixelMap** objects are not supported.
24
25**Atomic service API**: This API can be used in atomic services since API version 11.
26
27**System capability**: SystemCapability.ArkUI.ArkUI.Full
28
29**Parameters**
30
31| Name| Type| Mandatory| Description|
32| -------- | -------- | -------- | -------- |
33| value | [PixelMap](../../apis-image-kit/js-apis-image.md#pixelmap7) | No| Shape to draw. You can draw a shape in the specified **PixelMap** object. If no object is specified, the shape is drawn in the current drawing target.|
34
35
36## Attributes
37
38In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported.
39
40### viewPort
41
42viewPort(value: ViewportRect)
43
44Sets the viewport of the shape.
45
46**Widget capability**: Since API version 9, this API is supported in ArkTS widgets.
47
48**Atomic service API**: This API can be used in atomic services since API version 11.
49
50**System capability**: SystemCapability.ArkUI.ArkUI.Full
51
52**Parameters**
53
54| Name| Type| Mandatory| Description|
55| -------- | -------- | -------- | -------- |
56| value | [ViewportRect](ts-drawing-components-shape.md#viewportrect14) | Yes| Options of the viewport.|
57
58## ViewportRect<sup>14+</sup>
59Describes the options of the viewport.
60
61**Widget capability**: This API can be used in ArkTS widgets since API version 14.
62
63**Atomic service API**: This API can be used in atomic services since API version 14.
64
65**System capability**: SystemCapability.ArkUI.ArkUI.Full
66
67| Name| Type| Mandatory| Description|
68| -------- | -------- | -------- | -------- |
69| x | string \| number | No| Horizontal coordinate of the start point of the viewport.<br>Default value: **0**<br>Default unit: vp<br>An invalid value is handled as the default value.|
70| y | string \| number | No| Vertical coordinate of the start point of the viewport.<br>Default value: **0**<br>Default unit: vp<br>An invalid value is handled as the default value.|
71| width | string \| number | No| Width of the viewport.<br>Default value: **0**<br>Default unit: vp<br>An invalid value is handled as the default value.|
72| height | string \| number | No| Height of the viewport.<br>Default value: **0**<br>Default unit: vp<br>An invalid value is handled as the default value.|
73
74### fill
75
76fill(value: ResourceColor)
77
78Sets 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.
79
80**Widget capability**: Since API version 9, this API is supported in ArkTS widgets.
81
82**Atomic service API**: This API can be used in atomic services since API version 11.
83
84**System capability**: SystemCapability.ArkUI.ArkUI.Full
85
86**Parameters**
87
88| Name| Type                                      | Mandatory| Description                                  |
89| ------ | ------------------------------------------ | ---- | -------------------------------------- |
90| value  | [ResourceColor](ts-types.md#resourcecolor) | Yes  | Color of the fill area.<br>Default value: **Color.Black**|
91
92### fillOpacity
93
94fillOpacity(value: number | string | Resource)
95
96Sets the opacity 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**.
97
98**Widget capability**: Since API version 9, this API is supported in ArkTS widgets.
99
100**Atomic service API**: This API can be used in atomic services since API version 11.
101
102**System capability**: SystemCapability.ArkUI.ArkUI.Full
103
104**Parameters**
105
106| Name| Type                                                        | Mandatory| Description                          |
107| ------ | ------------------------------------------------------------ | ---- | ------------------------------ |
108| value  | number \| string \| [Resource](ts-types.md#resource) | Yes  | Opacity of the fill area.<br>Default value: **1**|
109
110### stroke
111
112stroke(value: ResourceColor)
113
114Sets 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.
115
116**Widget capability**: Since API version 9, this API is supported in ArkTS widgets.
117
118**Atomic service API**: This API can be used in atomic services since API version 11.
119
120**System capability**: SystemCapability.ArkUI.ArkUI.Full
121
122**Parameters**
123
124| Name| Type                                      | Mandatory| Description      |
125| ------ | ------------------------------------------ | ---- | ---------- |
126| value  | [ResourceColor](ts-types.md#resourcecolor) | Yes  | Stroke color.|
127
128### strokeDashArray
129
130strokeDashArray(value: Array&lt;any&gt;)
131
132Sets the stroke dashes. An invalid value is handled as the default value.
133
134**Widget capability**: Since API version 9, this API is supported in ArkTS widgets.
135
136**Atomic service API**: This API can be used in atomic services since API version 11.
137
138**System capability**: SystemCapability.ArkUI.ArkUI.Full
139
140**Parameters**
141
142| Name| Type            | Mandatory| Description                     |
143| ------ | ---------------- | ---- | ------------------------- |
144| value  | Array&lt;any&gt; | Yes  | Stroke dashes.<br>Default value: **[]**<br>Default unit: vp|
145
146### strokeDashOffset
147
148strokeDashOffset(value: number | string)
149
150Sets the offset of the start point for drawing the stroke. An invalid value is handled as the default value.
151
152**Widget capability**: Since API version 9, this API is supported in ArkTS widgets.
153
154**Atomic service API**: This API can be used in atomic services since API version 11.
155
156**System capability**: SystemCapability.ArkUI.ArkUI.Full
157
158**Parameters**
159
160| Name| Type                      | Mandatory| Description                                |
161| ------ | -------------------------- | ---- | ------------------------------------ |
162| value  | number \| string | Yes  | Offset of the start point for drawing the stroke.<br>Default value: **0**<br>Default unit: vp|
163
164### strokeLineCap
165
166strokeLineCap(value: LineCapStyle)
167
168Sets the cap style of the stroke.
169
170**Widget capability**: Since API version 9, this API is supported in ArkTS widgets.
171
172**Atomic service API**: This API can be used in atomic services since API version 11.
173
174**System capability**: SystemCapability.ArkUI.ArkUI.Full
175
176**Parameters**
177
178| Name| Type                                             | Mandatory| Description                                            |
179| ------ | ------------------------------------------------- | ---- | ------------------------------------------------ |
180| value  | [LineCapStyle](ts-appendix-enums.md#linecapstyle) | Yes  | Cap style of the stroke.<br>Default value: **LineCapStyle.Butt**|
181
182### strokeLineJoin
183
184strokeLineJoin(value: LineJoinStyle)
185
186Sets the join style of the stroke.
187
188**Widget capability**: Since API version 9, this API is supported in ArkTS widgets.
189
190**Atomic service API**: This API can be used in atomic services since API version 11.
191
192**System capability**: SystemCapability.ArkUI.ArkUI.Full
193
194**Parameters**
195
196| Name| Type                                               | Mandatory| Description                                              |
197| ------ | --------------------------------------------------- | ---- | -------------------------------------------------- |
198| value  | [LineJoinStyle](ts-appendix-enums.md#linejoinstyle) | Yes  | Join style of the stroke.<br>Default value: **LineJoinStyle.Miter**|
199
200### strokeMiterLimit
201
202strokeMiterLimit(value: number | string)
203
204Sets 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**.
205
206The 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.
207
208**Widget capability**: Since API version 9, this API is supported in ArkTS widgets.
209
210**Atomic service API**: This API can be used in atomic services since API version 11.
211
212**System capability**: SystemCapability.ArkUI.ArkUI.Full
213
214**Parameters**
215
216| Name| Type                      | Mandatory| Description                                          |
217| ------ | -------------------------- | ---- | ---------------------------------------------- |
218| 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**|
219
220### strokeOpacity
221
222strokeOpacity(value: number | string | Resource)
223
224Sets 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**.
225
226**Widget capability**: Since API version 9, this API is supported in ArkTS widgets.
227
228**Atomic service API**: This API can be used in atomic services since API version 11.
229
230**System capability**: SystemCapability.ArkUI.ArkUI.Full
231
232**Parameters**
233
234| Name| Type                                                        | Mandatory| Description                      |
235| ------ | ------------------------------------------------------------ | ---- | -------------------------- |
236| value  | number \| string \| [Resource](ts-types.md#resource) | Yes  | Stroke opacity.<br>Default value: **1**|
237
238### strokeWidth
239
240strokeWidth(value: number | string)
241
242Sets the stroke width. If of the string type, this attribute cannot be set in percentage. A percentage is processed as 1 px.
243
244**Widget capability**: Since API version 9, this API is supported in ArkTS widgets.
245
246**Atomic service API**: This API can be used in atomic services since API version 11.
247
248**System capability**: SystemCapability.ArkUI.ArkUI.Full
249
250**Parameters**
251
252| Name| Type                        | Mandatory| Description                    |
253| ------ | ---------------------------- | ---- | ------------------------ |
254| value  | number \| string | Yes  | Stroke width.<br>Default value: **1**<br>Default unit: vp|
255
256### antiAlias
257
258antiAlias(value: boolean)
259
260Specifies whether anti-aliasing is enabled.
261
262**Widget capability**: Since API version 9, this API is supported in ArkTS widgets.
263
264**Atomic service API**: This API can be used in atomic services since API version 11.
265
266**System capability**: SystemCapability.ArkUI.ArkUI.Full
267
268**Parameters**
269
270| Name| Type   | Mandatory| Description                                 |
271| ------ | ------- | ---- | ------------------------------------- |
272| value  | boolean | Yes  | Whether anti-aliasing is enabled.<br>Default value: **true**|
273
274### mesh<sup>8+</sup>
275
276mesh(value: Array&lt;number&gt;, column: number, row: number)
277
278Sets the mesh effect.
279
280**Widget capability**: Since API version 9, this API is supported in ArkTS widgets.
281
282**Atomic service API**: This API can be used in atomic services since API version 11.
283
284**System capability**: SystemCapability.ArkUI.ArkUI.Full
285
286**Parameters**
287
288| Name| Type               | Mandatory| Description                                                        |
289| ------ | ------------------- | ---- | ------------------------------------------------------------ |
290| value  | Array&lt;number&gt; | Yes  | An array of lengths (column + 1) * (row + 1) * 2, which records the position of each vertex of the distorted bitmap.|
291| column | number              | Yes  | Number of columns in the mesh matrix.                                              |
292| row    | number              | Yes  | Number of rows in the mesh matrix.                                              |
293
294## Example
295
296This example demonstrates how to use the **Shape** component to draw rectangles, ellipses, and lines.
297
298```ts
299// xxx.ets
300@Entry
301@Component
302struct ShapeExample {
303  build() {
304    Column({ space: 10 }) {
305      Text('basic').fontSize(11).fontColor(0xCCCCCC).width(320)
306      // Draw a 300 x 50 rectangle with strokes at (-2, -2). The fill color is 0x317AF7, the stroke color is black, the stroke width is 4, the stroke dash is 20, the offset is 10 to the left, the cap style is rounded, the join style is rounded, and anti-aliasing is enabled (default).
307      // Draw a 300 x 50 ellipse with strokes at (-2, 58). The fill color is 0x317AF7, the stroke color is black, the stroke width is 4, the stroke dash is 20, the offset is 10 to the left, the cap style is rounded, the join style is rounded, and anti-aliasing is enabled (default).
308      // Draw a 300 x 10 straight line at (-2, 118). The fill color is 0x317AF7, the stroke color is black, the stroke width is 4, the stroke dash is 20, the offset is 10 to the left, the cap style is rounded, the join style is rounded, and anti-aliasing is enabled (default).
309      Shape() {
310        Rect().width(300).height(50)
311        Ellipse().width(300).height(50).offset({ x: 0, y: 60 })
312        Path().width(300).height(10).commands('M0 0 L900 0').offset({ x: 0, y: 120 })
313      }
314      .width(350)
315      .height(140)
316      .viewPort({ x: -2, y: -2, width: 304, height: 130 })
317      .fill(0x317AF7)
318      .stroke(Color.Black)
319      .strokeWidth(4)
320      .strokeDashArray([20])
321      .strokeDashOffset(10)
322      .strokeLineCap(LineCapStyle.Round)
323      .strokeLineJoin(LineJoinStyle.Round)
324      .antiAlias(true)
325      // Draw a 300 x 50 rectangle with strokes at (0, 0) and (-5, -5). The drawing start point is the midpoint of the stroke width by default. To fully display the strokes, you must set the coordinates of the start position of the viewport to negative values so that the viewport is offset by half the stroke width.
326      Shape() {
327        Rect().width(300).height(50)
328      }
329      .width(350)
330      .height(80)
331      .viewPort({ x: 0, y: 0, width: 320, height: 70 })
332      .fill(0x317AF7)
333      .stroke(Color.Black)
334      .strokeWidth(10)
335
336      Shape() {
337        Rect().width(300).height(50)
338      }
339      .width(350)
340      .height(80)
341      .viewPort({ x: -5, y: -5, width: 320, height: 70 })
342      .fill(0x317AF7)
343      .stroke(Color.Black)
344      .strokeWidth(10)
345
346      Text('path').fontSize(11).fontColor(0xCCCCCC).width(320)
347      // Draw a straight line at (0, -5). The fill color is 0xEE8443, the stroke width is 10, and the stroke dash is 20.
348      Shape() {
349        Path().width(300).height(10).commands('M0 0 L900 0')
350      }
351      .width(350)
352      .height(20)
353      .viewPort({ x: 0, y: -5, width: 300, height: 20 })
354      .stroke(0xEE8443)
355      .strokeWidth(10)
356      .strokeDashArray([20])
357      // Draw a straight line at (0, -5). The fill color is 0xEE8443, the stroke width is 10, the stroke dash is 20, and the offset is 10 to the left.
358      Shape() {
359        Path().width(300).height(10).commands('M0 0 L900 0')
360      }
361      .width(350)
362      .height(20)
363      .viewPort({ x: 0, y: -5, width: 300, height: 20 })
364      .stroke(0xEE8443)
365      .strokeWidth(10)
366      .strokeDashArray([20])
367      .strokeDashOffset(10)
368      // Draw a straight line at (0, -5). The fill color is 0xEE8443, the stroke width is 10, and the stroke opacity is 0.5.
369      Shape() {
370        Path().width(300).height(10).commands('M0 0 L900 0')
371      }
372      .width(350)
373      .height(20)
374      .viewPort({ x: 0, y: -5, width: 300, height: 20 })
375      .stroke(0xEE8443)
376      .strokeWidth(10)
377      .strokeOpacity(0.5)
378      // Draw a straight line at (0, -5). The fill color is 0xEE8443, the stroke width is 10, the stroke dash is 20, and the cap style is rounded.
379      Shape() {
380        Path().width(300).height(10).commands('M0 0 L900 0')
381      }
382      .width(350)
383      .height(20)
384      .viewPort({ x: 0, y: -5, width: 300, height: 20 })
385      .stroke(0xEE8443)
386      .strokeWidth(10)
387      .strokeDashArray([20])
388      .strokeLineCap(LineCapStyle.Round)
389      // Draw a closed path at (-20, -5). The fill color is 0x317AF7, the stroke width is 10, the stroke color is 0xEE8443, and the join style is miter (default value).
390      Shape() {
391        Path().width(200).height(60).commands('M0 0 L400 0 L400 150 Z')
392      }
393      .width(300)
394      .height(200)
395      .viewPort({ x: -20, y: -5, width: 310, height: 90 })
396      .fill(0x317AF7)
397      .stroke(0xEE8443)
398      .strokeWidth(10)
399      .strokeLineJoin(LineJoinStyle.Miter)
400      .strokeMiterLimit(5)
401    }.width('100%').margin({ top: 15 })
402  }
403}
404```
405
406![en-us_image_0000001184628104](figures/en-us_image_0000001184628104.png)
407
408