• 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#lineoptions18) | No| Options for drawing a line.|
29
30## LineOptions<sup>18+</sup>
31Describes the options for drawing a line.
32
33**Widget capability**: This API can be used in ArkTS widgets since API version 18.
34
35**Atomic service API**: This API can be used in atomic services since API version 18.
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-component-general-attributes.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. The value must be greater than or equal to 0. Invalid values are treated 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 is treated as **0.0**. A value greater than 1.0 is treated as **1.0**. Any other value is treated as **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. 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.|
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>**true**: Anti-aliasing is enabled.<br>**false**: Anti-aliasing is disabled.<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')
361        .margin(10)
362      // Set LineCapStyle to Round.
363      Line()
364        .width(100)
365        .height(200)
366        .startPoint([50, 50])
367        .endPoint([50, 200])
368        .stroke(Color.Black)
369        .strokeWidth(20)
370        .strokeLineCap(LineCapStyle.Round)
371        .backgroundColor('#F5F5F5')
372      // Set LineCapStyle to Square.
373      Line()
374        .width(100)
375        .height(200)
376        .startPoint([50, 50])
377        .endPoint([50, 200])
378        .stroke(Color.Black)
379        .strokeWidth(20)
380        .strokeLineCap(LineCapStyle.Square)
381        .backgroundColor('#F5F5F5')
382    }
383  }
384}
385```
386
387![en-us_image1_0000001219982725](figures/en-us_image1_0000001219982725.png)
388
389### Example 3: Setting the Stroke Dashes
390
391This example demonstrates how to use **strokeDashArray** to set the stroke dashes of a line.
392
393```ts
394// xxx.ets
395@Entry
396@Component
397struct LineExample {
398  build() {
399    Column() {
400      Line()
401        .width(300)
402        .height(30)
403        .startPoint([50, 30])
404        .endPoint([300, 30])
405        .stroke(Color.Black)
406        .strokeWidth(10)
407      // Set the interval for strokeDashArray to 50.
408      Line()
409        .width(300)
410        .height(30)
411        .startPoint([50, 20])
412        .endPoint([300, 20])
413        .stroke(Color.Black)
414        .strokeWidth(10)
415        .strokeDashArray([50])
416      // Set the interval for strokeDashArray to 50, 10.
417      Line()
418        .width(300)
419        .height(30)
420        .startPoint([50, 20])
421        .endPoint([300, 20])
422        .stroke(Color.Black)
423        .strokeWidth(10)
424        .strokeDashArray([50, 10])
425      // Set the interval for strokeDashArray to 50, 10, 20.
426      Line()
427        .width(300)
428        .height(30)
429        .startPoint([50, 20])
430        .endPoint([300, 20])
431        .stroke(Color.Black)
432        .strokeWidth(10)
433        .strokeDashArray([50, 10, 20])
434      // Set the interval for strokeDashArray to 50, 10, 20, 30.
435      Line()
436        .width(300)
437        .height(30)
438        .startPoint([50, 20])
439        .endPoint([300, 20])
440        .stroke(Color.Black)
441        .strokeWidth(10)
442        .strokeDashArray([50, 10, 20, 30])
443    }
444  }
445}
446```
447
448![en-us_image2_0000001219982725](figures/en-us_image2_0000001219982725.PNG)
449