• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Outline
2
3You can set outline attributes for components. Drawn outside the component, the outline does not affect the component's layout or increase its size.
4
5![outlineTest](figures/outlineTest.PNG)
6
7>  **NOTE**
8>
9>  The initial APIs of this module are supported since API version 11. Updates will be marked with a superscript to indicate their earliest API version.
10
11## outline
12
13outline(value: OutlineOptions): T
14
15Sets the outline attributes in one declaration.
16
17**Widget capability**: This API can be used in ArkTS widgets since API version 11.
18
19**Atomic service API**: This API can be used in atomic services since API version 12.
20
21**System capability**: SystemCapability.ArkUI.ArkUI.Full
22
23**Parameters**
24
25| Name| Type                                     | Mandatory| Description        |
26| ------ | ----------------------------------------- | ---- | ------------ |
27| value  | [OutlineOptions](#outlineoptions) | Yes  | Outline attributes.|
28
29**Return value**
30
31| Type  | Description                    |
32| ------ | ------------------------ |
33| T | Current component.|
34
35## outline<sup>18+</sup>
36
37outline(options: Optional\<OutlineOptions>): T
38
39Sets the outline attributes in one declaration. Compared with [outline](#outline), this API supports the **undefined** type for the **options** parameter.
40
41**Widget capability**: This API can be used in ArkTS widgets since API version 18.
42
43**Atomic service API**: This API can be used in atomic services since API version 18.
44
45**System capability**: SystemCapability.ArkUI.ArkUI.Full
46
47**Parameters**
48
49| Name| Type                                     | Mandatory| Description|
50| ------ | ----------------------------------------- | ---- | ---- |
51| options | Optional\<[OutlineOptions](#outlineoptions)> | Yes  |   Outline attributes.<br>If **options** is **undefined**, the component reverts to its original style with no outline.  |
52
53**Return value**
54
55| Type  | Description                    |
56| ------ | ------------------------ |
57| T | Current component.|
58
59## OutlineStyle<sup>11+</sup>
60
61Outline attributes.
62
63**Widget capability**: This API can be used in ArkTS widgets since API version 11.
64
65**Atomic service API**: This API can be used in atomic services since API version 12.
66
67**System capability**: SystemCapability.ArkUI.ArkUI.Full
68
69| Name    | Description                           |
70| ------ | ----------------------------- |
71| SOLID  | Solid border.                     |
72| DASHED | Dashed border.                |
73| DOTTED | Dotted border. The radius of a dot is half of **outlineWidth**.|
74
75## outlineStyle
76
77outlineStyle(value: OutlineStyle | EdgeOutlineStyles): T
78
79Sets the style of the outline.
80
81**Widget capability**: This API can be used in ArkTS widgets since API version 11.
82
83**Atomic service API**: This API can be used in atomic services since API version 12.
84
85**System capability**: SystemCapability.ArkUI.ArkUI.Full
86
87**Parameters**
88
89| Name| Type                                                        | Mandatory| Description                                                 |
90| ------ | ------------------------------------------------------------ | ---- | ----------------------------------------------------- |
91| value  | [OutlineStyle](#outlinestyle11) \| [EdgeOutlineStyles](#edgeoutlinestyles) | Yes  | Outline style.<br>Default value: **OutlineStyle.SOLID**|
92
93**Return value**
94
95| Type  | Description                    |
96| ------ | ------------------------ |
97| T | Current component.|
98
99## outlineStyle<sup>18+</sup>
100
101outlineStyle(style: Optional\<OutlineStyle | EdgeOutlineStyles>): T
102
103Sets the style of the outline. Compared with [outlineStyle](#outlinestyle), this API supports the **undefined** type for the **style** parameter.
104
105**Widget capability**: This API can be used in ArkTS widgets since API version 18.
106
107**Atomic service API**: This API can be used in atomic services since API version 18.
108
109**System capability**: SystemCapability.ArkUI.ArkUI.Full
110
111**Parameters**
112
113| Name| Type                                                        | Mandatory| Description                                                        |
114| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
115| style  | Optional\<[OutlineStyle](#outlinestyle11) \| [EdgeOutlineStyles](#edgeoutlinestyles)> | Yes  | Outline style.<br>Default value: **OutlineStyle.SOLID**<br>If **style** is **undefined**, the component reverts to its original style with no outline.|
116
117**Return value**
118
119| Type  | Description                    |
120| ------ | ------------------------ |
121| T | Current component.|
122
123## outlineWidth
124
125outlineWidth(value: Dimension | EdgeOutlineWidths): T
126
127Sets the thickness of the outline.
128
129**Widget capability**: This API can be used in ArkTS widgets since API version 11.
130
131**Atomic service API**: This API can be used in atomic services since API version 12.
132
133**System capability**: SystemCapability.ArkUI.ArkUI.Full
134
135**Parameters**
136
137| Name| Type                                                        | Mandatory| Description                                                 |
138| ------ | ------------------------------------------------------------ | ---- | ----------------------------------------------------- |
139| value  | [Dimension](ts-types.md#dimension10) \| [EdgeOutlineWidths](#edgeoutlinewidths) | Yes  | Outline thickness. Percentage values are not supported.<br>Default value: **0**|
140
141**Return value**
142
143| Type  | Description                    |
144| ------ | ------------------------ |
145| T | Current component.|
146
147## outlineWidth<sup>18+</sup>
148
149outlineWidth(width: Optional\<Dimension | EdgeOutlineWidths>): T
150
151Sets the thickness of the outline. Compared with [[outlineWidth](#outlinewidth), this API supports the **undefined** type for the **width** parameter.
152
153**Widget capability**: This API can be used in ArkTS widgets since API version 18.
154
155**Atomic service API**: This API can be used in atomic services since API version 18.
156
157**System capability**: SystemCapability.ArkUI.ArkUI.Full
158
159**Parameters**
160
161| Name| Type                                                        | Mandatory| Description                                                        |
162| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
163| width  | Optional\<[Dimension](ts-types.md#dimension10) \| [EdgeOutlineWidths](#edgeoutlinewidths)> | Yes  | Outline thickness. Percentage values are not supported.<br>Default value: **0**<br>If **width** is **undefined**, the component reverts to its original style with no outline width.|
164
165**Return value**
166
167| Type  | Description                    |
168| ------ | ------------------------ |
169| T | Current component.|
170
171## outlineColor
172
173outlineColor(value: ResourceColor | EdgeColors): T
174
175Sets the color of the outline.
176
177**Widget capability**: This API can be used in ArkTS widgets since API version 11.
178
179**Atomic service API**: This API can be used in atomic services since API version 12.
180
181**System capability**: SystemCapability.ArkUI.ArkUI.Full
182
183**Parameters**
184
185| Name| Type                                                        | Mandatory| Description                                            |
186| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------ |
187| value  | [ResourceColor](ts-types.md#resourcecolor) \| [EdgeColors](#edgecolors) | Yes  | Outline color.<br>Default value: **Color.Black**.|
188
189**Return value**
190
191| Type  | Description                    |
192| ------ | ------------------------ |
193| T | Current component.|
194
195## outlineColor<sup>18+</sup>
196
197outlineColor(color: Optional\<ResourceColor | EdgeColors>): T
198
199Sets the color of the outline. Compared with [outlineColor](#outlinecolor), this API supports the **undefined** type for the **color** parameter.
200
201**Widget capability**: This API can be used in ArkTS widgets since API version 18.
202
203**Atomic service API**: This API can be used in atomic services since API version 18.
204
205**System capability**: SystemCapability.ArkUI.ArkUI.Full
206
207**Parameters**
208
209| Name| Type                                                        | Mandatory| Description                                                        |
210| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
211| color  | Optional\<[ResourceColor](ts-types.md#resourcecolor) \| [EdgeColors](#edgecolors)> | Yes  | Outline color.<br>Default value: **Color.Black**.<br>If **color** is **undefined**, the component reverts to its original style with the outline color of **Color.Black**.|
212
213**Return value**
214
215| Type  | Description                    |
216| ------ | ------------------------ |
217| T | Current component.|
218
219## outlineRadius
220
221outlineRadius(value: Dimension | OutlineRadiuses): T
222
223Sets the radius of the outline corners.
224
225**Widget capability**: This API can be used in ArkTS widgets since API version 11.
226
227**Atomic service API**: This API can be used in atomic services since API version 12.
228
229**System capability**: SystemCapability.ArkUI.ArkUI.Full
230
231**Parameters**
232
233| Name| Type                                                        | Mandatory| Description                                                        |
234| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
235| value  | [Dimension](ts-types.md#dimension10) \| [OutlineRadiuses](#outlineradiuses) | Yes  | Radius of the outline corners. Percentage values are not supported.<br>Default value: **0**<br>Maximum effective value: Component width/2 + outlineWidth or component height/2 + outlineWidth|
236
237**Return value**
238
239| Type  | Description                    |
240| ------ | ------------------------ |
241| T | Current component.|
242
243## outlineRadius<sup>18+</sup>
244
245outlineRadius(radius: Optional\<Dimension | OutlineRadiuses>): T
246
247Sets the radius of the outline corners. Compared with [outlineRadius](#outlineradius), this API supports the **undefined** type for the **radius** parameter.
248
249**Widget capability**: This API can be used in ArkTS widgets since API version 18.
250
251**Atomic service API**: This API can be used in atomic services since API version 18.
252
253**System capability**: SystemCapability.ArkUI.ArkUI.Full
254
255**Parameters**
256
257| Name| Type                                                        | Mandatory| Description                                                        |
258| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
259| radius | Optional\<[Dimension](ts-types.md#dimension10) \| [OutlineRadiuses](#outlineradiuses)> | Yes  | Radius of the outline corners. Percentage values are not supported.<br>Default value: **0**<br>Maximum effective value: Component width/2 + outlineWidth or component height/2 + outlineWidth<br>If **radius** is **undefined**, the component reverts to its original style with the outline corner radius of 0.|
260
261**Return value**
262
263| Type  | Description                    |
264| ------ | ------------------------ |
265| T | Current component.|
266
267## OutlineOptions
268
269**Atomic service API**: This API can be used in atomic services since API version 12.
270
271**Widget capability**: This API can be used in ArkTS widgets since API version 12.
272
273| Name  | Type                  |Mandatory                                     | Description                                                        |
274| ------ | ----------------------|-------------------------------------- | ------------------------------------------------------------ |
275| width  | [Dimension](ts-types.md#dimension10) \| [EdgeOutlineWidths](#edgeoutlinewidths) | No| Outline thickness. Percentage values are not supported.<br>Default value: **0**.<br>**width** must be set to display the outline effect.|
276| color  | [ResourceColor](ts-types.md#resourcecolor) \| [EdgeColors](#edgecolors) \| [LocalizedEdgeColors](#localizededgecolors12)<sup>12+</sup> |No| Outline color.<br>Default value: **Color.Black**.                  |
277| radius | [Dimension](ts-types.md#dimension10) \| [OutlineRadiuses](#outlineradiuses) | No| Radius of the outline corners. Percentage values are not supported.<br>Default value: **0**<br>Maximum effective value: Component width/2 + outlineWidth or component height/2 + outlineWidth|
278| style  | [OutlineStyle](#outlinestyle11) \| [EdgeOutlineStyles](#edgeoutlinestyles) |No| Outline style.<br>Default value: **OutlineStyle.SOLID**           |
279
280## EdgeOutlineWidths
281
282To reference this object, at least one parameter must be passed.
283
284**Atomic service API**: This API can be used in atomic services since API version 12.
285
286**Widget capability**: This API can be used in ArkTS widgets since API version 12.
287
288| Name    | Type                        | Mandatory  | Description     |
289| ------ | ---------------------------- | ---- | ------- |
290| left   | [Dimension](ts-types.md#dimension10) | No   | Thickness of the left outline.|
291| right  | [Dimension](ts-types.md#dimension10) | No   | Thickness of the right outline.|
292| top    | [Dimension](ts-types.md#dimension10) | No   | Thickness of the top outline.|
293| bottom | [Dimension](ts-types.md#dimension10) | No   | Thickness of the bottom outline.|
294
295## EdgeColors
296
297To reference this object, at least one parameter must be passed.
298
299**Atomic service API**: This API can be used in atomic services since API version 11.
300
301**System capability**: SystemCapability.ArkUI.ArkUI.Full
302
303**Widget capability**: This API can be used in ArkTS widgets since API version 12.
304
305| Name    | Type                                    | Mandatory  | Description     |
306| ------ | ---------------------------------------- | ---- | ------- |
307| left   | [ResourceColor](ts-types.md#resourcecolor) | No   | Color of the left outline.|
308| right  | [ResourceColor](ts-types.md#resourcecolor) | No   | Color of the right outline.|
309| top    | [ResourceColor](ts-types.md#resourcecolor) | No   | Color of the top outline.|
310| bottom | [ResourceColor](ts-types.md#resourcecolor) | No   | Color of the bottom outline.|
311
312## LocalizedEdgeColors<sup>12+</sup>
313
314To reference this object, at least one parameter must be passed.
315
316**Atomic service API**: This API can be used in atomic services since API version 12.
317
318**Widget capability**: This API can be used in ArkTS widgets since API version 12.
319
320| Name    | Type                                    | Mandatory  | Description     |
321| ------ | ---------------------------------------- | ---- | ------- |
322| start | [ResourceColor](ts-types.md#resourcecolor) | No   | Color of the left outline.<br>For left-to-right scripts, this indicates the color of the right outline.|
323| end | [ResourceColor](ts-types.md#resourcecolor) | No   | Color of the right outline.<br>For left-to-right scripts, this indicates the color of the left outline.|
324| top    | [ResourceColor](ts-types.md#resourcecolor) | No   | Color of the top outline.|
325| bottom | [ResourceColor](ts-types.md#resourcecolor) | No   | Color of the bottom outline.|
326
327## OutlineRadiuses
328
329To reference this object, at least one parameter must be passed.
330
331**Atomic service API**: This API can be used in atomic services since API version 12.
332
333**Widget capability**: This API can be used in ArkTS widgets since API version 12.
334
335| Name         | Type                        | Mandatory  | Description      |
336| ----------- | ---------------------------- | ---- | -------- |
337| topLeft     | [Dimension](ts-types.md#dimension10) | No   | Radius of the upper-left corner.|
338| topRight    | [Dimension](ts-types.md#dimension10) | No   | Radius of the upper-right corner.|
339| bottomLeft  | [Dimension](ts-types.md#dimension10) | No   | Radius of the lower-left corner.|
340| bottomRight | [Dimension](ts-types.md#dimension10) | No   | Radius of the lower-right corner.|
341
342## EdgeOutlineStyles
343
344To reference this object, at least one parameter must be passed.
345
346**Atomic service API**: This API can be used in atomic services since API version 12.
347
348**Widget capability**: This API can be used in ArkTS widgets since API version 12.
349
350| Name    | Type                                    | Mandatory  | Description     |
351| ------ | ---------------------------------------- | ---- | ------- |
352| left   | [OutlineStyle](#outlinestyle11) | No   | Style of the left outline.|
353| right  | [OutlineStyle](#outlinestyle11) | No   | Style of the right outline.|
354| top    | [OutlineStyle](#outlinestyle11) | No   | Style of the top outline.|
355| bottom | [OutlineStyle](#outlinestyle11) | No   | Style of the bottom outline.|
356
357## Example
358
359### Example 1: Creating Outlines
360
361This example demonstrates how to create component outlines using **outline**.
362
363```ts
364// xxx.ets
365@Entry
366@Component
367struct OutlineExample {
368  build() {
369    Column() {
370      Flex({ justifyContent: FlexAlign.SpaceAround, alignItems: ItemAlign.Center }) {
371        // Dashed line
372        Text('DASHED')
373          .backgroundColor(Color.Pink)
374          .outlineStyle(OutlineStyle.DASHED).outlineWidth(5).outlineColor(0xAFEEEE).outlineRadius(10)
375          .width(120).height(120).textAlign(TextAlign.Center).fontSize(16)
376        // Dotted line
377        Text('DOTTED')
378          .backgroundColor(Color.Pink)
379          .outline({ width: 5, color: 0x317AF7, radius: 10, style: OutlineStyle.DOTTED })
380          .width(120).height(120).textAlign(TextAlign.Center).fontSize(16)
381      }.width('100%').height(150)
382
383      Text('.outline')
384        .backgroundColor(Color.Pink)
385        .fontSize(50)
386        .width(300)
387        .height(300)
388        .outline({
389          width: { left: 3, right: 6, top: 10, bottom: 15 },
390          color: { left: '#e3bbbb', right: Color.Blue, top: Color.Red, bottom: Color.Green },
391          radius: { topLeft: 10, topRight: 20, bottomLeft: 40, bottomRight: 80 },
392          style: {
393            left: OutlineStyle.DOTTED,
394            right: OutlineStyle.DOTTED,
395            top: OutlineStyle.SOLID,
396            bottom: OutlineStyle.DASHED
397          }
398        }).textAlign(TextAlign.Center)
399    }
400  }
401}
402```
403
404![en-us_image_0000001219982706](figures/en-us_image_0000001219982706.png)
405
406### Example 2: Using the LocalizedEdgeColors Type
407
408This example sets the **color** property of the **outline** attribute to the LocalizedEdgeColors type.
409
410```ts
411// xxx.ets
412
413@Entry
414@Component
415struct OutlineExample {
416  build() {
417    Column() {
418      Flex({ justifyContent: FlexAlign.SpaceAround, alignItems: ItemAlign.Center }) {
419        // Dashed line
420        Text('DASHED')
421          .backgroundColor(Color.Pink)
422          .outlineStyle(OutlineStyle.DASHED).outlineWidth(5).outlineColor(0xAFEEEE).outlineRadius(10)
423          .width(120).height(120).textAlign(TextAlign.Center).fontSize(16)
424        // Dotted line
425        Text('DOTTED')
426          .backgroundColor(Color.Pink)
427          .outline({ width: 5, color: 0x317AF7, radius: 10, style: OutlineStyle.DOTTED })
428          .width(120).height(120).textAlign(TextAlign.Center).fontSize(16)
429      }.width('100%').height(150)
430
431      Text('.outline')
432        .backgroundColor(Color.Pink)
433        .fontSize(50)
434        .width(300)
435        .height(300)
436        .outline({
437          width: { left: 3, right: 6, top: 10, bottom: 15 },
438          color: { start: '#e3bbbb', end: Color.Blue, top: Color.Red, bottom: Color.Green },
439          radius: { topLeft: 10, topRight: 20, bottomLeft: 40, bottomRight: 80 },
440          style: {
441            left: OutlineStyle.DOTTED,
442            right: OutlineStyle.DOTTED,
443            top: OutlineStyle.SOLID,
444            bottom: OutlineStyle.DASHED
445          }
446        }).textAlign(TextAlign.Center)
447    }
448  }
449}
450```
451
452The following shows how the example is represented with left-to-right scripts.
453
454![en-us_image_outling_ltr](figures/en-us_image_outling_ltr.png)
455
456The following shows how the example is represented with right-to-left scripts.
457
458![en-us_image_outling_rtl](figures/en-us_image_outling_rtl.png)
459