• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Line
2<!--Kit: ArkUI-->
3<!--Subsystem: ArkUI-->
4<!--Owner: @zjsxstar-->
5<!--Designer: @sunbees-->
6<!--Tester: @liuli0427-->
7<!--Adviser: @HelloCrease-->
8
9直线绘制组件。
10
11>  **说明：**
12>
13> 该组件从API version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
14>
15> 该组件从API version 20开始支持使用[AttributeUpdater](../js-apis-arkui-AttributeUpdater.md)类的[updateConstructorParams](../js-apis-arkui-AttributeUpdater.md#updateconstructorparams)接口更新构造参数。
16
17## 子组件
18
19无
20
21
22## 接口
23
24Line(options?: LineOptions)
25
26**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
27
28**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
29
30**系统能力：** SystemCapability.ArkUI.ArkUI.Full
31
32**参数：**
33
34| 参数名 | 类型 | 必填 | 说明
35| -------- | -------- | -------- | -------- |
36| options | [LineOptions](ts-drawing-components-line.md#lineoptions18对象说明) | 否 | Line绘制区域。 |
37
38## LineOptions<sup>18+</sup>对象说明
39
40用于描述Line组件绘制属性。
41
42> **说明：**
43>
44> 为规范匿名对象的定义，API 18版本修改了此处的元素定义。其中，保留了历史匿名对象的起始版本信息，会出现外层元素@since版本号高于内层元素版本号的情况，但这不影响接口的使用。
45
46**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。
47
48**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。
49
50**系统能力：** SystemCapability.ArkUI.ArkUI.Full
51
52| 名称 | 类型 | 只读 | 可选 | 说明 |
53| -------- | -------- | -------- | -------- | -------- |
54| width<sup>7+</sup> | [Length](ts-types.md#length) | 否 | 是 | 宽度。<br/>值为异常值或缺省时按照自身内容需要的宽度处理。<br/>默认单位：vp<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 |
55| height<sup>7+</sup> | [Length](ts-types.md#length) | 否 | 是 | 高度。<br/>值为异常值或缺省时按照自身内容需要的高度处理。<br/>默认单位：vp<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 |
56
57## 属性
58
59除支持[通用属性](ts-component-general-attributes.md)外，还支持以下属性：
60
61### startPoint
62
63startPoint(value: Array&lt;any&gt;)
64
65设置直线起点坐标点（相对坐标），支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法，异常值按照默认值处理。
66
67**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
68
69**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
70
71**系统能力：** SystemCapability.ArkUI.ArkUI.Full
72
73**参数：**
74
75| 参数名 | 类型                                      | 必填 | 说明                                                         |
76| ------ | ----------------------------------------- | ---- | ------------------------------------------------------------ |
77| value  | Array&lt;any&gt; | 是   | 直线起点坐标点（相对坐标），单位vp。<br/>默认值：[0,&nbsp;0] |
78
79### endPoint
80
81endPoint(value: Array&lt;any&gt;)
82
83设置直线终点坐标点（相对坐标），支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法，异常值按照默认值处理。
84
85**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
86
87**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
88
89**系统能力：** SystemCapability.ArkUI.ArkUI.Full
90
91**参数：**
92
93| 参数名 | 类型                                      | 必填 | 说明                                                         |
94| ------ | ----------------------------------------- | ---- | ------------------------------------------------------------ |
95| value  | Array&lt;any&gt; | 是   | 直线终点坐标点（相对坐标），单位vp。<br/>默认值：[0,&nbsp;0] |
96
97### fill
98
99fill(value: ResourceColor)
100
101设置填充区域颜色，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。Line组件无法形成闭合区域，该属性设置无效。
102
103**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
104
105**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
106
107**系统能力：** SystemCapability.ArkUI.ArkUI.Full
108
109**参数：**
110
111| 参数名 | 类型                                       | 必填 | 说明                                   |
112| ------ | ------------------------------------------ | ---- | -------------------------------------- |
113| value  | [ResourceColor](ts-types.md#resourcecolor) | 是   | 填充区域颜色。<br/>默认值：Color.Black |
114
115### fillOpacity
116
117fillOpacity(value: number | string | Resource)
118
119设置填充区域透明度，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。Line组件无法形成闭合区域，该属性设置无效。
120
121**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
122
123**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
124
125**系统能力：** SystemCapability.ArkUI.ArkUI.Full
126
127**参数：**
128
129| 参数名 | 类型                                                         | 必填 | 说明                           |
130| ------ | ------------------------------------------------------------ | ---- | ------------------------------ |
131| value  | number&nbsp;\|&nbsp;string&nbsp;\|&nbsp;[Resource](ts-types.md#resource) | 是   | 填充区域透明度。<br/>**说明：**<br/>number格式取值范围是[0.0, 1.0]，若给定值小于0.0，则取值为0.0；若给定值大于1.0，则取值为1.0，其余异常值按1.0处理。<br/>string格式支持number格式取值的字符串形式，取值范围与number格式相同。<br/>Resource格式支持系统资源或者应用资源中的字符串，取值范围和number格式相同。<br/>默认值：1 |
132
133### stroke
134
135stroke(value: ResourceColor)
136
137设置边框颜色，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法，不设置时，默认边框透明度为0，即没有边框。异常值不会绘制边框线条。
138
139**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
140
141**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
142
143**系统能力：** SystemCapability.ArkUI.ArkUI.Full
144
145**参数：**
146
147| 参数名 | 类型                                       | 必填 | 说明       |
148| ------ | ------------------------------------------ | ---- | ---------- |
149| value  | [ResourceColor](ts-types.md#resourcecolor) | 是   | 边框颜色。 |
150
151### strokeDashArray
152
153strokeDashArray(value: Array&lt;any&gt;)
154
155设置边框间隙，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。线段相交时可能会出现重叠现象。取值范围≥0，异常值按照默认值处理。
156
157**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
158
159**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
160
161**系统能力：** SystemCapability.ArkUI.ArkUI.Full
162
163**参数：**
164
165| 参数名 | 类型                                      | 必填 | 说明                      |
166| ------ | ----------------------------------------- | ---- | ------------------------- |
167| value  | Array&lt;any&gt; | 是   | 边框间隙。<br/>默认值：[]（空数组）<br/>默认单位：vp |
168
169### strokeDashOffset
170
171strokeDashOffset(value: number | string)
172
173设置边框绘制起点的偏移量，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。
174
175**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
176
177**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
178
179**系统能力：** SystemCapability.ArkUI.ArkUI.Full
180
181**参数：**
182
183| 参数名 | 类型                       | 必填 | 说明                                 |
184| ------ | -------------------------- | ---- | ------------------------------------ |
185| value  | number&nbsp;\|&nbsp;string | 是   | 边框绘制起点的偏移量。<br/>默认值：0<br/>默认单位：vp |
186
187### strokeLineCap
188
189strokeLineCap(value: LineCapStyle)
190
191设置边框端点绘制样式，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。
192
193**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
194
195**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
196
197**系统能力：** SystemCapability.ArkUI.ArkUI.Full
198
199**参数：**
200
201| 参数名 | 类型                                              | 必填 | 说明                                             |
202| ------ | ------------------------------------------------- | ---- | ------------------------------------------------ |
203| value  | [LineCapStyle](ts-appendix-enums.md#linecapstyle) | 是   | 边框端点绘制样式。<br/>默认值：LineCapStyle.Butt |
204
205### strokeLineJoin
206
207strokeLineJoin(value: LineJoinStyle)
208
209设置边框拐角绘制样式，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。Line组件不支持拐角，该属性设置无效。
210
211**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
212
213**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
214
215**系统能力：** SystemCapability.ArkUI.ArkUI.Full
216
217**参数：**
218
219| 参数名 | 类型                                                | 必填 | 说明                                               |
220| ------ | --------------------------------------------------- | ---- | -------------------------------------------------- |
221| value  | [LineJoinStyle](ts-appendix-enums.md#linejoinstyle) | 是   | 边框拐角绘制样式。<br/>默认值：LineJoinStyle.Miter |
222
223### strokeMiterLimit
224
225strokeMiterLimit(value: number | string)
226
227设置锐角绘制成斜角的极限值，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。Line组件不支持设置锐角图形，该属性设置无效。
228
229**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
230
231**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
232
233**系统能力：** SystemCapability.ArkUI.ArkUI.Full
234
235**参数：**
236
237| 参数名 | 类型                       | 必填 | 说明                                   |
238| ------ | -------------------------- | ---- | -------------------------------------- |
239| value  | number&nbsp;\|&nbsp;string | 是   | 锐角绘制成斜角的极限值。<br/>默认值：4 |
240
241### strokeOpacity
242
243strokeOpacity(value: number | string | Resource)
244
245设置边框透明度，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。该属性的取值范围是[0.0, 1.0]，若给定值小于0.0，则取值为0.0；若给定值大于1.0，则取值为1.0，其余异常值按1.0处理。
246
247**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
248
249**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
250
251**系统能力：** SystemCapability.ArkUI.ArkUI.Full
252
253**参数：**
254
255| 参数名 | 类型                                                         | 必填 | 说明                       |
256| ------ | ------------------------------------------------------------ | ---- | -------------------------- |
257| value  | number&nbsp;\|&nbsp;string&nbsp;\|&nbsp;[Resource](ts-types.md#resource) | 是   | 边框透明度。<br/>默认值：[stroke](#stroke)接口设置的透明度。 |
258
259### strokeWidth
260
261strokeWidth(value: Length)
262
263设置边框宽度，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。该属性若为string类型, 暂不支持百分比，百分比按照1px处理。
264
265**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
266
267**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
268
269**系统能力：** SystemCapability.ArkUI.ArkUI.Full
270
271**参数：**
272
273| 参数名 | 类型                         | 必填 | 说明                     |
274| ------ | ---------------------------- | ---- | ------------------------ |
275| value  | [Length](ts-types.md#length) | 是   | 边框宽度，取值范围≥0。<br/>默认值：1<br/>默认单位：vp<br/>异常值按照默认值处理。 |
276
277### antiAlias
278
279antiAlias(value: boolean)
280
281设置是否开启抗锯齿效果，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。
282
283**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
284
285**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
286
287**系统能力：** SystemCapability.ArkUI.ArkUI.Full
288
289**参数：**
290
291| 参数名 | 类型    | 必填 | 说明                                  |
292| ------ | ------- | ---- | ------------------------------------- |
293| value  | boolean | 是   | 是否开启抗锯齿效果。<br/>true：开启抗锯齿；false：关闭抗锯齿。<br/>默认值：true |
294
295## 示例
296
297### 示例1（组件属性绘制）
298
299通过startPoint、endPoint、fillOpacity、stroke、strokeDashArray、strokeDashOffset属性分别绘制直线的起始点、结束点、透明度、直线颜色、边框间隙、绘制起点。
300
301```ts
302// xxx.ets
303@Entry
304@Component
305struct LineExample {
306  build() {
307    Column({ space: 10 }) {
308      // 线条绘制的起止点坐标均是相对于Line组件本身绘制区域的坐标
309      Line()
310        .width(200)
311        .height(150)
312        .startPoint([0, 0])
313        .endPoint([50, 100])
314        .stroke(Color.Black)
315        .backgroundColor('#F5F5F5')
316      Line()
317        .width(200)
318        .height(150)
319        .startPoint([50, 50])
320        .endPoint([150, 150])
321        .strokeWidth(5)
322        .stroke(Color.Orange)
323        .strokeOpacity(0.5)
324        .backgroundColor('#F5F5F5')
325      // strokeDashOffset用于定义关联虚线strokeDashArray数组渲染时的偏移
326      Line()
327        .width(200)
328        .height(150)
329        .startPoint([0, 0])
330        .endPoint([100, 100])
331        .stroke(Color.Black)
332        .strokeWidth(3)
333        .strokeDashArray([10, 3])
334        .strokeDashOffset(5)
335        .backgroundColor('#F5F5F5')
336      // 当坐标点设置的值超出Line组件的宽高范围时，线条会画出组件绘制区域
337      Line()
338        .width(50)
339        .height(50)
340        .startPoint([0, 0])
341        .endPoint([100, 100])
342        .stroke(Color.Black)
343        .strokeWidth(3)
344        .strokeDashArray([10, 3])
345        .backgroundColor('#F5F5F5')
346    }
347  }
348}
349```
350
351![zh-cn_image_0000001219982725](figures/zh-cn_image_0000001219982725.png)
352
353### 示例2（边框端点绘制）
354
355通过strokeLineCap属性绘制直线的边框端点样式。
356
357```ts
358// xxx.ets
359@Entry
360@Component
361struct LineExample1 {
362  build() {
363    Row({ space: 10 }) {
364      // 当LineCapStyle值为Butt时
365      Line()
366        .width(100)
367        .height(200)
368        .startPoint([50, 50])
369        .endPoint([50, 200])
370        .stroke(Color.Black)
371        .strokeWidth(20)
372        .strokeLineCap(LineCapStyle.Butt)
373        .backgroundColor('#F5F5F5')
374        .margin(10)
375      // 当LineCapStyle值为Round时
376      Line()
377        .width(100)
378        .height(200)
379        .startPoint([50, 50])
380        .endPoint([50, 200])
381        .stroke(Color.Black)
382        .strokeWidth(20)
383        .strokeLineCap(LineCapStyle.Round)
384        .backgroundColor('#F5F5F5')
385      // 当LineCapStyle值为Square时
386      Line()
387        .width(100)
388        .height(200)
389        .startPoint([50, 50])
390        .endPoint([50, 200])
391        .stroke(Color.Black)
392        .strokeWidth(20)
393        .strokeLineCap(LineCapStyle.Square)
394        .backgroundColor('#F5F5F5')
395    }
396  }
397}
398```
399
400![zh-cn_image1_0000001219982725](figures/zh-cn_image1_0000001219982725.png)
401
402### 示例3（边框间隙绘制）
403
404通过strokeDashArray属性绘制直线的边框间隙。
405
406```ts
407// xxx.ets
408@Entry
409@Component
410struct LineExample {
411  build() {
412    Column() {
413      Line()
414        .width(300)
415        .height(30)
416        .startPoint([50, 30])
417        .endPoint([300, 30])
418        .stroke(Color.Black)
419        .strokeWidth(10)
420      // 设置strokeDashArray的数组间隔为 50
421      Line()
422        .width(300)
423        .height(30)
424        .startPoint([50, 20])
425        .endPoint([300, 20])
426        .stroke(Color.Black)
427        .strokeWidth(10)
428        .strokeDashArray([50])
429      // 设置strokeDashArray的数组间隔为 50, 10
430      Line()
431        .width(300)
432        .height(30)
433        .startPoint([50, 20])
434        .endPoint([300, 20])
435        .stroke(Color.Black)
436        .strokeWidth(10)
437        .strokeDashArray([50, 10])
438      // 设置strokeDashArray的数组间隔为 50, 10, 20
439      Line()
440        .width(300)
441        .height(30)
442        .startPoint([50, 20])
443        .endPoint([300, 20])
444        .stroke(Color.Black)
445        .strokeWidth(10)
446        .strokeDashArray([50, 10, 20])
447      // 设置strokeDashArray的数组间隔为 50, 10, 20, 30
448      Line()
449        .width(300)
450        .height(30)
451        .startPoint([50, 20])
452        .endPoint([300, 20])
453        .stroke(Color.Black)
454        .strokeWidth(10)
455        .strokeDashArray([50, 10, 20, 30])
456    }
457  }
458}
459```
460
461![zh-cn_image2_0000001219982725](figures/zh-cn_image2_0000001219982725.PNG)
462
463### 示例4（宽和高使用不同参数类型绘制直线）
464
465width、height属性分别使用不同的长度类型绘制直线。
466
467```ts
468// xxx.ets
469@Entry
470@Component
471struct LineTypeExample {
472  build() {
473    Column({ space: 10 }) {
474      // 在200 * 200的区域内绘制一个起始点为（0,0），终点为（150,150），边框宽度为10的直线
475      Line({ width: '200', height: '200' })// 使用string类型
476        .startPoint([0, 0])
477        .endPoint([150, 150])
478        .stroke(Color.Black)
479        .strokeWidth(10)
480        .backgroundColor('#F5F5F5')
481        .margin(10)
482      // 在200 * 200的区域内绘制一个起始点为（0,50），终点为（150,150），边框宽度为10的直线
483      Line({ width: 200, height: 200 })// 使用number类型
484        .startPoint([0, 50])
485        .endPoint([150, 150])
486        .stroke(Color.Black)
487        .strokeWidth(10)
488        .backgroundColor('#F5F5F5')
489        .margin(10)
490      // 在200 * 200的区域内绘制一个起始点为（0,100），终点为（150,150），边框宽度为10的直线
491      Line({ width: $r('app.string.LineWidth'), height: $r('app.string.LineHeight') })// 使用Resource类型，需用户自定义
492        .startPoint([0, 100])
493        .endPoint([150, 150])
494        .stroke(Color.Black)
495        .strokeWidth(10)
496        .backgroundColor('#F5F5F5')
497        .margin(10)
498    }.width('100%')
499  }
500}
501```
502
503![lineDemo4](figures/lineDemo4.png)
504
505### 示例5（使用attributeModifier动态设置Line组件的属性）
506
507以下示例展示了如何使用attributeModifier动态设置Line组件的startPoint、endPoint、stroke、strokeDashArray、strokeDashOffset、strokeLineCap、strokeOpacity、strokeWidth和antiAlias属性。
508
509```ts
510// xxx.ets
511class MyLineModifier implements AttributeModifier<LineAttribute> {
512  applyNormalAttribute(instance: LineAttribute): void {
513    // 一个起始点为（10, 10），终点为（120, 10）的直线，边框颜色#2787D9，边框间隙[20]，向左偏移15，线条两端样式为半圆，边框透明度0.5，边框宽度10，抗锯齿开启
514    instance.startPoint([10,10])
515    instance.endPoint([120, 10])
516    instance.stroke("#2787D9")
517    instance.strokeDashArray([20])
518    instance.strokeDashOffset("15")
519    instance.strokeLineCap(LineCapStyle.Round)
520    instance.strokeOpacity(0.5)
521    instance.strokeWidth(10)
522    instance.antiAlias(true)
523  }
524}
525
526@Entry
527@Component
528struct LineModifierDemo {
529  @State modifier: MyLineModifier = new MyLineModifier()
530
531  build() {
532    Column() {
533      Line()
534        .attributeModifier(this.modifier)
535        .offset({ x: 20, y: 20 })
536    }
537  }
538}
539```
540
541![](figures/lineModifier.png)
542