• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Line
2
3直线绘制组件。
4
5>  **说明：**
6>
7> 该组件从API version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
8
9## 子组件
10
11无
12
13
14## 接口
15
16Line(options?: LineOptions)
17
18**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
19
20**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
21
22**系统能力：** SystemCapability.ArkUI.ArkUI.Full
23
24**参数：**
25
26| 参数名 | 类型 | 必填 | 说明
27| -------- | -------- | -------- | -------- |
28| options | [LineOptions](ts-drawing-components-line.md#lineoptions18对象说明) | 否 | Line绘制区域。 |
29
30## LineOptions<sup>18+</sup>对象说明
31用于描述Line绘制区域。
32
33**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。
34
35**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。
36
37**系统能力：** SystemCapability.ArkUI.ArkUI.Full
38
39| 名称 | 类型 | 必填 | 说明 |
40| -------- | -------- | -------- | -------- |
41| width | string \| number | 否 | 宽度。<br/>值为异常值或缺省时按照自身内容需要的宽度处理。<br/>默认单位：vp |
42| height | string \| number | 否 | 高度。<br/>值为异常值或缺省时按照自身内容需要的宽度处理。<br/>默认单位：vp |
43
44## 属性
45
46除支持[通用属性](ts-component-general-attributes.md)外，还支持以下属性：
47
48### startPoint
49
50startPoint(value: Array&lt;any&gt;)
51
52设置直线起点坐标点（相对坐标），异常值按照默认值处理。
53
54**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
55
56**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
57
58**系统能力：** SystemCapability.ArkUI.ArkUI.Full
59
60**参数：**
61
62| 参数名 | 类型                                      | 必填 | 说明                                                         |
63| ------ | ----------------------------------------- | ---- | ------------------------------------------------------------ |
64| value  | Array&lt;[Length](ts-types.md#length)&gt; | 是   | 直线起点坐标点（相对坐标），单位vp。<br/>默认值：[0,&nbsp;0] |
65
66### endPoint
67
68endPoint(value: Array&lt;any&gt;)
69
70设置直线终点坐标点（相对坐标），异常值按照默认值处理。
71
72**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
73
74**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
75
76**系统能力：** SystemCapability.ArkUI.ArkUI.Full
77
78**参数：**
79
80| 参数名 | 类型                                      | 必填 | 说明                                                         |
81| ------ | ----------------------------------------- | ---- | ------------------------------------------------------------ |
82| value  | Array&lt;[Length](ts-types.md#length)&gt; | 是   | 直线终点坐标点（相对坐标），单位vp。<br/>默认值：[0,&nbsp;0] |
83
84### fill
85
86fill(value: ResourceColor)
87
88设置填充区域颜色。Line组件无法形成闭合区域，该属性设置无效。
89
90**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
91
92**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
93
94**系统能力：** SystemCapability.ArkUI.ArkUI.Full
95
96**参数：**
97
98| 参数名 | 类型                                       | 必填 | 说明                                   |
99| ------ | ------------------------------------------ | ---- | -------------------------------------- |
100| value  | [ResourceColor](ts-types.md#resourcecolor) | 是   | 填充区域颜色。<br/>默认值：Color.Black |
101
102### fillOpacity
103
104fillOpacity(value: number | string | Resource)
105
106设置填充区域透明度。Line组件无法形成闭合区域，该属性设置无效。
107
108**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
109
110**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
111
112**系统能力：** SystemCapability.ArkUI.ArkUI.Full
113
114**参数：**
115
116| 参数名 | 类型                                                         | 必填 | 说明                           |
117| ------ | ------------------------------------------------------------ | ---- | ------------------------------ |
118| value  | number&nbsp;\|&nbsp;string&nbsp;\|&nbsp;[Resource](ts-types.md#resource) | 是   | 填充区域透明度。<br/>默认值：1 |
119
120### stroke
121
122stroke(value: ResourceColor)
123
124设置边框颜色，不设置时，默认没有边框。异常值不会绘制边框线条。
125
126**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
127
128**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
129
130**系统能力：** SystemCapability.ArkUI.ArkUI.Full
131
132**参数：**
133
134| 参数名 | 类型                                       | 必填 | 说明       |
135| ------ | ------------------------------------------ | ---- | ---------- |
136| value  | [ResourceColor](ts-types.md#resourcecolor) | 是   | 边框颜色。 |
137
138### strokeDashArray
139
140strokeDashArray(value: Array&lt;any&gt;)
141
142设置边框间隙。线段相交时可能会出现重叠现象。取值范围≥0，异常值按照默认值处理。
143
144**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
145
146**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
147
148**系统能力：** SystemCapability.ArkUI.ArkUI.Full
149
150**参数：**
151
152| 参数名 | 类型                                      | 必填 | 说明                      |
153| ------ | ----------------------------------------- | ---- | ------------------------- |
154| value  | Array&lt;[Length](ts-types.md#length)&gt; | 是   | 边框间隙。<br/>默认值：[]<br/>默认单位：vp |
155
156### strokeDashOffset
157
158strokeDashOffset(value: number | string)
159
160设置边框绘制起点的偏移量。
161
162**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
163
164**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
165
166**系统能力：** SystemCapability.ArkUI.ArkUI.Full
167
168**参数：**
169
170| 参数名 | 类型                       | 必填 | 说明                                 |
171| ------ | -------------------------- | ---- | ------------------------------------ |
172| value  | number&nbsp;\|&nbsp;string | 是   | 边框绘制起点的偏移量。<br/>默认值：0<br/>默认单位：vp |
173
174### strokeLineCap
175
176strokeLineCap(value: LineCapStyle)
177
178设置边框端点绘制样式。
179
180**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
181
182**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
183
184**系统能力：** SystemCapability.ArkUI.ArkUI.Full
185
186**参数：**
187
188| 参数名 | 类型                                              | 必填 | 说明                                             |
189| ------ | ------------------------------------------------- | ---- | ------------------------------------------------ |
190| value  | [LineCapStyle](ts-appendix-enums.md#linecapstyle) | 是   | 边框端点绘制样式。<br/>默认值：LineCapStyle.Butt |
191
192### strokeLineJoin
193
194strokeLineJoin(value: LineJoinStyle)
195
196设置边框拐角绘制样式。Line组件无法形成拐角，该属性设置无效。
197
198**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
199
200**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
201
202**系统能力：** SystemCapability.ArkUI.ArkUI.Full
203
204**参数：**
205
206| 参数名 | 类型                                                | 必填 | 说明                                               |
207| ------ | --------------------------------------------------- | ---- | -------------------------------------------------- |
208| value  | [LineJoinStyle](ts-appendix-enums.md#linejoinstyle) | 是   | 边框拐角绘制样式。<br/>默认值：LineJoinStyle.Miter |
209
210### strokeMiterLimit
211
212strokeMiterLimit(value: number | string)
213
214设置锐角绘制成斜角的极限值。Line组件无法设置锐角图形，该属性设置无效。
215
216**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
217
218**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
219
220**系统能力：** SystemCapability.ArkUI.ArkUI.Full
221
222**参数：**
223
224| 参数名 | 类型                       | 必填 | 说明                                   |
225| ------ | -------------------------- | ---- | -------------------------------------- |
226| value  | number&nbsp;\|&nbsp;string | 是   | 锐角绘制成斜角的极限值。<br/>默认值：4 |
227
228### strokeOpacity
229
230strokeOpacity(value: number | string | Resource)
231
232设置边框透明度。该属性的取值范围是[0.0, 1.0]，若给定值小于0.0，则取值为0.0；若给定值大于1.0，则取值为1.0，其余异常值按1.0处理。
233
234**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
235
236**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
237
238**系统能力：** SystemCapability.ArkUI.ArkUI.Full
239
240**参数：**
241
242| 参数名 | 类型                                                         | 必填 | 说明                       |
243| ------ | ------------------------------------------------------------ | ---- | -------------------------- |
244| value  | number&nbsp;\|&nbsp;string&nbsp;\|&nbsp;[Resource](ts-types.md#resource) | 是   | 边框透明度。<br/>默认值：1 |
245
246### strokeWidth
247
248strokeWidth(value: Length)
249
250设置边框宽度。该属性若为string类型, 暂不支持百分比，百分比按照1px处理。
251
252**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
253
254**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
255
256**系统能力：** SystemCapability.ArkUI.ArkUI.Full
257
258**参数：**
259
260| 参数名 | 类型                         | 必填 | 说明                     |
261| ------ | ---------------------------- | ---- | ------------------------ |
262| value  | [Length](ts-types.md#length) | 是   | 边框宽度，取值范围≥0。<br/>默认值：1<br/>默认单位：vp<br/>异常值按照默认值处理。 |
263
264### antiAlias
265
266antiAlias(value: boolean)
267
268设置是否开启抗锯齿效果。
269
270**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
271
272**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
273
274**系统能力：** SystemCapability.ArkUI.ArkUI.Full
275
276**参数：**
277
278| 参数名 | 类型    | 必填 | 说明                                  |
279| ------ | ------- | ---- | ------------------------------------- |
280| value  | boolean | 是   | 是否开启抗锯齿效果。<br/>true：开启抗锯齿；false：关闭抗锯齿。<br/>默认值：true |
281
282## 示例
283
284### 示例1（组件属性绘制）
285
286使用startPoint、endPoint、fillOpacity、stroke、strokeDashArray、strokeDashOffset属性分别绘制直线的起始点、结束点、透明度、直线颜色、边框间隙、绘制起点。
287
288```ts
289// xxx.ets
290@Entry
291@Component
292struct LineExample {
293  build() {
294    Column({ space: 10 }) {
295      // 线条绘制的起止点坐标均是相对于Line组件本身绘制区域的坐标
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用于定义关联虚线strokeDashArray数组渲染时的偏移
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      // 当坐标点设置的值超出Line组件的宽高范围时，线条会画出组件绘制区域
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![zh-cn_image_0000001219982725](figures/zh-cn_image_0000001219982725.png)
339
340### 示例2（边框端点绘制）
341
342使用strokeLineCap绘制直线的边框端点样式。
343
344```ts
345// xxx.ets
346@Entry
347@Component
348struct LineExample1 {
349  build() {
350    Row({ space: 10 }) {
351      // 当LineCapStyle值为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      // 当LineCapStyle值为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      // 当LineCapStyle值为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![zh-cn_image1_0000001219982725](figures/zh-cn_image1_0000001219982725.png)
388
389### 示例3（边框间隙绘制）
390
391使用strokeDashArray绘制直线的边框间隙。
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      // 设置strokeDashArray的数组间隔为 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      // 设置strokeDashArray的数组间隔为 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      // 设置strokeDashArray的数组间隔为 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      // 设置strokeDashArray的数组间隔为 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![zh-cn_image2_0000001219982725](figures/zh-cn_image2_0000001219982725.PNG)
449