• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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. For the string type, numeric string values with optional units, for example, **"10"** or **"10fp"**, are supported.
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.<br>Unit: fp|
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. For the string type, numeric string values with optional units, for example, **"10"** or **"10fp"**, are supported. Percentage values are not supported.|
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. When using the string type, numeric string values with optional units, for example, **"10"** or **"10fp"**, are supported.
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 demonstrates how to apply different text styles and configure click events for the **Span** component.
305
306```ts
307// xxx.ets
308@Entry
309@Component
310struct SpanExample {
311  build() {
312    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start }) {
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          .fontFamily('HarmonyOS Sans')
324      }.margin({ top: 12 })
325
326      // Add a line under the text.
327      Text('Text Decoration').fontSize(9).fontColor(0xCCCCCC).margin({ top: 12 })
328      Text() {
329        Span('I am Underline-WAVY-span')
330          .decoration({ type: TextDecorationType.Underline, color: Color.Red, style: TextDecorationStyle.WAVY })
331          .fontSize(12)
332      }
333
334      Text() {
335        Span('I am LineThrough-DOTTED-span')
336          .decoration({ type: TextDecorationType.LineThrough, color: Color.Red, style: TextDecorationStyle.DOTTED })
337          .fontSize(12)
338      }
339
340      Text() {
341        Span('I am Overline-DASHED-span')
342          .decoration({ type: TextDecorationType.Overline, color: Color.Red, style: TextDecorationStyle.DASHED })
343          .fontSize(12)
344      }
345
346      // Set the letter spacing.
347      Text('LetterSpacing').fontSize(9).fontColor(0xCCCCCC).margin({ top: 12 })
348      Text() {
349        Span('span letter spacing')
350          .letterSpacing(0)
351          .fontSize(12)
352      }
353
354      Text() {
355        Span('span letter spacing')
356          .letterSpacing(-2)
357          .fontSize(12)
358      }
359
360      Text() {
361        Span('span letter spacing')
362          .letterSpacing(3)
363          .fontSize(12)
364      }
365
366      // Set the text case.
367      Text('Text Case').fontSize(9).fontColor(0xCCCCCC).margin({ top: 12 })
368      Text() {
369        Span('I am Lower-span').fontSize(12)
370          .textCase(TextCase.LowerCase)
371          .decoration({ type: TextDecorationType.None })
372      }
373
374      Text() {
375        Span('I am Upper-span').fontSize(12)
376          .textCase(TextCase.UpperCase)
377          .decoration({ type: TextDecorationType.None })
378      }
379
380      // Set the text font style.
381      Text('FontStyle').fontSize(9).fontColor(0xCCCCCC).margin({ top: 12 })
382      Text() {
383        Span('I am FontStyle-Normal').fontSize(12)
384          .fontStyle(FontStyle.Normal)
385      }
386
387      Text() {
388        Span('I am FontStyle-Italic').fontSize(12)
389          .fontStyle(FontStyle.Italic)
390      }
391
392      // Set the text font weight.
393      Text('FontWeight').fontSize(9).fontColor(0xCCCCCC).margin({ top: 12 })
394      Text() {
395        Span('I am FontWeight-Lighter').fontSize(12)
396          .fontWeight(FontWeight.Lighter)
397      }
398
399      Text() {
400        Span('I am FontWeight-Bold').fontSize(12)
401          .fontWeight(FontWeight.Bold)
402      }
403
404      // Set the text line height.
405      Text('LineHeight').fontSize(9).fontColor(0xCCCCCC).margin({ top: 12 })
406      Text() {
407        Span('I am lineHeight default\n').fontSize(12)
408          .fontWeight(FontWeight.Lighter)
409        Span('I am lineHeight 30').fontSize(12)
410          .lineHeight(30)
411      }
412      .backgroundColor(Color.Gray)
413
414      // Set the text style.
415      Text('Font').fontSize(9).fontColor(0xCCCCCC).margin({ top: 12 })
416      Text() {
417        Span('span font 12 Bolder Italic')
418          .font({
419            size: 12,
420            weight: FontWeight.Bolder,
421            style: FontStyle.Italic,
422            family: "HarmonyOS Sans"
423          })
424      }
425
426      // Set the click event.
427      Text('span click event').fontSize(9).fontColor(0xCCCCCC).margin({ top: 12 })
428      Text() {
429        Span('Span default ').fontSize(12)
430        Span('Span click')
431          .onClick((event) => {
432            console.log("span onClick")
433          })
434      }
435    }.width('100%').padding({ left: 35, right: 35, top: 35 })
436  }
437}
438```
439
440![Span](figures/span.png)
441
442### Example 2: Setting the Text Shadow
443
444This example demonstrates the effect of setting a shadow for text using the **textShadow** attributes.
445
446``` ts
447// xxx.ets
448@Entry
449@Component
450struct SpanExample {
451  @State textShadows: ShadowOptions | Array<ShadowOptions> = [{
452    radius: 10,
453    color: Color.Red,
454    offsetX: 10,
455    offsetY: 0
456  }, {
457    radius: 10,
458    color: Color.Orange,
459    offsetX: 20,
460    offsetY: 0
461  },
462    {
463      radius: 10,
464      color: Color.Yellow,
465      offsetX: 30,
466      offsetY: 0
467    }, {
468      radius: 10,
469      color: Color.Green,
470      offsetX: 40,
471      offsetY: 0
472    },
473    {
474      radius: 10,
475      color: Color.Blue,
476      offsetX: 100,
477      offsetY: 0
478    }]
479
480  build() {
481    Column({ space: 8 }) {
482      Text() {
483        Span('123456789').fontSize(50).textShadow(this.textShadows).fontColor(Color.Pink)
484      }
485
486      Text() {
487        Span('123456789') // span can inherit text shadow & font size from outer text
488      }.fontSize(50).textShadow(this.textShadows).fontColor(Color.Pink)
489    }
490  }
491}
492```
493![TextshadowExample](figures/text_span_textshadow.png)
494
495### Example 3: Setting the Background Style
496
497This example demonstrates the effect of setting a background style for text using the **textBackgroundStyle** attribute.
498
499``` ts
500// xxx.ets
501@Component
502@Entry
503struct SpanExample {
504  build() {
505    Column() {
506      Text() {
507        Span('   Hello World !   ')
508          .fontSize('20fp')
509          .textBackgroundStyle({ color: "#7F007DFF", radius: "5vp" })
510          .fontColor(Color.White)
511      }
512    }.width('100%').margin({ bottom: '5vp' }).alignItems(HorizontalAlign.Center)
513  }
514}
515```
516![TextBackgroundStyleExample](figures/span_textbackgroundstyle.png)
517
518### Example 4: Setting the Text Baseline Offset
519
520This example demonstrates the effect of setting different baseline offsets for text using the **baselineOffset** attribute.
521
522```ts
523// xxx.ets
524import { LengthUnit, LengthMetrics } from '@kit.ArkUI';
525
526@Entry
527@Component
528struct SpanExample {
529  build() {
530    Row() {
531      Column() {
532        Text() {
533          Span('SpanOne')
534            .fontSize(10)
535            .baselineOffset(new LengthMetrics(20, LengthUnit.VP))
536          Span('SpanTwo')
537            .fontSize(10)
538            .baselineOffset(new LengthMetrics(0, LengthUnit.VP))
539          ImageSpan($r("app.media.sky"))// You are advised to use a custom local image.
540            .width('80px')
541            .baselineOffset(new LengthMetrics(-20, LengthUnit.VP))
542        }
543        .backgroundColor('#7F007DFF')
544      }
545      .width('100%')
546    }
547    .height('100%')
548  }
549}
550```
551
552![SpanBaselineOffset](figures/SpanBaselineOffset.png)
553