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)> and \<[ImageSpan](ts-basic-components-imagespan.md)> child components. 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) and [universal text attributes](ts-universal-attributes-text-style.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 vertical alignment for the text, use the [align](ts-universal-attributes-location.md) attribute. The **align** attribute alone does not control the horizontal position of the text. In other words, **Alignment.TopStart**, **Alignment.Top**, and **Alignment.TopEnd** produce the same effect, top-aligning the text; **Alignment.Start**, **Alignment.Center**, and **Alignment.End** produce the same effect, centered-aligning the text vertically; **Alignment.BottomStart**, **Alignment.Bottom**, and **Alignment.BottomEnd** produce the same effect, bottom-aligning the text. Yet, it can work with the **textAlign** attribute to jointly determine the horizontal position of the text.<br>When **textAlign** is set to **TextAlign.JUSTIFY**, the text in the last line is horizontally aligned with the start edge.<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>If **overflow** is set to **TextOverflow.None**, **TextOverflow.Clip**, or **TextOverflow.Ellipsis**, this attribute must be used with **maxLines** for the settings to take effect. **TextOverflow.None** produces the same effect as **TextOverflow.Clip**.<br>If **overflow** is set to **TextOverflow.MARQUEE**, the text scrolls in a line, and neither **maxLines** nor **copyOption** takes effect. In this case, the **\<ImageSpan>** component is not supported, and **textAlign** takes effect only when the text is not scrollable.<br>Since API version 9, this API is supported in ArkTS widgets.| 35| maxLines | number | Maximum number of lines in the text.<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/>If this attribute is set to a percentage, the default value is used.<br> If this attribute is set to a negative value, the text is compressed. A negative value too large may result in the text being compressed to 0 and no content being displayed.| 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** and **maxLines**, or layout constraint settings. It has no effect on child components.<br>When the adaptive font size is used, the **fontSize** settings do not take effect.<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** and **maxLines**, or layout constraint settings. It has no effect on child components.<br>When the adaptive font size is used, the **fontSize** settings do not take effect.<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.<br>**NOTE**<br/>When this attribute is set to **CopyOptions.InApp** or **CopyOptions.LocalDevice**, a long press on the text will display a context menu that offers the copy and select-all options. | 44| draggable | boolean | Drag effect of the selected text.<br>This attribute cannot be used with the [onDragStart](ts-universal-events-drag-drop.md) event.<br>It must be used together with **copyOption**. When it is set to **true** and **copyOptions** is set to **CopyOptions.InApp** or **CopyOptions.LocalDevice**, the selected text can be dragged and copied to the text box.<br>Default value: **false**<br>**NOTE**<br/><br>This API is supported since API version 9.| 45| textShadow<sup>10+</sup> | [ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions) | Text shadow.| 46| heightAdaptivePolicy<sup>10+</sup> | [TextHeightAdaptivePolicy](ts-appendix-enums.md#textheightadaptivepolicy10) | How the adaptive height is determined for the text.<br>Default value: **TextHeightAdaptivePolicy.MAX_LINES_FIRST**<br>**NOTE**<br/><br>When this attribute is set to **TextHeightAdaptivePolicy.MAX_LINES_FIRST**, the **maxLines** attribute takes precedence for adjusting the text height. If the **maxLines** setting results in a layout beyond the layout constraints, the text will shrink to a font size between `minFontSize` and `maxFontSize` to allow for more content to be shown.<br>When this attribute is set to **TextHeightAdaptivePolicy.MIN_FONT_SIZE_FIRST**, the **minFontSize** attribute takes precedence for adjusting the text height. If the text can fit in one line with the **minFontSize** setting, the text will enlarge to the largest possible font size between **minFontSize** and **maxFontSize**.<br>When this attribute is set to **TextHeightAdaptivePolicy.LAYOUT_CONSTRAINT_FIRST**, the layout constraints take precedence for adjusting the text height. If the resultant layout is beyond the layout constraints, the text will shrink to a font size between **minFontSize** and **maxFontSize** to respect the layout constraints. If the layout still exceeds the layout constraints after the font size is reduced to **minFontSize**, the lines that exceed the layout constraints are deleted.| 47| textIndent<sup>10+</sup> | number \| string | Indentation of the first line.<br>Default value: **0**| 48| font<sup>10+</sup> | [Font](ts-types.md#font) | Text style, covering the font size, font width, Font family, and font style.| 49 50> **NOTE** 51> 52> The **\<Text>** component cannot contain both text and the child component **\<Span>** or **\<ImageSpan>**. If both of them exist, only the content in **\<Span>** or **\<ImageSpan>** is displayed. 53> 54> For the **\<Text>** component, the default value of the universal attribute [clip](ts-universal-attributes-sharp-clipping.md) is **true**, which means that the content outside of the component's content area is clipped. To display the content in full, set **clip** to **false**. 55> 56> The typesetting engine rounds down the value of [width](ts-universal-attributes-size.md#width) to ensure that the value is an integer. If the typesetting engine rounds up the value instead, the right side of the text may be clipped. 57 58## Events 59 60The [universal events](ts-universal-events-click.md) are supported. 61 62## Example 63 64### Example 1 65 66```ts 67// xxx.ets 68@Entry 69@Component 70struct TextExample1 { 71 build() { 72 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start, justifyContent: FlexAlign.SpaceBetween }) { 73 // Set the horizontal alignment mode for the text. 74 // Single-line text 75 Text('textAlign').fontSize(9).fontColor(0xCCCCCC) 76 Text('TextAlign set to Center.') 77 .textAlign(TextAlign.Center) 78 .fontSize(12) 79 .border({ width: 1 }) 80 .padding(10) 81 .width('100%') 82 Text('TextAlign set to Start.') 83 .textAlign(TextAlign.Start) 84 .fontSize(12) 85 .border({ width: 1 }) 86 .padding(10) 87 .width('100%') 88 Text('TextAlign set to End.') 89 .textAlign(TextAlign.End) 90 .fontSize(12) 91 .border({ width: 1 }) 92 .padding(10) 93 .width('100%') 94 95 // Multi-line text 96 Text('This is the text content with textAlign set to Center.') 97 .textAlign(TextAlign.Center) 98 .fontSize(12) 99 .border({ width: 1 }) 100 .padding(10) 101 .width('100%') 102 Text('This is the text content with textAlign set to Start.') 103 .textAlign(TextAlign.Start) 104 .fontSize(12) 105 .border({ width: 1 }) 106 .padding(10) 107 .width('100%') 108 Text('This is the text content with textAlign set to End.') 109 .textAlign(TextAlign.End) 110 .fontSize(12) 111 .border({ width: 1 }) 112 .padding(10) 113 .width('100%') 114 115 116 // Set the display mode when the text is too long. 117 Text('TextOverflow+maxLines').fontSize(9).fontColor(0xCCCCCC) 118 // Clip the text when the value of maxLines is exceeded. 119 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.') 120 .textOverflow({ overflow: TextOverflow.Clip }) 121 .maxLines(1) 122 .fontSize(12) 123 .border({ width: 1 }) 124 .padding(10) 125 126 // Show an ellipsis (...) when the value of maxLines is exceeded. 127 Text('This is set textOverflow to Ellipsis text content This is set textOverflow to Ellipsis text content.'.split('') 128 .join('\u200B')) 129 .textOverflow({ overflow: TextOverflow.Ellipsis }) 130 .maxLines(1) 131 .fontSize(12) 132 .border({ width: 1 }) 133 .padding(10) 134 135 Text('lineHeight').fontSize(9).fontColor(0xCCCCCC) 136 Text('This is the text with the line height set. This is the text with the line height set.') 137 .fontSize(12).border({ width: 1 }).padding(10) 138 Text('This is the text with the line height set. This is the text with the line height set.') 139 .fontSize(12).border({ width: 1 }).padding(10) 140 .lineHeight(20) 141 }.height(600).width(350).padding({ left: 35, right: 35, top: 35 }) 142 } 143} 144``` 145 146 147### Example 2 148 149```ts 150@Entry 151@Component 152struct TextExample2 { 153 build() { 154 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start, justifyContent: FlexAlign.SpaceBetween }) { 155 Text('decoration').fontSize(9).fontColor(0xCCCCCC) 156 Text('This is the text content with the decoration set to LineThrough and the color set to Red.') 157 .decoration({ 158 type: TextDecorationType.LineThrough, 159 color: Color.Red 160 }) 161 .fontSize(12) 162 .border({ width: 1 }) 163 .padding(10) 164 .width('100%') 165 166 167 Text('This is the text content with the decoration set to Overline and the color set to Red.') 168 .decoration({ 169 type: TextDecorationType.Overline, 170 color: Color.Red 171 }) 172 .fontSize(12) 173 .border({ width: 1 }) 174 .padding(10) 175 .width('100%') 176 177 178 Text('This is the text content with the decoration set to Underline and the color set to Red.') 179 .decoration({ 180 type: TextDecorationType.Underline, 181 color: Color.Red 182 }) 183 .fontSize(12) 184 .border({ width: 1 }) 185 .padding(10) 186 .width('100%') 187 188 // Set the text baseline offset. 189 Text('baselineOffset').fontSize(9).fontColor(0xCCCCCC) 190 Text('This is the text content with baselineOffset 0.') 191 .baselineOffset(0) 192 .fontSize(12) 193 .border({ width: 1 }) 194 .padding(10) 195 .width('100%') 196 Text('This is the text content with baselineOffset 30.') 197 .baselineOffset(30) 198 .fontSize(12) 199 .border({ width: 1 }) 200 .padding(10) 201 .width('100%') 202 Text('This is the text content with baselineOffset -20.') 203 .baselineOffset(-20) 204 .fontSize(12) 205 .border({ width: 1 }) 206 .padding(10) 207 .width('100%') 208 209 // Set the letter spacing. 210 Text('letterSpacing').fontSize(9).fontColor(0xCCCCCC) 211 Text('This is the text content with letterSpacing 0.') 212 .letterSpacing(0) 213 .fontSize(12) 214 .border({ width: 1 }) 215 .padding(10) 216 .width('100%') 217 Text('This is the text content with letterSpacing 3.') 218 .letterSpacing(3) 219 .fontSize(12) 220 .border({ width: 1 }) 221 .padding(10) 222 .width('100%') 223 Text('This is the text content with letterSpacing -1.') 224 .letterSpacing(-1) 225 .fontSize(12) 226 .border({ width: 1 }) 227 .padding(10) 228 .width('100%') 229 230 Text('textCase').fontSize(9).fontColor(0xCCCCCC) 231 Text('This is the text content with textCase set to Normal.') 232 .textCase(TextCase.Normal) 233 .fontSize(12) 234 .border({ width: 1 }) 235 .padding(10) 236 .width('100%') 237 // Display the text in lowercase. 238 Text('This is the text content with textCase set to LowerCase.') 239 .textCase(TextCase.LowerCase) 240 .fontSize(12) 241 .border({ width: 1 }) 242 .padding(10) 243 .width('100%') 244 // Display the text in uppercase. 245 Text('This is the text content with textCase set to UpperCase.') 246 .textCase(TextCase.UpperCase) 247 .fontSize(12).border({ width: 1 }).padding(10) 248 249 }.height(700).width(350).padding({ left: 35, right: 35, top: 35 }) 250 } 251} 252``` 253 254 255### Example 3 256 257```ts 258@Entry 259@Component 260struct TextExample { 261 build() { 262 Column({ space: 8 }) { 263 // Set the text shadow. 264 Text('textShadow').fontSize(9).fontColor(0xCCCCCC).margin(15).width('90%') 265 Text('textShadow') 266 .width('80%') 267 .height(55) 268 .fontSize(40) 269 .lineHeight(55) 270 .textAlign(TextAlign.Center) 271 .textShadow({ radius: 10, color: Color.Black, offsetX: 0, offsetY: 0 }) 272 .borderWidth(1) 273 Divider() 274 // Set how the adaptive height is determined for the text. 275 Text('heightAdaptivePolicy').fontSize(9).fontColor(0xCCCCCC).margin(15).width('90%') 276 Text('This is the text with the height adaptive policy set') 277 .width('80%') 278 .height(90) 279 .borderWidth(1) 280 .minFontSize(10) 281 .maxFontSize(30) 282 .maxLines(3) 283 .textOverflow({ overflow: TextOverflow.Ellipsis }) 284 .heightAdaptivePolicy(TextHeightAdaptivePolicy.MAX_LINES_FIRST) 285 Text('This is the text with the height adaptive policy set') 286 .width('80%') 287 .height(90) 288 .borderWidth(1) 289 .minFontSize(10) 290 .maxFontSize(30) 291 .maxLines(3) 292 .textOverflow({ overflow: TextOverflow.Ellipsis }) 293 .heightAdaptivePolicy(TextHeightAdaptivePolicy.MIN_FONT_SIZE_FIRST) 294 Text('This is the text with the height adaptive policy set') 295 .width('80%') 296 .height(90) 297 .borderWidth(1) 298 .minFontSize(10) 299 .maxFontSize(30) 300 .maxLines(3) 301 .textOverflow({ overflow: TextOverflow.Ellipsis }) 302 .heightAdaptivePolicy(TextHeightAdaptivePolicy.LAYOUT_CONSTRAINT_FIRST) 303 Divider() 304 // Set the text to continuously scroll when text overflow occurs. 305 Text('marquee').fontSize(9).fontColor(0xCCCCCC).margin(15).width('90%') 306 Text('This is the text with the text overflow set marquee') 307 .width(300) 308 .borderWidth(1) 309 .textOverflow({ overflow: TextOverflow.MARQUEE }) 310 } 311 } 312} 313``` 314 315 316
