• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Line
2
3The **Line** component is used to draw a straight line.
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## Child Components
10
11Not supported
12
13
14## APIs
15
16Line(options?: LineOptions)
17
18**Widget capability**: This API can be used in ArkTS widgets since API version 9.
19
20**Atomic service API**: This API can be used in atomic services since API version 11.
21
22**System capability**: SystemCapability.ArkUI.ArkUI.Full
23
24**Parameters**
25
26| Name| Type| Mandatory| Description
27| -------- | -------- | -------- | -------- |
28| options | [LineOptions](ts-drawing-components-line.md#lineoptions14) | No| Options for drawing a line.|
29
30## LineOptions<sup>14+</sup>
31Describes the options for drawing a line.
32
33**Widget capability**: This API can be used in ArkTS widgets since API version 14.
34
35**Atomic service API**: This API can be used in atomic services since API version 14.
36
37**System capability**: SystemCapability.ArkUI.ArkUI.Full
38
39| Name| Type| Mandatory| Description|
40| -------- | -------- | -------- | -------- |
41| width | string \| number | No| Width.<br>If the value is invalid or the default value is used, the width required for the content is used.<br>Default unit: vp|
42| height | string \| number | No| Height.<br>If the value is invalid or the default value is used, the width required for the content is used.<br>Default unit: vp|
43
44## Attributes
45
46In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported.
47
48### startPoint
49
50startPoint(value: Array&lt;any&gt;)
51
52Sets the coordinates (relative coordinates) of the start point of the line. An invalid value is handled as the default value.
53
54**Widget capability**: This API can be used in ArkTS widgets since API version 9.
55
56**Atomic service API**: This API can be used in atomic services since API version 11.
57
58**System capability**: SystemCapability.ArkUI.ArkUI.Full
59
60**Parameters**
61
62| Name| Type                                     | Mandatory| Description                                                        |
63| ------ | ----------------------------------------- | ---- | ------------------------------------------------------------ |
64| value  | Array&lt;[Length](ts-types.md#length)&gt; | Yes  | Coordinates (relative coordinates) of the start point of the line, in vp.<br>Default value: **[0, 0]**|
65
66### endPoint
67
68endPoint(value: Array&lt;any&gt;)
69
70Sets the coordinates (relative coordinates) of the end point of the line. An invalid value is handled as the default value.
71
72**Widget capability**: This API can be used in ArkTS widgets since API version 9.
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  | Array&lt;[Length](ts-types.md#length)&gt; | Yes  | Coordinates (relative coordinates) of the end point of the line, in vp.<br>Default value: **[0, 0]**|
83
84### fill
85
86fill(value: ResourceColor)
87
88Sets the color of the fill area. This attribute has no effect for the **Line** component, which cannot be used to draw a closed shape.
89
90**Widget capability**: This API can be used in ArkTS widgets since API version 9.
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  | [ResourceColor](ts-types.md#resourcecolor) | Yes  | Color of the fill area.<br>Default value: **Color.Black**|
101
102### fillOpacity
103
104fillOpacity(value: number | string | Resource)
105
106Sets the opacity of the fill area. This attribute has no effect for the **Line** component, which cannot be used to draw a closed shape.
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 \| [Resource](ts-types.md#resource) | Yes  | Opacity of the fill area.<br>Default value: **1**|
119
120### stroke
121
122stroke(value: ResourceColor)
123
124Sets 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.
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  | Stroke color.|
137
138### strokeDashArray
139
140strokeDashArray(value: Array&lt;any&gt;)
141
142Sets stroke dashes. Line segments may overlap when they intersect. An invalid value is handled as the default value.
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  | Array&lt;[Length](ts-types.md#length)&gt; | Yes  | Stroke dashes.<br>Default value: **[]**<br>Default unit: vp|
155
156### strokeDashOffset
157
158strokeDashOffset(value: number | string)
159
160Sets the offset of the start point for drawing the stroke.
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  | number \| string | Yes  | Offset of the start point for drawing the stroke.<br>Default value: **0**<br>Default unit: vp|
173
174### strokeLineCap
175
176strokeLineCap(value: LineCapStyle)
177
178Sets the cap style of the stroke.
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  | [LineCapStyle](ts-appendix-enums.md#linecapstyle) | Yes  | Cap style of the stroke.<br>Default value: **LineCapStyle.Butt**|
191
192### strokeLineJoin
193
194strokeLineJoin(value: LineJoinStyle)
195
196Sets the join style of the stroke. This attribute has no effect for the **Line** component, which does not have corners.
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  | [LineJoinStyle](ts-appendix-enums.md#linejoinstyle) | Yes  | Join style of the stroke.<br>Default value: **LineJoinStyle.Miter**|
209
210### strokeMiterLimit
211
212strokeMiterLimit(value: number | string)
213
214Sets the limit value when the sharp angle is drawn as a miter. This attribute has no effect for the **Line** component, which cannot be used to draw a shape with a sharp angle.
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  | number \| string | Yes  | Limit value when the sharp angle is drawn as a miter.<br>Default value: **4**|
227
228### strokeOpacity
229
230strokeOpacity(value: number | string | Resource)
231
232Sets the stroke opacity. 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**.
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  | number \| string \| [Resource](ts-types.md#resource) | Yes  | Stroke opacity.<br>Default value: **1**|
245
246### strokeWidth
247
248strokeWidth(value: Length)
249
250Sets the stroke width. If of the string type, this attribute cannot be set in percentage. A percentage is processed as 1px.
251
252**Widget capability**: This API can be used in ArkTS widgets since API version 9.
253
254**Atomic service API**: This API can be used in atomic services since API version 11.
255
256**System capability**: SystemCapability.ArkUI.ArkUI.Full
257
258**Parameters**
259
260| Name| Type                        | Mandatory| Description                    |
261| ------ | ---------------------------- | ---- | ------------------------ |
262| value  | [Length](ts-types.md#length) | Yes  | Stroke width.<br>Default value: **1**<br>Default unit: vp|
263
264### antiAlias
265
266antiAlias(value: boolean)
267
268Specifies whether anti-aliasing is enabled.
269
270**Widget capability**: This API can be used in ArkTS widgets since API version 9.
271
272**Atomic service API**: This API can be used in atomic services since API version 11.
273
274**System capability**: SystemCapability.ArkUI.ArkUI.Full
275
276**Parameters**
277
278| Name| Type   | Mandatory| Description                                 |
279| ------ | ------- | ---- | ------------------------------------- |
280| value  | boolean | Yes  | Whether anti-aliasing is enabled.<br>Default value: **true**|
281
282## Example
283
284### Example 1: Drawing a Line
285
286This example demonstrates how to use **startPoint**, **endPoint**, **fillOpacity**, **stroke**, **strokeDashArray**, and **strokeDashOffset** to set the start point, end point, opacity, stroke color, stroke dashes, and stroke offset of a line.
287
288```ts
289// xxx.ets
290@Entry
291@Component
292struct LineExample {
293  build() {
294    Column({ space: 10 }) {
295      // The coordinates of the start and end points of the line are determined relative to the coordinates of the drawing area of the <Line> component.
296      Line()
297        .width(200)
298        .height(150)
299        .startPoint([0, 0])
300        .endPoint([50, 100])
301        .stroke(Color.Black)
302        .backgroundColor('#F5F5F5')
303      Line()
304        .width(200)
305        .height(150)
306        .startPoint([50, 50])
307        .endPoint([150, 150])
308        .strokeWidth(5)
309        .stroke(Color.Orange)
310        .strokeOpacity(0.5)
311        .backgroundColor('#F5F5F5')
312      // strokeDashOffset is used to define the offset when the associated strokeDashArray array is rendered.
313      Line()
314        .width(200)
315        .height(150)
316        .startPoint([0, 0])
317        .endPoint([100, 100])
318        .stroke(Color.Black)
319        .strokeWidth(3)
320        .strokeDashArray([10, 3])
321        .strokeDashOffset(5)
322        .backgroundColor('#F5F5F5')
323      // If the coordinates of a point are beyond the width and height range of the <Line> component, the line will exceed the drawing area.
324      Line()
325        .width(50)
326        .height(50)
327        .startPoint([0, 0])
328        .endPoint([100, 100])
329        .stroke(Color.Black)
330        .strokeWidth(3)
331        .strokeDashArray([10, 3])
332        .backgroundColor('#F5F5F5')
333    }
334  }
335}
336```
337
338![en-us_image_0000001219982725](figures/en-us_image_0000001219982725.png)
339
340### Example 2: Setting the Stroke Cap Style
341
342This example demonstrates how to use **strokeLineCap** to set the stroke cap style of a line.
343
344```ts
345// xxx.ets
346@Entry
347@Component
348struct LineExample1 {
349  build() {
350    Row({ space: 10 }) {
351      // Set LineCapStyle to Butt.
352      Line()
353        .width(100)
354        .height(200)
355        .startPoint([50, 50])
356        .endPoint([50, 200])
357        .stroke(Color.Black)
358        .strokeWidth(20)
359        .strokeLineCap(LineCapStyle.Butt)
360        .backgroundColor('#F5F5F5').margin(10)
361      // Set LineCapStyle to Round.
362      Line()
363        .width(100)
364        .height(200)
365        .startPoint([50, 50])
366        .endPoint([50, 200])
367        .stroke(Color.Black)
368        .strokeWidth(20)
369        .strokeLineCap(LineCapStyle.Round)
370        .backgroundColor('#F5F5F5')
371      // Set LineCapStyle to Square.
372      Line()
373        .width(100)
374        .height(200)
375        .startPoint([50, 50])
376        .endPoint([50, 200])
377        .stroke(Color.Black)
378        .strokeWidth(20)
379        .strokeLineCap(LineCapStyle.Square)
380        .backgroundColor('#F5F5F5')
381    }
382  }
383}
384```
385
386![en-us_image1_0000001219982725](figures/en-us_image1_0000001219982725.png)
387
388### Example 3: Setting the Stroke Dashes
389
390This example demonstrates how to use **strokeDashArray** to set the stroke dashes of a line.
391
392```ts
393// xxx.ets
394@Entry
395@Component
396struct LineExample {
397  build() {
398    Column() {
399      Line()
400        .width(300)
401        .height(30)
402        .startPoint([50, 30])
403        .endPoint([300, 30])
404        .stroke(Color.Black)
405        .strokeWidth(10)
406      // Set the interval for strokeDashArray to 50.
407      Line()
408        .width(300)
409        .height(30)
410        .startPoint([50, 20])
411        .endPoint([300, 20])
412        .stroke(Color.Black)
413        .strokeWidth(10)
414        .strokeDashArray([50])
415      // Set the interval for strokeDashArray to 50, 10.
416      Line()
417        .width(300)
418        .height(30)
419        .startPoint([50, 20])
420        .endPoint([300, 20])
421        .stroke(Color.Black)
422        .strokeWidth(10)
423        .strokeDashArray([50, 10])
424      // Set the interval for strokeDashArray to 50, 10, 20.
425      Line()
426        .width(300)
427        .height(30)
428        .startPoint([50, 20])
429        .endPoint([300, 20])
430        .stroke(Color.Black)
431        .strokeWidth(10)
432        .strokeDashArray([50, 10, 20])
433      // Set the interval for strokeDashArray to 50, 10, 20, 30.
434      Line()
435        .width(300)
436        .height(30)
437        .startPoint([50, 20])
438        .endPoint([300, 20])
439        .stroke(Color.Black)
440        .strokeWidth(10)
441        .strokeDashArray([50, 10, 20, 30])
442
443    }
444  }
445}
446```
447
448![en-us_image2_0000001219982725](figures/en-us_image2_0000001219982725.PNG)
449