1# Span
2
3As a child of the [Text](ts-basic-components-text.md) and [ContainerSpan](ts-basic-components-containerspan.md) components, the Span component is used to display inline text.
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>  Since API version 10, this component can inherit the attributes of the **Text** parent component. That is, if no attribute is set for this component, it inherits the attributes (if set) of its parent component. Only the following attributes can be inherited: **fontColor**, **fontSize**, **fontStyle**, **fontWeight**, **decoration**, **letterSpacing**, **textCase**, **fontfamily**, and **textShadow**.
10
11
12## Child Components
13
14Not supported
15
16
17## APIs
18
19Span(value: string | Resource)
20
21**Widget capability**: This API can be used in ArkTS widgets since API version 9.
22
23**Atomic service API**: This API can be used in atomic services since API version 11.
24
25**System capability**: SystemCapability.ArkUI.ArkUI.Full
26
27**Parameters**
28
29| Name| Type| Mandatory| Description|
30| -------- | -------- | -------- | -------- |
31| value | string \| [Resource](ts-types.md#resource) | Yes| Plain text.|
32
33
34## Attributes
35
36Inherited from [BaseSpan](#basespan).
37
38### decoration
39
40decoration(value: DecorationStyleInterface)
41
42Style and color of the text decorative line.
43
44**Widget capability**: This API can be used in ArkTS widgets since API version 9.
45
46**Atomic service API**: This API can be used in atomic services since API version 11.
47
48**System capability**: SystemCapability.ArkUI.ArkUI.Full
49
50**Parameters**
51
52| Name| Type     | Mandatory| Description    |
53| ------ | -------- | ---- | -------------- |
54| value  | [DecorationStyleInterface<sup>12+</sup>](ts-universal-styled-string.md#decorationstyleinterface) | Yes  | Style of the text decorative line.<br>Default value:<br>{<br> type: TextDecorationType.None,<br> color: Color.Black,<br> style: TextDecorationStyle.SOLID <br>}<br>**NOTE**<br>The **style** parameter cannot be used in widgets.|
55
56### letterSpacing
57
58letterSpacing(value: number | string)
59
60Letter spacing. A negative value tightens the spacing; a positive value loosens the spacing, and the letters are spread farther apart with the value.
61
62**Widget capability**: This API can be used in ArkTS widgets since API version 9.
63
64**Atomic service API**: This API can be used in atomic services since API version 11.
65
66**System capability**: SystemCapability.ArkUI.ArkUI.Full
67
68**Parameters**
69
70| Name| Type    | Mandatory|  Description  |
71| ------ | ------- | ---- | -------------- |
72| value  | number \| string | Yes  | Letter spacing.|
73
74### textCase
75
76textCase(value: TextCase)
77
78Text case.
79
80**Widget capability**: This API can be used in ArkTS widgets since API version 9.
81
82**Atomic service API**: This API can be used in atomic services since API version 11.
83
84**System capability**: SystemCapability.ArkUI.ArkUI.Full
85
86**Parameters**
87
88| Name| Type  | Mandatory| Description  |
89| ------ | ------- | ---- | ------- |
90| value  | [TextCase](ts-appendix-enums.md#textcase) | Yes  | Text case.<br>Default value: **TextCase.Normal**|
91
92### fontColor
93
94fontColor(value: ResourceColor)
95
96Sets the font color.
97
98**Widget capability**: This API can be used in ArkTS widgets since API version 9.
99
100**Atomic service API**: This API can be used in atomic services since API version 11.
101
102**System capability**: SystemCapability.ArkUI.ArkUI.Full
103
104**Parameters**
105
106| Name| Type                                      | Mandatory| Description      |
107| ------ | ------------------------------------------ | ---- | ---------- |
108| value  | [ResourceColor](ts-types.md#resourcecolor) | Yes  | Font color.|
109
110### fontSize
111
112fontSize(value: number | string | Resource)
113
114Sets the font size.
115
116**Widget capability**: This API can be used in ArkTS widgets since API version 9.
117
118**Atomic service API**: This API can be used in atomic services since API version 11.
119
120**System capability**: SystemCapability.ArkUI.ArkUI.Full
121
122**Parameters**
123
124| Name| Type                                                        | Mandatory| Description                                                        |
125| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
126| value  | number \|  string\| [Resource](ts-types.md#resource) | Yes  | Font size. If **fontSize** is of the number type, the unit fp is used. The default font size is 16 fp. The value cannot be a percentage.|
127
128### fontStyle
129
130fontStyle(value: FontStyle)
131
132Sets the font style.
133
134**Widget capability**: This API can be used in ArkTS widgets since API version 9.
135
136**Atomic service API**: This API can be used in atomic services since API version 11.
137
138**System capability**: SystemCapability.ArkUI.ArkUI.Full
139
140**Parameters**
141
142| Name| Type                                       | Mandatory| Description                                   |
143| ------ | ------------------------------------------- | ---- | --------------------------------------- |
144| value  | [FontStyle](ts-appendix-enums.md#fontstyle) | Yes  | Font style.<br>Default value: **FontStyle.Normal**|
145
146### fontWeight
147
148fontWeight(value: number | FontWeight | string)
149
150Sets the font weight. If the value is too large, the text may be clipped depending on the font.
151
152**Widget capability**: This API can be used in ArkTS widgets since API version 9.
153
154**Atomic service API**: This API can be used in atomic services since API version 11.
155
156**System capability**: SystemCapability.ArkUI.ArkUI.Full
157
158**Parameters**
159
160| Name| Type                                                        | Mandatory| Description                                                        |
161| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
162| value  | number \| [FontWeight](ts-appendix-enums.md#fontweight) \| string | Yes  | Font weight. For the number type, the value range is [100, 900], at an interval of 100. The default value is **400**. A larger value indicates a heavier font weight. For the string type, only strings of the number type are supported, for example, **400**, **"bold"**, **"bolder"**, **"lighter"**, **"regular"**, and **"medium"**, which correspond to the enumerated values in **FontWeight**.<br>Default value: **FontWeight.Normal**|
163
164### fontFamily
165
166fontFamily(value: string | Resource)
167
168Sets the font family.
169
170**Widget capability**: This API can be used in ArkTS widgets since API version 9.
171
172**Atomic service API**: This API can be used in atomic services since API version 11.
173
174**System capability**: SystemCapability.ArkUI.ArkUI.Full
175
176**Parameters**
177
178| Name| Type                                                | Mandatory| Description                                                        |
179| ------ | ---------------------------------------------------- | ---- | ------------------------------------------------------------ |
180| value  | string \| [Resource](ts-types.md#resource) | Yes  | Font family. Default font: **'HarmonyOS Sans'**<br>The 'HarmonyOS Sans' font and [registered custom fonts](../js-apis-font.md) are supported for applications.<br>Only the 'HarmonyOS Sans' font is supported for widgets.|
181
182### lineHeight<sup>10+</sup>
183
184lineHeight(value: Length)
185
186Sets the line height for the text.
187
188**Atomic service API**: This API can be used in atomic services since API version 11.
189
190**System capability**: SystemCapability.ArkUI.ArkUI.Full
191
192**Parameters**
193
194| Name| Type   | Mandatory| Description |
195| ------ | ------ | ---- | ---- |
196| value  | [Length](ts-types.md#length) | Yes  | Line height of the text.|
197
198### font<sup>10+</sup>
199
200font(value: Font)
201
202Sets the text style, covering the font size, font width, Font family, and font style.
203
204**Atomic service API**: This API can be used in atomic services since API version 11.
205
206**System capability**: SystemCapability.ArkUI.ArkUI.Full
207
208**Parameters**
209
210| Name| Type                    | Mandatory| Description      |
211| ------ | ------------------------ | ---- | ---------- |
212| value  | [Font](ts-types.md#font) | Yes  | Text style.|
213
214### textShadow<sup>11+</sup>
215
216textShadow(value: ShadowOptions | Array&lt;ShadowOptions&gt;)
217
218Text shadow. It supports input parameters in an array to implement multiple text shadows. This API does not work with the **fill** attribute or coloring strategy.
219
220**Atomic service API**: This API can be used in atomic services since API version 12.
221
222**System capability**: SystemCapability.ArkUI.ArkUI.Full
223
224**Parameters**
225
226| Name| Type| Mandatory| Description|
227| ------ | ----- | ---- | --- |
228| value  | [ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions) \|  Array&lt;[ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions)>| Yes  | Text shadow.|
229
230## Events
231
232Among all the universal events, only the [click event](ts-universal-events-click.md) is supported.
233
234>  **NOTE**
235>
236>  As the **Span** component does not include size information, the **target** attribute of the **ClickEvent** object returned by the click event is invalid.
237
238## BaseSpan
239
240Defines the **BaseSpan** base class, including the common attributes of the span.
241
242**System capability**: SystemCapability.ArkUI.ArkUI.Full
243
244**Atomic service API**: This API can be used in atomic services since API version 12.
245
246### textBackgroundStyle<sup>11+</sup>
247
248textBackgroundStyle(style: TextBackgroundStyle): T
249
250Background style. This attribute prioritizes the value separately set for the component. If it is not set, the component can inherit the settings from its parent [ContainerSpan](ts-basic-components-containerspan.md).
251
252**Atomic service API**: This API can be used in atomic services since API version 12.
253
254**System capability**: SystemCapability.ArkUI.ArkUI.Full
255
256**Parameters**
257
258| Name| Type | Mandatory| Description|
259| ----- | ---- | ---- | ---- |
260| style  | [TextBackgroundStyle](#textbackgroundstyle11) | Yes  | Background style.<br>Default value:<br>{<br>  color: Color.Transparent,<br>  radius: 0<br>} |
261
262**Return value**
263
264| Type                                      | Description     |
265| ---------------------------------------- | ------- |
266| T | Attributes of the span.|
267
268### baselineOffset<sup>12+</sup>
269
270baselineOffset(value: LengthMetrics): T
271
272Sets the offset of the baseline. This attribute coexists with the **baselineOffset** attribute of the parent component.
273
274**Atomic service API**: This API can be used in atomic services since API version 12.
275
276**System capability**: SystemCapability.ArkUI.ArkUI.Full
277
278**Parameters**
279
280| Name| Type| Mandatory| Description |
281| ----- | ---- | ---- | ---- |
282| value  | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) | Yes  | Offset of the baseline. If the value specified is a percentage, the default value is used.<br>A positive number is offset upwards, and a negative number is offset downwards.<br>Default value: **0**<br>In an image span, setting this parameter to a non-zero value will cause **verticalAlign** to become ineffective.|
283
284**Return value**
285
286| Type                                      | Description     |
287| ---------------------------------------- | ------- |
288| T | Attributes of the span.|
289
290## TextBackgroundStyle<sup>11+</sup>
291
292**Atomic service API**: This API can be used in atomic services since API version 12.
293
294**System capability**: SystemCapability.ArkUI.ArkUI.Full
295
296| Name  | Type    | Mandatory| Description        |
297| ------ | ------- | ---- | ------------ |
298| color  | [ResourceColor](ts-types.md#resourcecolor)                                  | No  | Text background color.|
299| radius | [Dimension](ts-types.md#dimension10) \| [BorderRadiuses](ts-universal-attributes-border.md#borderradiuses9) | No  | Rounded corner radius of the text background.|
300
301## Example
302### Example 1: Setting the Text Style
303
304This example showcases various text styles by using the **decoration**, **letterSpacing**, and **textCase** attributes.
305
306```ts
307// xxx.ets
308@Entry
309@Component
310struct SpanExample {
311  build() {
312    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start, justifyContent: FlexAlign.SpaceBetween }) {
313      Text('Basic Usage').fontSize(9).fontColor(0xCCCCCC)
314      Text() {
315        Span('In Line')
316        Span(' Component')
317        Span(' !')
318      }
319
320      Text() {
321        Span('This is the Span component').fontSize(12).textCase(TextCase.Normal)
322          .decoration({ type: TextDecorationType.None, color: Color.Red })
323      }
324
325      // Add a line under the text.
326      Text('Text Decoration').fontSize(9).fontColor(0xCCCCCC)
327      Text() {
328        Span('I am Underline-WAVY-span').decoration({ type: TextDecorationType.Underline, color: Color.Red, style: TextDecorationStyle.WAVY }).fontSize(12)
329      }
330
331      Text() {
332        Span('I am LineThrough-DOTTED-span')
333          .decoration({ type: TextDecorationType.LineThrough, color: Color.Red, style: TextDecorationStyle.DOTTED })
334          .fontSize(12)
335      }
336
337      Text() {
338        Span('I am Overline-DASHED-span').decoration({ type: TextDecorationType.Overline, color: Color.Red, style: TextDecorationStyle.DASHED }).fontSize(12)
339      }
340
341      // Set the letter spacing.
342      Text('LetterSpacing').fontSize(9).fontColor(0xCCCCCC)
343      Text() {
344        Span('span letter spacing')
345          .letterSpacing(0)
346          .fontSize(12)
347      }
348
349      Text() {
350        Span('span letter spacing')
351          .letterSpacing(-2)
352          .fontSize(12)
353      }
354
355      Text() {
356        Span('span letter spacing')
357          .letterSpacing(3)
358          .fontSize(12)
359      }
360
361
362      // Set the text case.
363      Text('Text Case').fontSize(9).fontColor(0xCCCCCC)
364      Text() {
365        Span('I am Lower-span').fontSize(12)
366          .textCase(TextCase.LowerCase)
367          .decoration({ type: TextDecorationType.None })
368      }
369
370      Text() {
371        Span('I am Upper-span').fontSize(12)
372          .textCase(TextCase.UpperCase)
373          .decoration({ type: TextDecorationType.None })
374      }
375    }.width('100%').height(250).padding({ left: 35, right: 35, top: 35 })
376  }
377}
378```
379
380![Span](figures/span.png)
381
382### Example 2: Setting the Text Shadow
383
384This example demonstrates the effect of setting a shadow for text using the **textShadow** attributes.
385
386``` ts
387// xxx.ets
388@Entry
389@Component
390struct SpanExample {
391  @State textShadows : ShadowOptions | Array<ShadowOptions> = [{ radius: 10, color: Color.Red, offsetX: 10, offsetY: 0 },{ radius: 10, color: Color.Black, offsetX: 20, offsetY: 0 },
392      { radius: 10, color: Color.Brown, offsetX: 30, offsetY: 0 },{ radius: 10, color: Color.Green, offsetX: 40, offsetY: 0 },
393      { radius: 10, color: Color.Yellow, offsetX: 100, offsetY: 0 }]
394
395  build() {
396    Column({ space: 8 }) {
397      Text() {
398        Span('123456789').fontSize(50).textShadow(this.textShadows)
399      }
400      Text() {
401        Span('123456789') // span can inherit text shadow & font size from outer text
402      }.fontSize(50).textShadow(this.textShadows)
403    }
404  }
405}
406```
407![TextshadowExample](figures/text_span_textshadow.png)
408
409### Example 3: Setting the Background Style
410
411This example demonstrates the effect of setting a background style for text using the **textBackgroundStyle** attribute.
412
413``` ts
414// xxx.ets
415@Component
416@Entry
417struct SpanExample {
418  build() {
419    Column() {
420      Text() {
421        Span('   Hello World !   ')
422          .fontSize('20fp')
423          .textBackgroundStyle({color: "#7F007DFF", radius: "5vp"})
424          .fontColor(Color.White)
425      }
426    }.width('100%').margin({bottom: '5vp'}).alignItems(HorizontalAlign.Center)
427  }
428}
429```
430![TextBackgroundStyleExample](figures/span_textbackgroundstyle.png)
431
432### Example 4: Setting the Text Baseline Offset
433
434This example demonstrates the effect of setting different baseline offsets for text using the **baselineOffset** attribute.
435
436```ts
437import { LengthUnit, LengthMetrics } from '@kit.ArkUI';
438
439@Entry
440@Component
441struct SpanExample {
442  build() {
443    Row() {
444      Column() {
445        Text(){
446          Span('word1')
447            .baselineOffset(new LengthMetrics(20,LengthUnit.VP))
448          Span('word2')
449            .baselineOffset(new LengthMetrics(0,LengthUnit.VP))
450          ImageSpan($r("app.media.icon"))
451            .width('45px')
452            .baselineOffset(new LengthMetrics(-20,LengthUnit.VP))
453        }
454        .backgroundColor(Color.Gray)
455      }
456      .width('100%')
457    }
458    .height('100%')
459  }
460}
461```
462
463![SpanBaselineOffset](figures/SpanBaselineOffset.png)
464