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
36The attributes inherit from [BaseSpan](#basespan). Only the [universal text attributes](ts-universal-attributes-text-style.md) are supported.
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### lineHeight<sup>10+</sup>
93
94lineHeight(value: Length)
95
96Sets the line height for the text.
97
98**Atomic service API**: This API can be used in atomic services since API version 11.
99
100**System capability**: SystemCapability.ArkUI.ArkUI.Full
101
102**Parameters**
103
104| Name| Type   | Mandatory| Description |
105| ------ | ------ | ---- | ---- |
106| value  | [Length](ts-types.md#length) | Yes  | Line height of the text.|
107
108### font<sup>10+</sup>
109
110font(value: Font)
111
112Text style, covering the font size, font width, Font family, and font style.
113
114**Atomic service API**: This API can be used in atomic services since API version 11.
115
116**System capability**: SystemCapability.ArkUI.ArkUI.Full
117
118**Parameters**
119
120| Name| Type                    | Mandatory| Description      |
121| ------ | ------------------------ | ---- | ---------- |
122| value  | [Font](ts-types.md#font) | Yes  | Text style.|
123
124### textShadow<sup>11+</sup>
125
126textShadow(value: ShadowOptions | Array&lt;ShadowOptions&gt;)
127
128Text 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.
129
130**Atomic service API**: This API can be used in atomic services since API version 12.
131
132**System capability**: SystemCapability.ArkUI.ArkUI.Full
133
134**Parameters**
135
136| Name| Type| Mandatory| Description|
137| ------ | ----- | ---- | --- |
138| value  | [ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions) \|  Array&lt;[ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions)>| Yes  | Text shadow.|
139
140## Events
141
142Among all the universal events, only the [click event](ts-universal-events-click.md) is supported.
143
144>  **NOTE**
145>
146>  As the **Span** component does not include size information, the **target** attribute of the **ClickEvent** object returned by the click event is invalid.
147
148## BaseSpan
149
150Defines the **BaseSpan** base class, including the common attributes of the span.
151
152**System capability**: SystemCapability.ArkUI.ArkUI.Full
153
154**Atomic service API**: This API can be used in atomic services since API version 12.
155
156### textBackgroundStyle<sup>11+</sup>
157
158textBackgroundStyle(style: TextBackgroundStyle): T
159
160Background 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).
161
162**Atomic service API**: This API can be used in atomic services since API version 12.
163
164**System capability**: SystemCapability.ArkUI.ArkUI.Full
165
166**Parameters**
167
168| Name| Type | Mandatory| Description|
169| ----- | ---- | ---- | ---- |
170| style  | [TextBackgroundStyle](#textbackgroundstyle11) | Yes  | Background style.<br>Default value:<br>{<br>  color: Color.Transparent,<br>  radius: 0<br>} |
171
172**Return value**
173
174| Type                                      | Description     |
175| ---------------------------------------- | ------- |
176| T | Attributes of the span.|
177
178### baselineOffset<sup>12+</sup>
179
180baselineOffset(value: LengthMetrics): T
181
182Sets the offset of the baseline. This attribute coexists with the **baselineOffset** attribute of the parent component.
183
184**Atomic service API**: This API can be used in atomic services since API version 12.
185
186**System capability**: SystemCapability.ArkUI.ArkUI.Full
187
188**Parameters**
189
190| Name| Type| Mandatory| Description |
191| ----- | ---- | ---- | ---- |
192| 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.|
193
194**Return value**
195
196| Type                                      | Description     |
197| ---------------------------------------- | ------- |
198| T | Attributes of the span.|
199
200## TextBackgroundStyle<sup>11+</sup>
201
202**Atomic service API**: This API can be used in atomic services since API version 12.
203
204**System capability**: SystemCapability.ArkUI.ArkUI.Full
205
206| Name  | Type    | Mandatory| Description        |
207| ------ | ------- | ---- | ------------ |
208| color  | [ResourceColor](ts-types.md#resourcecolor)                                  | No  | Text background color.|
209| radius | [Dimension](ts-types.md#dimension10) \| [BorderRadiuses](ts-universal-attributes-border.md#borderradiuses9) | No  | Rounded corner radius of the text background.|
210
211## Example
212### Example 1
213
214This example shows how to set the **decoration**, **letterSpacing**, and **textCase** attributes.
215
216```ts
217// xxx.ets
218@Entry
219@Component
220struct SpanExample {
221  build() {
222    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start, justifyContent: FlexAlign.SpaceBetween }) {
223      Text('Basic Usage').fontSize(9).fontColor(0xCCCCCC)
224      Text() {
225        Span('In Line')
226        Span(' Component')
227        Span(' !')
228      }
229
230      Text() {
231        Span('This is the Span component').fontSize(12).textCase(TextCase.Normal)
232          .decoration({ type: TextDecorationType.None, color: Color.Red })
233      }
234
235      // Add a line under the text.
236      Text('Text Decoration').fontSize(9).fontColor(0xCCCCCC)
237      Text() {
238        Span('I am Underline-WAVY-span').decoration({ type: TextDecorationType.Underline, color: Color.Red, style: TextDecorationStyle.WAVY }).fontSize(12)
239      }
240
241      Text() {
242        Span('I am LineThrough-DOTTED-span')
243          .decoration({ type: TextDecorationType.LineThrough, color: Color.Red, style: TextDecorationStyle.DOTTED })
244          .fontSize(12)
245      }
246
247      Text() {
248        Span('I am Overline-DASHED-span').decoration({ type: TextDecorationType.Overline, color: Color.Red, style: TextDecorationStyle.DASHED }).fontSize(12)
249      }
250
251      // Set the letter spacing.
252      Text('LetterSpacing').fontSize(9).fontColor(0xCCCCCC)
253      Text() {
254        Span('span letter spacing')
255          .letterSpacing(0)
256          .fontSize(12)
257      }
258
259      Text() {
260        Span('span letter spacing')
261          .letterSpacing(-2)
262          .fontSize(12)
263      }
264
265      Text() {
266        Span('span letter spacing')
267          .letterSpacing(3)
268          .fontSize(12)
269      }
270
271
272      // Set the text case.
273      Text('Text Case').fontSize(9).fontColor(0xCCCCCC)
274      Text() {
275        Span('I am Lower-span').fontSize(12)
276          .textCase(TextCase.LowerCase)
277          .decoration({ type: TextDecorationType.None })
278      }
279
280      Text() {
281        Span('I am Upper-span').fontSize(12)
282          .textCase(TextCase.UpperCase)
283          .decoration({ type: TextDecorationType.None })
284      }
285    }.width('100%').height(250).padding({ left: 35, right: 35, top: 35 })
286  }
287}
288```
289
290![Span](figures/span.png)
291
292### Example 2
293``` ts
294@Entry
295@Component
296struct TextSpanExample {
297  @State textShadows : ShadowOptions | Array<ShadowOptions> = [{ radius: 10, color: Color.Red, offsetX: 10, offsetY: 0 },{ radius: 10, color: Color.Black, offsetX: 20, offsetY: 0 },
298      { radius: 10, color: Color.Brown, offsetX: 30, offsetY: 0 },{ radius: 10, color: Color.Green, offsetX: 40, offsetY: 0 },
299      { radius: 10, color: Color.Yellow, offsetX: 100, offsetY: 0 }]
300  build() {
301    Column({ space: 8 }) {
302      Text() {
303        Span('123456789').fontSize(50).textShadow(this.textShadows)
304      }
305      Text() {
306        Span('123456789') // span can inherit text shadow & font size from outer text
307      }.fontSize(50).textShadow(this.textShadows)
308    }
309  }
310}
311```
312![TextshadowExample](figures/text_span_textshadow.png)
313
314### Example 3
315``` ts
316// xxx.ets
317@Component
318@Entry
319struct Index {
320  build() {
321    Column() {
322      Text() {
323        Span('   Hello World !   ')
324          .fontSize('20fp')
325          .textBackgroundStyle({color: "#7F007DFF", radius: "5vp"})
326          .fontColor(Color.White)
327      }
328    }.width('100%').margin({bottom: '5vp'}).alignItems(HorizontalAlign.Center)
329  }
330}
331```
332![TextBackgroundStyleExample](figures/span_textbackgroundstyle.png)
333
334### Example 4
335
336This example shows how to set the offset of the span baseline.
337
338```ts
339import { LengthUnit, LengthMetrics } from '@kit.ArkUI';
340
341@Entry
342@Component
343struct Index {
344
345  build() {
346    Row() {
347      Column() {
348        Text(){
349          Span('word1')
350            .baselineOffset(new LengthMetrics(20,LengthUnit.VP))
351          Span('word2')
352            .baselineOffset(new LengthMetrics(0,LengthUnit.VP))
353          ImageSpan($r("app.media.icon"))
354            .width('45px')
355            .baselineOffset(new LengthMetrics(-20,LengthUnit.VP))
356        }
357        .backgroundColor(Color.Gray)
358      }
359      .width('100%')
360    }
361    .height('100%')
362  }
363}
364```
365
366![SpanBaselineOffset](figures/SpanBaselineOffset.png)
367