• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Text
2
3The **\<Text>** component is used to display a piece of textual information.
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
10## Child Components
11
12This component can contain the [\<Span>](ts-basic-components-span.md) child component.
13
14
15## APIs
16
17Text(content?: string | Resource)
18
19Since API version 9, this API is supported in ArkTS widgets.
20
21**Parameters**
22
23| Name| Type| Mandatory| Description|
24| -------- | -------- | -------- | -------- |
25| content | string \| [Resource](ts-types.md#resource) | No| Text content. The content and style set for the **\<Text>** component do not take effect when it contains the **\<Span>** child component.<br>Default value: **' '**|
26
27## Attributes
28
29In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported.
30
31| Name                      | Type                           | Description                                              |
32| ----------------------- | ----------------------------------- | ------------------------------------------- |
33| textAlign               | [TextAlign](ts-appendix-enums.md#textalign) | Horizontal alignment mode of the text.<br>Default value: **TextAlign.Start**<br>**NOTE**<br>The text takes up the full width of the **\<Text>** component. To set the vertical alignment for the text, use the [align](ts-universal-attributes-location.md) attribute.<br>Since API version 9, this API is supported in ArkTS widgets.|
34| textOverflow            | {overflow: [TextOverflow](ts-appendix-enums.md#textoverflow)} | Display mode when the text is too long.<br>Default value: **{overflow: TextOverflow.Clip}**<br>**NOTE**<br/>Text is clipped at the transition between words. To clip text in the middle of a word, add **\u200B** between characters.<br>This attribute must be used with `maxLines` to take effect.<br>Since API version 9, this API is supported in ArkTS widgets.|
35| maxLines                | number | Maximum number of lines in the text.<br>Default value: **Infinity**<br>**NOTE**<br/>By default, text is automatically folded. If this attribute is specified, the text will not exceed the specified number of lines. If there is extra text, you can use **textOverflow** to specify how it is displayed.<br>Since API version 9, this API is supported in ArkTS widgets.|
36| lineHeight              | string \| number \| [Resource](ts-types.md#resource)  | Text line height. If the value is less than or equal to **0**, the line height is not limited and the font size is adaptive. If the value of the number type, the unit fp is used.<br>Since API version 9, this API is supported in ArkTS widgets.|
37| decoration              | {<br>type: [TextDecorationType](ts-appendix-enums.md#textdecorationtype),<br>color?: [ResourceColor](ts-types.md#resourcecolor)<br>} | Style and color of the text decorative line.<br>Default value: {<br>type: TextDecorationType.None,<br>color: Color.Black<br>} <br>Since API version 9, this API is supported in ArkTS widgets.|
38| baselineOffset          | number \| string | Baseline offset of the text. The default value is **0**.<br>Since API version 9, this API is supported in ArkTS widgets.<br>**NOTE**<br/><br>If this attribute is set to a percentage, the default value is used.|
39| letterSpacing           | number \| string | Letter spacing.<br>Since API version 9, this API is supported in ArkTS widgets.<br>**NOTE**<br/><br>If this attribute is set to a percentage, the default value is used.|
40| minFontSize             | number \| string \| [Resource](ts-types.md#resource)      | Minimum font size.<br>For the setting to take effect, this attribute must be used together with **maxFontSize**, **maxLines**, or layout constraint settings.<br>Since API version 9, this API is supported in ArkTS widgets.                              |
41| maxFontSize             | number \| string \| [Resource](ts-types.md#resource)      | Maximum font size.<br>For the setting to take effect, this attribute must be used together with **minFontSize**, **maxLines**, or layout constraint settings.<br>Since API version 9, this API is supported in ArkTS widgets.                               |
42| textCase                | [TextCase](ts-appendix-enums.md#textcase) | Text case.<br>Default value: **TextCase.Normal**<br>Since API version 9, this API is supported in ArkTS widgets.|
43| copyOption<sup>9+</sup> | [CopyOptions](ts-appendix-enums.md#copyoptions9) | Whether copy and paste is allowed.<br>Default value: **CopyOptions.None**<br>This API is supported in ArkTS widgets.|
44
45>  **NOTE**
46>
47>  The **\<Text>** component cannot contain both the text and the child component **\<Span>**. If both of them exist, only the content in **\<Span>** is displayed.
48
49## Events
50
51The [universal events](ts-universal-events-click.md) are supported.
52
53
54## Example
55
56### Example 1
57Examples of using **textAlign**, **textOverflow**, **maxLines**, and **lineHeight**
58```ts
59// xxx.ets
60@Entry
61@Component
62struct TextExample1 {
63  build() {
64    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start, justifyContent: FlexAlign.SpaceBetween }) {
65      // Set the horizontal alignment mode for the text.
66      // Single-line text
67      Text('textAlign').fontSize(9).fontColor(0xCCCCCC)
68      Text('TextAlign set to Center.')
69        .textAlign(TextAlign.Center)
70        .fontSize(12)
71        .border({ width: 1 })
72        .padding(10)
73        .width('100%')
74      Text('TextAlign set to Start.')
75        .textAlign(TextAlign.Start)
76        .fontSize(12)
77        .border({ width: 1 })
78        .padding(10)
79        .width('100%')
80      Text('TextAlign set to End.')
81        .textAlign(TextAlign.End)
82        .fontSize(12)
83        .border({ width: 1 })
84        .padding(10)
85        .width('100%')
86
87      // Multi-line text
88      Text('This is the text content with textAlign set to Center.')
89        .textAlign(TextAlign.Center)
90        .fontSize(12)
91        .border({ width: 1 })
92        .padding(10)
93        .width('100%')
94      Text('This is the text content with textAlign set to Start.')
95        .textAlign(TextAlign.Start)
96        .fontSize(12)
97        .border({ width: 1 })
98        .padding(10)
99        .width('100%')
100      Text('This is the text content with textAlign set to End.')
101        .textAlign(TextAlign.End)
102        .fontSize(12)
103        .border({ width: 1 })
104        .padding(10)
105        .width('100%')
106
107
108      // Set the display mode when the text is too long.
109      Text('TextOverflow+maxLines').fontSize(9).fontColor(0xCCCCCC)
110      // Clip the text when the value of maxLines is exceeded.
111      Text('This is the setting of textOverflow to Clip text content This is the setting of textOverflow to None text content. This is the setting of textOverflow to Clip text content This is the setting of textOverflow to None text content.')
112        .textOverflow({ overflow: TextOverflow.None })
113        .maxLines(1)
114        .fontSize(12)
115        .border({ width: 1 })
116        .padding(10)
117
118      // Show an ellipsis (...) when the value of maxLines is exceeded.
119      Text('This is set textOverflow to Ellipsis text content This is set textOverflow to Ellipsis text content.'.split('')
120        .join('\u200B'))
121        .textOverflow({ overflow: TextOverflow.Ellipsis })
122        .maxLines(1)
123        .fontSize(12)
124        .border({ width: 1 })
125        .padding(10)
126
127      Text('lineHeight').fontSize(9).fontColor(0xCCCCCC)
128      Text('This is the text with the line height set. This is the text with the line height set.')
129        .fontSize(12).border({ width: 1 }).padding(10)
130      Text('This is the text with the line height set. This is the text with the line height set.')
131        .fontSize(12).border({ width: 1 }).padding(10)
132        .lineHeight(20)
133    }.height(600).width(350).padding({ left: 35, right: 35, top: 35 })
134  }
135}
136```
137![textExp1](figures/textExp1.png)
138
139### Example 2
140Example of using **decoration**, **baselineOffset**, **letterSpacing**, and **textCase**:
141```ts
142@Entry
143@Component
144struct TextExample2 {
145  build() {
146    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start, justifyContent: FlexAlign.SpaceBetween }) {
147      Text('decoration').fontSize(9).fontColor(0xCCCCCC)
148      Text('This is the text content with the decoration set to LineThrough and the color set to Red.')
149        .decoration({
150          type: TextDecorationType.LineThrough,
151          color: Color.Red
152        })
153        .fontSize(12)
154        .border({ width: 1 })
155        .padding(10)
156        .width('100%')
157
158
159      Text('This is the text content with the decoration set to Overline and the color set to Red.')
160        .decoration({
161          type: TextDecorationType.Overline,
162          color: Color.Red
163        })
164        .fontSize(12)
165        .border({ width: 1 })
166        .padding(10)
167        .width('100%')
168
169
170      Text('This is the text content with the decoration set to Underline and the color set to Red.')
171        .decoration({
172          type: TextDecorationType.Underline,
173          color: Color.Red
174        })
175        .fontSize(12)
176        .border({ width: 1 })
177        .padding(10)
178        .width('100%')
179
180      // Set the text baseline offset.
181      Text('baselineOffset').fontSize(9).fontColor(0xCCCCCC)
182      Text('This is the text content with baselineOffset 0.')
183        .baselineOffset(0)
184        .fontSize(12)
185        .border({ width: 1 })
186        .padding(10)
187        .width('100%')
188      Text('This is the text content with baselineOffset 30.')
189        .baselineOffset(30)
190        .fontSize(12)
191        .border({ width: 1 })
192        .padding(10)
193        .width('100%')
194      Text('This is the text content with baselineOffset -20.')
195        .baselineOffset(-20)
196        .fontSize(12)
197        .border({ width: 1 })
198        .padding(10)
199        .width('100%')
200
201      // Set the letter spacing.
202      Text('letterSpacing').fontSize(9).fontColor(0xCCCCCC)
203      Text('This is the text content with letterSpacing 0.')
204        .letterSpacing(0)
205        .fontSize(12)
206        .border({ width: 1 })
207        .padding(10)
208        .width('100%')
209      Text('This is the text content with letterSpacing 3.')
210        .letterSpacing(3)
211        .fontSize(12)
212        .border({ width: 1 })
213        .padding(10)
214        .width('100%')
215      Text('This is the text content with letterSpacing -1.')
216        .letterSpacing(-1)
217        .fontSize(12)
218        .border({ width: 1 })
219        .padding(10)
220        .width('100%')
221
222      Text('textCase').fontSize(9).fontColor(0xCCCCCC)
223      Text('This is the text content with textCase set to Normal.')
224        .textCase(TextCase.Normal)
225        .fontSize(12)
226        .border({ width: 1 })
227        .padding(10)
228        .width('100%')
229      // Display the text in lowercase.
230      Text('This is the text content with textCase set to LowerCase.')
231        .textCase(TextCase.LowerCase)
232        .fontSize(12)
233        .border({ width: 1 })
234        .padding(10)
235        .width('100%')
236      // Display the text in uppercase.
237      Text('This is the text content with textCase set to UpperCase.')
238        .textCase(TextCase.UpperCase)
239        .fontSize(12).border({ width: 1 }).padding(10)
240
241    }.height(700).width(350).padding({ left: 35, right: 35, top: 35 })
242  }
243}
244```
245![textExp1](figures/textExp2.png)
246