1# TextArea 2 3The **TextArea** component provides multi-line text input and automatically wraps text to ensure that no line extends beyond the component's width. 4 5If the component does not have its height set, it adapts its height to the content. If the component does not have its width set, it stretches to fill the maximum available width. 6 7> **NOTE** 8> 9> This component is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. 10 11 12## Child Components 13 14Not supported 15 16 17## APIs 18 19TextArea(value?: TextAreaOptions) 20 21**Atomic service API**: This API can be used in atomic services since API version 11. 22 23**System capability**: SystemCapability.ArkUI.ArkUI.Full 24 25**Parameters** 26 27| Name| Type| Mandatory| Description| 28| ----- | ----- | ---- | ---- | 29| value | [TextAreaOptions](#textareaoptions) | No | Parameters of the **TextArea** component.| 30 31## TextAreaOptions 32 33**Atomic service API**: This API can be used in atomic services since API version 11. 34 35**System capability**: SystemCapability.ArkUI.ArkUI.Full 36 37| Name| Type | Mandatory | Description| 38| ---- | ----- | ---- | ---- | 39| placeholder | [ResourceStr](ts-types.md#resourcestr) | No | Text displayed when there is no input. <br>When only the **placeholder** attribute is set, the text selection handle is still available; the caret stays at the beginning of the placeholder text when the handle is released. | 40| text | [ResourceStr](ts-types.md#resourcestr) | No | Current text input.<br>You are advised to bind the state variable to the text in real time through the **onChange** event,<br>so as to prevent display errors when the component is updated.<br>Since API version 10, this parameter supports two-way binding through [$$](../../../quick-start/arkts-two-way-sync.md).<br>Since API version 18, this parameter supports two-way binding through [!!](../../../quick-start/arkts-new-binding.md#two-way-binding-between-built-in-component-parameters).| 41| controller<sup>8+</sup> | [TextAreaController](#textareacontroller8) | No | Text area controller.| 42 43 44## Attributes 45 46In addition to the [universal attributes](ts-component-general-attributes.md), the following attributes are supported. 47 48> **NOTE** 49> 50> The default value of the universal attribute [padding](ts-universal-attributes-size.md#padding) is as follows:<br>{<br> top: '8vp',<br> right: '16vp',<br> bottom: '8vp',<br> left: '16vp'<br> } 51> 52> Since API version 11, **.width('auto')** can be set for the **TextArea** component. Under this setting, the component auto-adapts its width to the text width, while respecting the **constraintSize** configuration and the maximum and minimum width restrictions received by the parent container. For details, see [Size](ts-universal-attributes-size.md). 53 54### placeholderColor 55 56placeholderColor(value: ResourceColor) 57 58Sets the placeholder text color. 59 60**Atomic service API**: This API can be used in atomic services since API version 11. 61 62**System capability**: SystemCapability.ArkUI.ArkUI.Full 63 64**Parameters** 65 66| Name| Type | Mandatory| Description | 67| ------ | ------------------------------------------ | ---- | -------------------------------------------- | 68| value | [ResourceColor](ts-types.md#resourcecolor) | Yes | Placeholder text color.<br>The default value follows the theme.| 69 70### placeholderFont 71 72placeholderFont(value: Font) 73 74Sets the placeholder text style, including the font size, font width, font family, and font style. The 'HarmonyOS Sans' font and [registered custom fonts](../js-apis-font.md) are supported. 75 76**Atomic service API**: This API can be used in atomic services since API version 11. 77 78**System capability**: SystemCapability.ArkUI.ArkUI.Full 79 80**Parameters** 81 82| Name| Type | Mandatory| Description | 83| ------ | ------------------------ | ---- | --------------------- | 84| value | [Font](ts-types.md#font) | Yes | Placeholder text style.| 85 86### textAlign 87 88textAlign(value: TextAlign) 89 90Sets the horizontal alignment of the text. 91 92Available options are **TextAlign.Start**, **TextAlign.Center**, and **TextAlign.End**. 93 94To 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. 95 96When **textAlign** is set to **TextAlign.JUSTIFY**, the text in the last line is horizontally aligned with the start edge. 97 98Since API version 11, **textAlign** can be set to **TextAlign.JUSTIFY**. 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 | [TextAlign](ts-appendix-enums.md#textalign) | Yes | Horizontal alignment of the text.<br>Default value: **TextAlign.Start**| 109 110### caretColor 111 112caretColor(value: ResourceColor) 113 114Sets the color of the caret in the text box. 115 116**Atomic service API**: This API can be used in atomic services since API version 11. 117 118**System capability**: SystemCapability.ArkUI.ArkUI.Full 119 120**Parameters** 121 122| Name| Type | Mandatory| Description | 123| ------ | ------------------------------------------ | ---- | -------------------------------------- | 124| value | [ResourceColor](ts-types.md#resourcecolor) | Yes | Color of the caret in the text box.<br>Default value: **'#007DFF'**| 125 126> **NOTE** 127> Since API version 12, this API can be used to set the text handle color, which is the same as the caret color. 128 129### fontColor 130 131fontColor(value: ResourceColor) 132 133Sets the font color. 134 135**Atomic service API**: This API can be used in atomic services since API version 11. 136 137**System capability**: SystemCapability.ArkUI.ArkUI.Full 138 139**Parameters** 140 141| Name| Type | Mandatory| Description | 142| ------ | ------------------------------------------ | ---- | ---------- | 143| value | [ResourceColor](ts-types.md#resourcecolor) | Yes | Font color.| 144 145### fontSize 146 147fontSize(value: Length) 148 149Sets the text size. 150 151**Atomic service API**: This API can be used in atomic services since API version 11. 152 153**System capability**: SystemCapability.ArkUI.ArkUI.Full 154 155**Parameters** 156 157| Name| Type | Mandatory| Description | 158| ------ | ---------------------------- | ---- | ------------------------------------------------------------ | 159| value | [Length](ts-types.md#length) | Yes | Font size. If **fontSize** is of the number type, the unit fp is used. The default font size is 16 fp on non-wearable devices and 18 fp on wearable devices. This parameter cannot be set in percentage.| 160 161### fontStyle 162 163fontStyle(value: FontStyle) 164 165Sets the font style. 166 167**Atomic service API**: This API can be used in atomic services since API version 11. 168 169**System capability**: SystemCapability.ArkUI.ArkUI.Full 170 171**Parameters** 172 173| Name| Type | Mandatory| Description | 174| ------ | ------------------------------------------- | ---- | --------------------------------------- | 175| value | [FontStyle](ts-appendix-enums.md#fontstyle) | Yes | Font style.<br>Default value: **FontStyle.Normal**| 176 177### fontWeight 178 179fontWeight(value: number | FontWeight | string) 180 181Sets the font weight. If the value is too large, the text may be clipped depending on the font. 182 183**Atomic service API**: This API can be used in atomic services since API version 11. 184 185**System capability**: SystemCapability.ArkUI.ArkUI.Full 186 187**Parameters** 188 189| Name| Type | Mandatory| Description | 190| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 191| 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 that represent a number, for example, **"400"**, and the following enumerated values of **FontWeight** are supported: **"bold"**, **"bolder"**, **"lighter"**, **"regular"**, and **"medium"**.<br>Default value: **FontWeight.Normal**| 192 193### fontFamily 194 195fontFamily(value: ResourceStr) 196 197Sets the font family. 198 199**Atomic service API**: This API can be used in atomic services since API version 11. 200 201**System capability**: SystemCapability.ArkUI.ArkUI.Full 202 203**Parameters** 204 205| Name| Type | Mandatory| Description | 206| ------ | -------------------------------------- | ---- | ------------------------------------------------------------ | 207| value | [ResourceStr](ts-types.md#resourcestr) | 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.| 208 209### inputFilter<sup>8+</sup> 210 211inputFilter(value: ResourceStr, error?: (value: string) => void) 212 213Sets the regular expression for input filtering. Only inputs that comply with the regular expression can be displayed. Other inputs are filtered out. The specified regular expression can match single characters, but not strings. 214 215**Atomic service API**: This API can be used in atomic services since API version 11. 216 217**System capability**: SystemCapability.ArkUI.ArkUI.Full 218 219**Parameters** 220 221| Name| Type | Mandatory| Description | 222| ------ | -------------------------------------- | ---- | ---------------------------------- | 223| value | [ResourceStr](ts-types.md#resourcestr) | Yes | Regular expression. | 224| error | (value: string) => void | No | Filtered-out content to return when regular expression matching fails.| 225 226### copyOption<sup>9+</sup> 227 228copyOption(value: CopyOptions) 229 230Sets whether copy and paste is allowed. If this attribute is set to **CopyOptions.None**, the text can only be pasted; all other actions, such as copying, cutting, and sharing, are disabled. 231 232Dragging is not allowed when **CopyOptions.None** is set. 233 234**Atomic service API**: This API can be used in atomic services since API version 11. 235 236**System capability**: SystemCapability.ArkUI.ArkUI.Full 237 238**Parameters** 239 240| Name| Type | Mandatory| Description | 241| ------ | ------------------------------------------------ | ---- | ------------------------------------------------------------ | 242| value | [CopyOptions](ts-appendix-enums.md#copyoptions9) | Yes | Whether copy and paste is allowed.<br>Default value: **CopyOptions.LocalDevice**| 243 244### maxLength<sup>10+</sup> 245 246maxLength(value: number) 247 248Sets the maximum number of characters for text input. By default, there is no maximum number of characters. When the maximum number of characters is reached, no more characters can be entered, and the border turns red. 249 250**Atomic service API**: This API can be used in atomic services since API version 11. 251 252**System capability**: SystemCapability.ArkUI.ArkUI.Full 253 254**Parameters** 255 256| Name| Type | Mandatory| Description | 257| ------ | ------ | ---- | ---------------------- | 258| value | number | Yes | Maximum number of characters for text input.| 259 260### showCounter<sup>10+</sup> 261 262showCounter(value: boolean, options?: InputCounterOptions) 263 264Sets the character counter displayed when the number of characters entered exceeds the threshold. 265 266**options** can be set only when **value** is set to **true**, in which case a character counter is displayed below the text box. This attribute must be used together with **maxlength**. The character counter is displayed in this format: Number of characters entered/Character limit. 267 268It is visible when the number of characters entered is greater than the character limit multiplied by the threshold percentage value. If **options** is not set, the text box border and character counter subscript turn red when the number of characters entered reaches the limit. If **value** is set to **true** and **options** is set, the text box border and character counter subscript turn red and the text box shakes when the number of characters entered reaches the limit, provided that the value of **thresholdPercentage** is valid. If **highlightBorder** is set to **false**, the text box border does not turn red. By default, **highlightBorder** is set to **true**. The character counter is not displayed for text boxes in inline input style. 269 270**Atomic service API**: This API can be used in atomic services since API version 11. 271 272**System capability**: SystemCapability.ArkUI.ArkUI.Full 273 274**Parameters** 275 276| Name | Type | Mandatory| Description | 277| --------------------- | ------------------------------------------------------------ | ---- | ---------------- | 278| value | boolean | Yes | Whether to display the character counter.| 279| options<sup>11+</sup> | [InputCounterOptions](ts-types.md#inputcounteroptions11) | No | Threshold percentage of the character counter.| 280 281### style<sup>10+</sup> 282 283style(value: TextContentStyle) 284 285Sets the polymorphic style of the text box. The inline input style is only available for the **TextAreaType.Normal** type. 286 287**Atomic service API**: This API can be used in atomic services since API version 11. 288 289**System capability**: SystemCapability.ArkUI.ArkUI.Full 290 291**Parameters** 292 293| Name| Type | Mandatory| Description | 294| ------ | ----------------------------------------------------------- | ---- | ----------------------------------------------------- | 295| value | [TextContentStyle](ts-appendix-enums.md#textcontentstyle10) | Yes | Polymorphic style of the text box.<br>Default value: **TextContentStyle.DEFAULT**| 296 297### enableKeyboardOnFocus<sup>10+</sup> 298 299enableKeyboardOnFocus(value: boolean) 300 301Sets whether to bring up the keyboard when the **TextArea** component obtains focus in a way other than clicking. 302 303Since API version 10, the **TextArea** component brings up the keyboard by default when it obtains focus. 304 305**Atomic service API**: This API can be used in atomic services since API version 11. 306 307**System capability**: SystemCapability.ArkUI.ArkUI.Full 308 309**Parameters** 310 311| Name| Type | Mandatory| Description | 312| ------ | ------- | ---- | ----------------------------------------------------------- | 313| value | boolean | Yes | Whether to bring up the keyboard when the **TextArea** component obtains focus in a way other than clicking.<br>Default value: **true**| 314 315### selectionMenuHidden<sup>10+</sup> 316 317selectionMenuHidden(value: boolean) 318 319Sets whether to hide the system text selection menu. 320 321**Atomic service API**: This API can be used in atomic services since API version 11. 322 323**System capability**: SystemCapability.ArkUI.ArkUI.Full 324 325**Parameters** 326 327| Name| Type | Mandatory| Description | 328| ------ | ------- | ---- | ------------------------------------------------------------ | 329| value | boolean | Yes | Whether to hide the system text selection menu.<br>**true**: The system text selection menu does not appear under the following circumstances: clicking the text box cursor, long-pressing the text box, double-tapping the text box, triple-tapping the text box, or right-clicking the text box.<br>**false**: The system text selection menu appears under the following circumstances: clicking the text box cursor, long-pressing the text box, double-tapping the text box, triple-tapping the text box, or right-clicking the text box.<br>Default value: **false**| 330 331### barState<sup>10+</sup> 332 333barState(value: BarState) 334 335Sets the scrollbar display mode when the text box is editable. 336 337**Atomic service API**: This API can be used in atomic services since API version 11. 338 339**System capability**: SystemCapability.ArkUI.ArkUI.Full 340 341**Parameters** 342 343| Name| Type | Mandatory| Description | 344| ------ | ----------------------------------------- | ---- | ------------------------------------------------------------ | 345| value | [BarState](ts-appendix-enums.md#barstate) | Yes | Scrollbar display mode when the text box is editable.<br>Default value: **BarState.Auto**| 346 347### maxLines<sup>10+</sup> 348 349maxLines(value: number) 350 351Sets the maximum number of lines that can be displayed. When **textOverflow** is set, text is truncated if the content exceeds this limit. When **textOverflow** is not set, in inline style, the text is scrollable if the content exceeds the limit while the text box is focused; **maxLines** does not apply when the text box is not focused. In non-inline style, the text is truncated according to the number of lines. 352 353**Atomic service API**: This API can be used in atomic services since API version 11. 354 355**System capability**: SystemCapability.ArkUI.ArkUI.Full 356 357**Parameters** 358 359| Name| Type | Mandatory| Description | 360| ------ | ----------------------------------------- | ---- | ------------------------------------------------------------ | 361| value | number | Yes | Maximum number of lines that can be displayed with the inline style in the editing state or with the non-inline style.<br>Default value: **3** with the inline style; **+∞** with the non-inline style, indicating that there is no maximum number of lines<br>Value range: (0, +∞)| 362 363### customKeyboard<sup>10+</sup> 364 365customKeyboard(value: CustomBuilder, options?: KeyboardOptions) 366 367Custom keyboard. 368 369When a custom keyboard is set, activating the text box opens the specified custom component, instead of the system input method. 370 371The custom keyboard's height can be set through the **height** attribute of the custom component's root node, and its width is fixed at the default value. 372 373The custom keyboard is presented by overlaying the original screen, which is not compressed or lifted if avoid mode is not enabled or avoidance is not needed for the text box. 374 375The custom keyboard cannot obtain the focus, but it blocks gesture events. 376 377By default, the custom keyboard is closed when the input component loses the focus. You can also use the [TextAreaController](#textareacontroller8).[stopEditing](#stopediting10) API to close the keyboard. 378 379When a custom keyboard is set, the text box does not support camera input, even when the device supports. 380 381When setting a custom keyboard, you can bind the [onKeyPrelme](ts-universal-events-key.md#onkeypreime12) event to prevent input from the physical keyboard. 382 383**Atomic service API**: This API can be used in atomic services since API version 11. 384 385**System capability**: SystemCapability.ArkUI.ArkUI.Full 386 387**Parameters** 388 389| Name | Type | Mandatory| Description | 390| --------------------- | ------------------------------------------- | ---- | ------------------------------------------------------------ | 391| value | [CustomBuilder](ts-types.md#custombuilder8) | Yes | Custom keyboard.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 392| options<sup>12+</sup> | [KeyboardOptions](ts-basic-components-richeditor.md#keyboardoptions12) | No | Whether to support keyboard avoidance. | 393 394### type<sup>11+</sup> 395 396type(value: TextAreaType) 397 398Sets the text box type. 399 400**Atomic service API**: This API can be used in atomic services since API version 12. 401 402**System capability**: SystemCapability.ArkUI.ArkUI.Full 403 404**Parameters** 405 406| Name| Type | Mandatory| Description | 407| ------ | --------------------------------------- | ---- | -------------------------------------------- | 408| value | [TextAreaType](#textareatype11) | Yes | Text box type.<br>Default value: **TextAreaType.Normal**| 409 410### enterKeyType<sup>11+</sup> 411 412enterKeyType(value: EnterKeyType) 413 414Sets the type of the Enter key. 415 416**Atomic service API**: This API can be used in atomic services since API version 12. 417 418**System capability**: SystemCapability.ArkUI.ArkUI.Full 419 420**Parameters** 421 422| Name| Type | Mandatory| Description | 423| ------ | ------------------------------------------------ | ---- | ---------------------------------------------------- | 424| value | [EnterKeyType](ts-basic-components-textinput.md#enterkeytype) | Yes | Type of the Enter key.<br>Default value: **EnterKeyType.NEW_LINE**| 425 426### enableAutoFill<sup>12+</sup> 427 428enableAutoFill(value: boolean) 429 430Sets whether to enable autofill. 431 432**Atomic service API**: This API can be used in atomic services since API version 12. 433 434**System capability**: SystemCapability.ArkUI.ArkUI.Full 435 436**Parameters** 437 438| Name| Type | Mandatory| Description | 439| ------ | ------- | ---- | ------------------------------------------------------------ | 440| value | boolean | Yes | Whether to enable autofill.<br>**true**: enable<br>**false**: disable<br><br>Default value: **true**| 441 442### contentType<sup>12+</sup> 443 444contentType(contentType: ContentType) 445 446Sets the content type for autofill. 447 448**Atomic service API**: This API can be used in atomic services since API version 12. 449 450**System capability**: SystemCapability.ArkUI.ArkUI.Full 451 452**Parameters** 453 454| Name | Type | Mandatory| Description | 455| ----------- | ------------------------------------- | ---- | -------------- | 456| contentType | [ContentType](ts-basic-components-textinput.md#contenttype12) | Yes | Content type for autofill.| 457 458### lineHeight<sup>12+</sup> 459 460lineHeight(value: number | string | Resource) 461 462Sets the 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 is of the number type, the unit fp is used. 463 464**Atomic service API**: This API can be used in atomic services since API version 12. 465 466**System capability**: SystemCapability.ArkUI.ArkUI.Full 467 468**Parameters** 469 470| Name| Type | Mandatory| Description | 471| ------ | ------------------------------------------------------------ | ---- | ---------------- | 472| value | number \| string \| [Resource](ts-types.md#resource) | Yes | Text line height.| 473 474### decoration<sup>12+</sup> 475 476decoration(value: TextDecorationOptions) 477 478Sets the color, type, and style of the text decorative line. 479 480**Atomic service API**: This API can be used in atomic services since API version 12. 481 482**System capability**: SystemCapability.ArkUI.ArkUI.Full 483 484**Parameters** 485 486| Name| Type | Mandatory| Description | 487| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 488| value | [TextDecorationOptions](ts-types.md#textdecorationoptions12) | Yes | Text decorative line options.<br>Default value: {<br> type: TextDecorationType.None,<br> color: Color.Black,<br> style: TextDecorationStyle.SOLID <br>} | 489 490### letterSpacing<sup>12+</sup> 491 492letterSpacing(value: number | string | Resource) 493 494Sets the letter spacing for a text style. If the value specified is a percentage or 0, the default value is used. For the string type, numeric string values with optional units, for example, **"10"** or **"10fp"**, are supported. 495 496If the value specified is a negative value, the text is compressed. A negative value too small may result in the text being compressed to 0 and no content being displayed. 497 498**Atomic service API**: This API can be used in atomic services since API version 12. 499 500**System capability**: SystemCapability.ArkUI.ArkUI.Full 501 502**Parameters** 503 504| Name| Type | Mandatory| Description | 505| ------ | -------------------------- | ---- | -------------- | 506| value | number \| string \| [Resource](ts-types.md#resource) | Yes | Letter spacing.<br>Unit: fp| 507 508### fontFeature<sup>12+</sup> 509 510fontFeature(value: string) 511 512Sets the font feature, for example, monospaced digits. 513 514Format: normal \| \<feature-tag-value\> 515 516Format of **\<feature-tag-value\>**: \<string\> \[ \<integer\> \| on \| off ] 517 518There can be multiple **\<feature-tag-value\>** values, which are separated by commas (,). 519 520For example, the input format for monospaced clock fonts is "ss01" on. 521 522**Atomic service API**: This API can be used in atomic services since API version 12. 523 524**System capability**: SystemCapability.ArkUI.ArkUI.Full 525 526**Parameters** 527 528| Name| Type | Mandatory| Description | 529| ------ | ------ | ---- | -------------- | 530| value | string | Yes | Font feature.| 531 532For details about the supported font features, see [Font Feature List](ts-basic-components-text.md#fontfeature12). 533Font features are advanced typographic features, such as ligatures and monospace, for OpenType fonts. They are typically used in custom fonts and require the support of the font itself. 534For more information about the font features, see [Low-level font feature settings control: the font-feature-settings property](https://www.w3.org/TR/css-fonts-3/#font-feature-settings-prop) and [The Complete CSS Demo for OpenType Features](https://sparanoid.com/lab/opentype-features/). 535### wordBreak<sup>12+</sup> 536 537wordBreak(value: WordBreak) 538 539Sets the word break rule. This attribute does not take effect for the placeholder text. 540 541**Atomic service API**: This API can be used in atomic services since API version 12. 542 543**System capability**: SystemCapability.ArkUI.ArkUI.Full 544 545**Parameters** 546 547| Name| Type | Mandatory| Description | 548| ------ | --------------------------------------------- | ---- | --------------------------------------------- | 549| value | [WordBreak](ts-appendix-enums.md#wordbreak11) | Yes | Word break rule.<br>Default value: **WordBreak.BREAK_WORD**| 550 551> **NOTE** 552> 553> The component does not support the **clip** attribute. Therefore, setting this attribute does not affect text clipping. 554 555### selectedBackgroundColor<sup>12+</sup> 556 557selectedBackgroundColor(value: ResourceColor) 558 559Sets the background color of the selected text. If the opacity is not set, a 20% opacity will be used. 560 561**Atomic service API**: This API can be used in atomic services since API version 12. 562 563**System capability**: SystemCapability.ArkUI.ArkUI.Full 564 565**Parameters** 566 567| Name| Type | Mandatory| Description | 568| ------ | ------------------------------------------ | ---- | ------------------------------------------ | 569| value | [ResourceColor](ts-types.md#resourcecolor) | Yes | Background color of the selected text.<br>By default, a 20% opacity is applied.| 570 571### caretStyle<sup>12+</sup> 572 573caretStyle(value: CaretStyle) 574 575Sets the caret style. 576 577**Atomic service API**: This API can be used in atomic services since API version 12. 578 579**System capability**: SystemCapability.ArkUI.ArkUI.Full 580 581**Parameters** 582 583| Name| Type | Mandatory| Description | 584| ------ | ----------------------------------- | ---- | ------------ | 585| value | [CaretStyle](ts-text-common.md#caretstyle10) | Yes | Caret style.| 586 587### textIndent<sup>12+</sup> 588 589textIndent(value: Dimension) 590 591Sets the indent of the first line text. 592 593**Atomic service API**: This API can be used in atomic services since API version 12. 594 595**System capability**: SystemCapability.ArkUI.ArkUI.Full 596 597**Parameters** 598 599| Name| Type | Mandatory| Description | 600| ------ | ----------------------------------- | ---- | ---------------------------- | 601| value | [Dimension](ts-types.md#dimension10)| Yes | Indent of the first line text.<br>Default value: **0**| 602 603### textOverflow<sup>12+</sup> 604 605textOverflow(value: TextOverflow) 606 607Sets the display mode when the text is too long. 608 609In inline style, the effect of truncating text according to **maxLines** only applies when **textOverflow** is set. 610 611Text is clipped at the transition between words. To clip text in the middle of a word, set **wordBreak** to **WordBreak.BREAK_ALL**. 612 613If **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**. 614 615**Widget capability**: This API can be used in ArkTS widgets. 616 617**Atomic service API**: This API can be used in atomic services since API version 12. 618 619**System capability**: SystemCapability.ArkUI.ArkUI.Full 620 621**Parameters** 622 623| Name| Type | Mandatory| Description | 624| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 625| value | [TextOverflow](ts-appendix-enums.md#textoverflow) | Yes | Display mode when the text is too long.<br>Default value: **TextOverflow.Clip** | 626 627> **NOTE** 628> The **TextArea** component does not support the **TextOverflow.MARQUEE** mode. If this attribute is set to **TextOverflow.MARQUEE**, **TextOverflow.Clip** is used instead. 629 630### minFontSize<sup>12+</sup> 631 632minFontSize(value: number | string | Resource) 633 634Sets the minimum font size. For the string type, numeric string values with optional units, for example, **"10"** or **"10fp"**, are supported. 635 636For the setting to take effect, this attribute must be used together with [maxFontSize](#maxfontsize12) and [maxLines](#maxlines10), or layout constraint settings. 637 638When the adaptive font size is used, the **fontSize** settings do not take effect. 639 640**Atomic service API**: This API can be used in atomic services since API version 12. 641 642**System capability**: SystemCapability.ArkUI.ArkUI.Full 643 644**Parameters** 645 646| Name| Type | Mandatory| Description | 647| ------ | ------------------------------------------------------------ | ---- | ------------------ | 648| value | number \| string \| [Resource](ts-types.md#resource) | Yes | Minimum font size.<br>Unit: fp| 649 650### maxFontSize<sup>12+</sup> 651 652maxFontSize(value: number | string | Resource) 653 654Sets the maximum font size. For the string type, numeric string values with optional units, for example, **"10"** or **"10fp"**, are supported. 655 656For the setting to take effect, this attribute must be used together with [minFontSize](#minfontsize12) and [maxLines](#maxlines10), or layout constraint settings. 657 658When the adaptive font size is used, the **fontSize** settings do not take effect. 659 660**Atomic service API**: This API can be used in atomic services since API version 12. 661 662**System capability**: SystemCapability.ArkUI.ArkUI.Full 663 664**Parameters** 665 666| Name| Type | Mandatory| Description | 667| ------ | ------------------------------------------------------------ | ---- | ------------------ | 668| value | number \| string \| [Resource](ts-types.md#resource) | Yes | Maximum font size.<br>Unit: fp| 669 670### heightAdaptivePolicy<sup>12+</sup> 671 672heightAdaptivePolicy(value: TextHeightAdaptivePolicy) 673 674Sets how the adaptive height is determined for the text. 675 676When this attribute is set to **TextHeightAdaptivePolicy.MAX_LINES_FIRST**, the [maxLines](#maxlines10) 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](#minfontsize12) and [maxFontSize](#maxfontsize12) to allow for more content to be shown. 677If the text box is in inline input style, the font size in the editing state is different from that in the non-editing state. 678 679If 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**. 680 681If 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. 682 683**Atomic service API**: This API can be used in atomic services since API version 12. 684 685**System capability**: SystemCapability.ArkUI.ArkUI.Full 686 687**Parameters** 688 689| Name| Type | Mandatory| Description | 690| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 691| value | [TextHeightAdaptivePolicy](ts-appendix-enums.md#textheightadaptivepolicy10) | Yes | How the adaptive height is determined for the text.<br>Default value: **TextHeightAdaptivePolicy.MAX_LINES_FIRST**| 692 693### lineSpacing<sup>12+</sup> 694 695lineSpacing(value: LengthMetrics) 696 697Sets the line spacing of the text. If the value specified is less than or equal to 0, the default value **0** is used. 698 699**Atomic service API**: This API can be used in atomic services since API version 12. 700 701**System capability**: SystemCapability.ArkUI.ArkUI.Full 702 703**Parameters** 704 705| Name| Type | Mandatory| Description | 706| ------ | ------------------------------------------------------------ | ---- | ---------------- | 707| value | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) | Yes | Line spacing. Default value: **0**| 708 709### lineBreakStrategy<sup>12+</sup> 710 711lineBreakStrategy(strategy: LineBreakStrategy) 712 713Sets the line break rule. This attribute takes effect when **wordBreak** is not set to **breakAll**. Hyphens are not supported. 714 715**Atomic service API**: This API can be used in atomic services since API version 12. 716 717**System capability**: SystemCapability.ArkUI.ArkUI.Full 718 719**Parameters** 720 721| Name | Type | Mandatory| Description | 722| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------- | 723| strategy | [LineBreakStrategy](ts-appendix-enums.md#linebreakstrategy12) | Yes | Line break rule.<br>Default value: **LineBreakStrategy.GREEDY**| 724 725### editMenuOptions<sup>12+</sup> 726 727editMenuOptions(editMenu: EditMenuOptions) 728 729Sets the extended options of the custom context menu on selection, including the text content, icon, and callback. 730 731**Atomic service API**: This API can be used in atomic services since API version 12. 732 733**System capability**: SystemCapability.ArkUI.ArkUI.Full 734 735**Parameters** 736 737| Name| Type | Mandatory| Description | 738| ------ | --------------------------------------------- | ---- | --------------------------------------------- | 739| editMenu | [EditMenuOptions](ts-text-common.md#editmenuoptions) | Yes | Extended options of the custom context menu on selection.| 740 741### enablePreviewText<sup>12+</sup> 742 743enablePreviewText(enable: boolean) 744 745Sets whether to enable preview text. 746 747Preview text is in a temporary state and does not support text interception. As such, it does not trigger **onWillInsert**, **onDidInsert**, **onWillDelete**, or **onDidDelete** callbacks. 748 749**Atomic service API**: This API can be used in atomic services since API version 12. 750 751**System capability**: SystemCapability.ArkUI.ArkUI.Full 752 753**Parameters** 754 755| Name| Type | Mandatory| Description | 756| ------ | ------- | ---- | ---------------------------------- | 757| enable | boolean | Yes | Whether to enable preview text.<br>Default value: **true**| 758 759### enableHapticFeedback<sup>13+</sup> 760 761enableHapticFeedback(isEnabled: boolean) 762 763Specifies whether to enable haptic feedback. 764 765**Atomic service API**: This API can be used in atomic services since API version 13. 766 767**System capability**: SystemCapability.ArkUI.ArkUI.Full 768 769**Parameters** 770 771| Name| Type | Mandatory| Description | 772| ------ | ------- | ---- | ---------------------------------- | 773| isEnabled | boolean | Yes | Whether to enable haptic feedback.<br>Default value: **true**| 774 775> **NOTE** 776> 777> To enable haptic feedback, you must declare the ohos.permission.VIBRATE permission under **requestPermissions** in the **module.json5** file of the project. 778> ```json 779> "requestPermissions": [ 780> { 781> "name": "ohos.permission.VIBRATE", 782> } 783> ] 784> ``` 785 786### keyboardAppearance<sup>15+</sup> 787 788keyboardAppearance(appearance: Optional\<KeyboardAppearance>) 789 790Sets the appearance of the keyboard when the text box is focused. 791 792**Atomic service API**: This API can be used in atomic services since API version 15. 793 794**System capability**: SystemCapability.ArkUI.ArkUI.Full 795 796**Parameters** 797 798| Name| Type| Mandatory| Description| 799| ------ | ----------------------------------------- | ---- | ------------------------------------------------------ | 800| appearance | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[KeyboardAppearance](ts-text-common.md#keyboardappearance15)> | Yes | Appearance of the keyboard.<br>Default value: **KeyboardAppearance.NONE_IMMERSIVE**| 801 802### stopBackPress<sup>15+</sup> 803 804stopBackPress(isStopped: Optional\<boolean>) 805 806Sets whether to prevent the back button press from being propagated to other components or applications. 807 808**Atomic service API**: This API can be used in atomic services since API version 15. 809 810**System capability**: SystemCapability.ArkUI.ArkUI.Full 811 812**Parameters** 813 814| Name| Type | Mandatory| Description | 815| ------ | --------------------------------------------------- | ---- | ----------------------------------------- | 816| isStopped | [Optional](ts-universal-attributes-custom-property.md#optional12)\<boolean> | Yes | Whether to consume the back button press.<br>Default value: **true**| 817 818### halfLeading<sup>18+</sup> 819 820halfLeading(halfLeading: Optional\<boolean>) 821 822Sets whether half leading is enabled. 823 824**Atomic service API**: This API can be used in atomic services since API version 18. 825 826**System capability**: SystemCapability.ArkUI.ArkUI.Full 827 828**Parameters** 829 830| Name| Type | Mandatory| Description | 831| ------ | --------------------------------------------- | ---- | --------------------------------------------- | 832| halfLeading | [Optional](ts-universal-attributes-custom-property.md#optional12)\<boolean> | Yes | Whether half leading is enabled.<br>Half leading is the leading split in half and applied equally to the top and bottom edges. The value **true** means that half leading is enabled, and **false** means the opposite.<br>Default value: **false**| 833 834### minFontScale<sup>18+</sup> 835 836minFontScale(scale: Optional\<number | Resource>) 837 838Sets the minimum font scale factor for text. 839 840**Atomic service API**: This API can be used in atomic services since API version 18. 841 842**System capability**: SystemCapability.ArkUI.ArkUI.Full 843 844**Parameters** 845 846| Name| Type | Mandatory| Description | 847| ------ | --------------------------------------------- | ---- | --------------------------------------------- | 848| scale | [Optional](ts-universal-attributes-custom-property.md#optional12)\<number \| [Resource](ts-types.md#resource)> | Yes | Minimum font scale factor for text. The **undefined** type is supported.<br>Value range: [0, 1]<br>**NOTE**<br>A value less than 0 is handled as 0. A value greater than 1 is handled as 1. Abnormal values are ineffective by default.| 849 850### maxFontScale<sup>18+</sup> 851 852maxFontScale(scale: Optional\<number | Resource>) 853 854Sets the maximum font scale factor for text. 855 856**Atomic service API**: This API can be used in atomic services since API version 18. 857 858**System capability**: SystemCapability.ArkUI.ArkUI.Full 859 860**Parameters** 861 862| Name| Type | Mandatory| Description | 863| ------ | --------------------------------------------- | ---- | --------------------------------------------- | 864| scale | [Optional](ts-universal-attributes-custom-property.md#optional12)\<number \| [Resource](ts-types.md#resource)> | Yes | Maximum font scale factor for text. The **undefined** type is supported.<br>Value range: [1, +∞)<br>**NOTE**<br>A value less than 1 is handled as 1. Abnormal values are ineffective by default.| 865 866### ellipsisMode<sup>18+</sup> 867 868ellipsisMode(mode: Optional\<EllipsisMode>) 869 870Sets the ellipsis position. For the settings to work, **overflow** must be set to **TextOverflow.Ellipsis** and **maxLines** must be specified. Setting **ellipsisMode** alone does not take effect. 871 872**EllipsisMode.START** and **EllipsisMode.CENTER** take effect only when **maxLines** is set to **1**. 873 874**Atomic service API**: This API can be used in atomic services since API version 18. 875 876**System capability**: SystemCapability.ArkUI.ArkUI.Full 877 878**Parameters** 879 880| Name| Type | Mandatory| Description | 881| ------ | --------------------------------------------------- | ---- | ----------------------------------------- | 882| mode | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[EllipsisMode](ts-appendix-enums.md#ellipsismode11)> | Yes | Ellipsis position.<br>Default value: **EllipsisMode.END**| 883 884## Events 885 886In addition to the [universal events](ts-component-general-events.md), the following events are supported. 887 888### onChange 889 890onChange(callback: EditableTextOnChangeCallback) 891 892Called when the input in the text box changes. 893 894In this callback, if cursor operations are performed, you need to adjust the cursor logic based on the **previewText** parameter to make sure it works seamlessly under the preview display scenario. 895 896**Atomic service API**: This API can be used in atomic services since API version 11. 897 898**System capability**: SystemCapability.ArkUI.ArkUI.Full 899 900**Parameters** 901 902| Name| Type | Mandatory| Description | 903| ------ | ------ | ---- | -------------------- | 904| callback | [EditableTextOnChangeCallback](ts-text-common.md#editabletextonchangecallback12) | Yes | Callback invoked when the input in the text box changes.| 905 906### onEditChange<sup>10+</sup> 907 908onEditChange(callback: (isEditing: boolean) => void) 909 910Triggered when the input status changes. The text box is in the editing state when it has the caret placed in it, and is in the non-editing state otherwise. If the value of **isEditing** is **true**, the text box is in the editing state. 911 912**Atomic service API**: This API can be used in atomic services since API version 11. 913 914**System capability**: SystemCapability.ArkUI.ArkUI.Full 915 916**Parameters** 917 918| Name | Type | Mandatory| Description | 919| --------- | ------- | ---- | -------------------- | 920| isEditing | boolean | Yes | Whether the text box is in the editing state. The value **true** indicates that the text box is in the editing state.| 921 922### onCopy<sup>8+</sup> 923 924onCopy(callback: (value: string) => void) 925 926Triggered when a copy operation is performed. 927 928**Atomic service API**: This API can be used in atomic services since API version 11. 929 930**System capability**: SystemCapability.ArkUI.ArkUI.Full 931 932**Parameters** 933 934| Name| Type | Mandatory| Description | 935| ------ | ------ | ---- | ---------------- | 936| value | string | Yes | Text that is copied.| 937 938### onCut<sup>8+</sup> 939 940onCut(callback: (value: string) => void) 941 942Triggered when a cut operation is performed. 943 944**Atomic service API**: This API can be used in atomic services since API version 11. 945 946**System capability**: SystemCapability.ArkUI.ArkUI.Full 947 948**Parameters** 949 950| Name| Type | Mandatory| Description | 951| ------ | ------ | ---- | ---------------- | 952| value | string | Yes | Text that is cut.| 953 954### onPaste 955 956onPaste(callback: (value: string, event: PasteEvent) => void) 957 958Triggered when a paste operation is performed. 959 960**Atomic service API**: This API can be used in atomic services since API version 11. 961 962**System capability**: SystemCapability.ArkUI.ArkUI.Full 963 964**Parameters** 965 966| Name | Type | Mandatory| Description | 967| ------------------- | ------------------------------------------------------------ | ---- | ---------------------- | 968| value | string | Yes | Text to be pasted. | 969| event<sup>11+</sup> | [PasteEvent](ts-basic-components-richeditor.md#pasteevent11) | Yes | Custom paste event.| 970 971### onTextSelectionChange<sup>10+</sup> 972 973onTextSelectionChange(callback: (selectionStart: number, selectionEnd: number) => void) 974 975Triggered when the position of the text selection changes or when the cursor position changes during the editing state. 976 977**Atomic service API**: This API can be used in atomic services since API version 11. 978 979**System capability**: SystemCapability.ArkUI.ArkUI.Full 980 981**Parameters** 982 983| Name | Type | Mandatory| Description | 984| -------------- | ------ | ---- | --------------------------------------- | 985| selectionStart | number | Yes | Start position of the selected text. The start position of text is **0**.| 986| selectionEnd | number | Yes | End position of the selected text. | 987 988### onContentScroll<sup>10+</sup> 989 990onContentScroll(callback: (totalOffsetX: number, totalOffsetY: number) => void) 991 992Triggered when the text content is scrolled. 993 994**Atomic service API**: This API can be used in atomic services since API version 11. 995 996**System capability**: SystemCapability.ArkUI.ArkUI.Full 997 998**Parameters** 999 1000| Name | Type | Mandatory| Description | 1001| ------------ | ------ | ---- | ---------------------------------- | 1002| totalOffsetX | number | Yes | Offset in the X coordinate of the text in the content area, in px.| 1003| totalOffsetY | number | Yes | Offset in the Y coordinate of the text in the content area, in px.| 1004 1005### onSubmit<sup>11+</sup> 1006 1007onSubmit(callback: (enterKey: EnterKeyType) => void) 1008 1009Triggered when the Enter key on the soft keyboard is pressed. 1010 1011**Atomic service API**: This API can be used in atomic services since API version 12. 1012 1013**System capability**: SystemCapability.ArkUI.ArkUI.Full 1014 1015**Parameters** 1016 1017| Name | Type | Mandatory| Description | 1018| -------- | ------------------------------------------------ | ---- | ------------------------------------------------------------ | 1019| enterKey | [EnterKeyType](ts-basic-components-textinput.md#enterkeytype) | Yes | Type of the Enter key. If it is **EnterKeyType.NEW_LINE** and the text box is in inline input style, **onSubmit** is not triggered.| 1020 1021### onSubmit<sup>14+</sup> 1022 1023onSubmit(callback: TextAreaSubmitCallback) 1024 1025Triggered when the Enter key on the soft keyboard is pressed, providing methods to maintain the editing state of the **TextArea** component upon submission. 1026 1027**Atomic service API**: This API can be used in atomic services since API version 14. 1028 1029**System capability**: SystemCapability.ArkUI.ArkUI.Full 1030 1031**Parameters** 1032 1033| Name| Type | Mandatory| Description | 1034| ------ | ------- | ---- | ----------------------------- | 1035| callback | [TextAreaSubmitCallback](#textareasubmitcallback14) | Yes | Callback triggered when the Enter key on the soft keyboard is pressed.| 1036 1037### onWillInsert<sup>12+</sup> 1038 1039onWillInsert(callback: Callback\<InsertValue, boolean>) 1040 1041Triggered when text is about to be inserted. 1042 1043**Atomic service API**: This API can be used in atomic services since API version 12. 1044 1045**System capability**: SystemCapability.ArkUI.ArkUI.Full 1046 1047**Parameters** 1048 1049| Name| Type | Mandatory| Description | 1050| ------ | ------------------------------------------------------------ | ---- | ------------------ | 1051| callback | Callback\<[InsertValue](ts-text-common.md#insertvalue12), boolean> | Yes | Callback triggered when text is about to be inserted.<br>It returns **true** if the text is inserted; returns **false** otherwise.<br>This callback is not triggered for pre-edit or candidate word operations.<br>It is available only for system input methods.| 1052 1053### onDidInsert<sup>12+</sup> 1054 1055onDidInsert(callback: Callback\<InsertValue>) 1056 1057Called when text is inserted. 1058 1059**Atomic service API**: This API can be used in atomic services since API version 12. 1060 1061**System capability**: SystemCapability.ArkUI.ArkUI.Full 1062 1063**Parameters** 1064 1065| Name| Type | Mandatory| Description | 1066| ------ | ------------------------------------------------------------ | ---- | ------------------ | 1067| callback | Callback\<[InsertValue](ts-text-common.md#insertvalue12)> | Yes | Callback triggered when text is inserted.<br>It is available only for system input methods.| 1068 1069### onWillDelete<sup>12+</sup> 1070 1071onWillDelete(callback: Callback\<DeleteValue, boolean>) 1072 1073Triggered when text is about to be deleted. 1074 1075**Atomic service API**: This API can be used in atomic services since API version 12. 1076 1077**System capability**: SystemCapability.ArkUI.ArkUI.Full 1078 1079**Parameters** 1080 1081| Name| Type | Mandatory| Description | 1082| ------ | ------------------------------------------------------------ | ---- | ------------------ | 1083| callback | Callback\<[DeleteValue](ts-text-common.md#deletevalue12), boolean> | Yes | Callback triggered when text is about to be deleted.<br>It returns **true** if the text is deleted; returns **false** otherwise.<br>This callback is not called for text preview.<br>It is available only for system input methods.| 1084 1085### onDidDelete<sup>12+</sup> 1086 1087onDidDelete(callback: Callback\<DeleteValue>) 1088 1089Triggered when text is deleted. 1090 1091**Atomic service API**: This API can be used in atomic services since API version 12. 1092 1093**System capability**: SystemCapability.ArkUI.ArkUI.Full 1094 1095**Parameters** 1096 1097| Name| Type | Mandatory| Description | 1098| ------ | ------------------------------------------------------------ | ---- | ------------------ | 1099| callback | Callback\<[DeleteValue](ts-text-common.md#deletevalue12)> | Yes | Callback triggered when text is deleted.<br>It is available only for system input methods.| 1100 1101### onWillChange<sup>15+</sup> 1102 1103onWillChange(callback: Callback\<EditableTextChangeValue, boolean>) 1104 1105Called when the text content is about to change. 1106 1107This callback is triggered after **onWillInsert** and **onWillDelete**, but before **onDidInsert** and **onDidDelete**. 1108 1109**Atomic service API**: This API can be used in atomic services since API version 15. 1110 1111**System capability**: SystemCapability.ArkUI.ArkUI.Full 1112 1113**Parameters** 1114 1115| Name| Type | Mandatory| Description | 1116| ------ | ------------------------------------------------------------ | ---- | ------------------ | 1117| callback | Callback\<[EditableTextChangeValue](ts-text-common.md#editabletextchangevalue15), boolean> | Yes | Callback triggered when the text content is about to change.<br>Returning **true** allows the change to proceed, while returning **false** cancels the change.| 1118 1119## TextAreaController<sup>8+</sup> 1120 1121Inherits from [TextContentControllerBase](ts-types.md#textcontentcontrollerbase10). 1122 1123**Atomic service API**: This API can be used in atomic services since API version 11. 1124 1125**System capability**: SystemCapability.ArkUI.ArkUI.Full 1126 1127### Objects to Import 1128 1129``` 1130controller: TextAreaController = new TextAreaController() 1131``` 1132 1133### constructor<sup>8+</sup> 1134 1135constructor() 1136 1137A constructor used to create a **TextAreaController** object. 1138 1139**Atomic service API**: This API can be used in atomic services since API version 11. 1140 1141**System capability**: SystemCapability.ArkUI.ArkUI.Full 1142 1143### caretPosition<sup>8+</sup> 1144 1145caretPosition(value: number): void 1146 1147Sets the position of the caret. 1148 1149**Atomic service API**: This API can be used in atomic services since API version 11. 1150 1151**System capability**: SystemCapability.ArkUI.ArkUI.Full 1152 1153**Parameters** 1154 1155| Name| Type| Mandatory| Description | 1156| ------ | ---- | ---- | ---- | 1157| value | number | Yes | Length from the start of the string to the position where the caret is located.| 1158 1159### setTextSelection<sup>10+</sup> 1160 1161setTextSelection(selectionStart: number, selectionEnd: number, options?: SelectionOptions): void 1162 1163Sets the text selection range and highlights the selected text when the component is focused. This API works only when the value of **selectionStart** is less than that of **selectionEnd**. 1164 1165**Atomic service API**: This API can be used in atomic services since API version 11. 1166 1167**System capability**: SystemCapability.ArkUI.ArkUI.Full 1168 1169**Parameters** 1170 1171| Name| Type| Mandatory| Description | 1172| ------ | ---- | ---- | ---- | 1173| selectionStart | number | Yes | Start position of the text selection range. The start position of text in the text box is 0.<br>A value less than 0 is handled as **0**. A value greater than the maximum text length is handled as the maximum text length.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 1174| selectionEnd | number | Yes | End position of the text selection range.<br>A value less than 0 is handled as the value **0**. A value greater than the maximum text length is handled as the maximum text length.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 1175| options<sup>12+</sup> | [SelectionOptions](ts-types.md#selectionoptions12) | No | Configuration options for text selection.<br>Default value: **MenuPolicy.DEFAULT**<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 1176 1177> **NOTE** 1178> 1179> If **selectionMenuHidden** is set to **true** or a 2-in-1 device is used, calling **setTextSelection** does not display the context menu even when **options** is set to **MenuPolicy.SHOW**. 1180> 1181> If the selected text contains an emoji, the emoji is selected when its start position is within the text selection range. 1182 1183### stopEditing<sup>10+</sup> 1184 1185stopEditing(): void 1186 1187Exits the editing state. 1188 1189**Atomic service API**: This API can be used in atomic services since API version 11. 1190 1191**System capability**: SystemCapability.ArkUI.ArkUI.Full 1192 1193## TextAreaType<sup>11+</sup> 1194 1195**Atomic service API**: This API can be used in atomic services since API version 12. 1196 1197**System capability**: SystemCapability.ArkUI.ArkUI.Full 1198 1199| Name | Value | Description| 1200| ------ | ----- | ------ | 1201| NORMAL | 0 | Normal input mode.<br>The value can contain digits, letters, underscores (_), spaces, and special characters.| 1202| NUMBER | 2 | Digit input mode. | 1203| PHONE_NUMBER | 3 | Phone number input mode.<br>In this mode, the following are allowed: digits, spaces, plus signs (+), hyphens (-), asterisks (*), and number signs (#); the length is not limited.| 1204| EMAIL | 5 | Email address input mode.<br>This mode accepts only digits, letters, underscores (_), dots (.), and the following special characters: ! # $ % & ' * + - / = ? ^ ` \{ \| \} ~ @ (which can only appear once)| 1205| NUMBER_DECIMAL<sup>12+</sup> | 12 | Number input mode with a decimal point.<br>The value can contain digits and one decimal point.| 1206| URL<sup>12+</sup> | 13 | URL input mode.| 1207 1208## TextAreaSubmitCallback<sup>14+</sup> 1209 1210type TextAreaSubmitCallback = (enterKeyType: EnterKeyType, event?: SubmitEvent) => void 1211 1212Represents the callback invoked when the Enter key on the soft keyboard is pressed. 1213 1214**Atomic service API**: This API can be used in atomic services since API version 14. 1215 1216**System capability**: SystemCapability.ArkUI.ArkUI.Full 1217 1218**Parameters** 1219 1220| Name | Type | Mandatory| Description | 1221| -------- | ------------------------------------------------------------ | ---- | -------------------------------------------------------- | 1222| enterKeyType | [EnterKeyType](ts-basic-components-textinput.md#enterkeytype) | Yes | Type of the Enter key.<br>If the type is **EnterKeyType.NEW_LINE**, **onSubmit** is not triggered.| 1223| event | [SubmitEvent](ts-basic-components-textinput.md#submitevent11) | No | Submit event. | 1224 1225## Example 1226 1227### Example 1: Setting and Obtaining the Cursor Position 1228 1229This example demonstrates how to use the controller to set and obtain the cursor position within a text box. 1230 1231```ts 1232// xxx.ets 1233@Entry 1234@Component 1235struct TextAreaExample { 1236 @State text: string = '' 1237 @State positionInfo: CaretOffset = { index: 0, x: 0, y: 0 } 1238 controller: TextAreaController = new TextAreaController() 1239 1240 build() { 1241 Column() { 1242 TextArea({ 1243 text: this.text, 1244 placeholder: 'The text area can hold an unlimited amount of text. input your word...', 1245 controller: this.controller 1246 }) 1247 .placeholderFont({ size: 16, weight: 400 }) 1248 .width(336) 1249 .height(56) 1250 .margin(20) 1251 .fontSize(16) 1252 .fontColor('#182431') 1253 .backgroundColor('#FFFFFF') 1254 .onChange((value: string) => { 1255 this.text = value 1256 }) 1257 Text(this.text) 1258 Button('Set caretPosition 1') 1259 .backgroundColor('#007DFF') 1260 .margin(15) 1261 .onClick(() => { 1262 // Move the caret to after the first entered character. 1263 this.controller.caretPosition(1) 1264 }) 1265 Button('Get CaretOffset') 1266 .backgroundColor('#007DFF') 1267 .margin(15) 1268 .onClick(() => { 1269 this.positionInfo = this.controller.getCaretOffset() 1270 }) 1271 }.width('100%').height('100%').backgroundColor('#F1F3F5') 1272 } 1273} 1274``` 1275 1276 1277 1278### Example 2: Implementing a Counter 1279 1280This example showcases the implementation of a counter feature using the **maxLength** and **showCounter** attributes. 1281 1282```ts 1283// xxx.ets 1284@Entry 1285@Component 1286struct TextAreaExample { 1287 @State text: string = '' 1288 controller: TextAreaController = new TextAreaController() 1289 1290 build() { 1291 Column() { 1292 TextArea({ 1293 text: this.text, 1294 placeholder: 'The text area can hold an unlimited amount of text. input your word...', 1295 controller: this.controller 1296 }) 1297 .placeholderFont({ size: 16, weight: 400 }) 1298 .width(336) 1299 .height(56) 1300 .margin(20) 1301 .fontSize(16) 1302 .fontColor('#182431') 1303 .backgroundColor('#FFFFFF') 1304 .maxLength(4) 1305 .showCounter(true, { thresholdPercentage: 50, highlightBorder: true }) 1306 // The character counter is in this format: Number of characters that have been entered/Maximum number of characters allowed, which is specified by maxLength(). 1307 // The character counter is displayed when the number of characters that have been entered is greater than the maximum number of characters multiplied by 50% (threshold percentage). 1308 // When highlightBorder is set to false, the text box border turns red when the number of entered characters reaches the maximum. The default value is true. 1309 .onChange((value: string) => { 1310 this.text = value 1311 }) 1312 }.width('100%').height('100%').backgroundColor('#F1F3F5') 1313 } 1314} 1315``` 1316 1317 1318 1319 1320### Example 3: Implementing a Custom Keyboard 1321 1322This example demonstrates how to implement a custom keyboard using the **customKeyboard** attribute. 1323 1324```ts 1325// xxx.ets 1326@Entry 1327@Component 1328struct TextAreaExample { 1329 controller: TextAreaController = new TextAreaController() 1330 @State inputValue: string = "" 1331 1332 // Create a custom keyboard component. 1333 @Builder CustomKeyboardBuilder() { 1334 Column() { 1335 Button('x').onClick(() => { 1336 // Disable the custom keyboard. 1337 this.controller.stopEditing() 1338 }) 1339 Grid() { 1340 ForEach([1, 2, 3, 4, 5, 6, 7, 8, 9, '*', 0, '#'], (item: number | string) => { 1341 GridItem() { 1342 Button(item + "") 1343 .width(110).onClick(() => { 1344 this.inputValue += item 1345 }) 1346 } 1347 }) 1348 }.maxCount(3).columnsGap(10).rowsGap(10).padding(5) 1349 }.backgroundColor(Color.Gray) 1350 } 1351 1352 build() { 1353 Column() { 1354 TextArea({ controller: this.controller, text: this.inputValue}) 1355 // Bind the custom keyboard. 1356 .customKeyboard(this.CustomKeyboardBuilder()).margin(10).border({ width: 1 }) 1357 .height(200) 1358 } 1359 } 1360} 1361``` 1362 1363 1364 1365### Example 4: Setting the Enter Key Type 1366 1367This example shows how to use the **enterKeyType** attribute to dynamically change the effect of the Enter key on the soft keyboard. 1368 1369```ts 1370// xxx.ets 1371@Entry 1372@Component 1373struct TextAreaExample { 1374 @State text: string = '' 1375 @State enterTypes: Array<EnterKeyType> = 1376 [EnterKeyType.Go, EnterKeyType.Search, EnterKeyType.Send, EnterKeyType.Done, EnterKeyType.Next, 1377 EnterKeyType.PREVIOUS, EnterKeyType.NEW_LINE] 1378 @State index: number = 0 1379 1380 build() { 1381 Column({ space: 20 }) { 1382 TextArea({ placeholder: 'Enter user name', text: this.text }) 1383 .width(380) 1384 .enterKeyType(this.enterTypes[this.index]) 1385 .onChange((value: string) => { 1386 this.text = value 1387 }) 1388 .onSubmit((enterKey: EnterKeyType) => { 1389 console.log("trigger area onsubmit" + enterKey); 1390 }) 1391 Button('Change EnterKeyType').onClick(() => { 1392 this.index = (this.index + 1) % this.enterTypes.length; 1393 }) 1394 1395 }.width('100%') 1396 } 1397} 1398``` 1399 1400 1401 1402 1403### Example 5: Setting Text Wrapping Rules 1404 1405This example demonstrates the effects of different text wrapping rules using the **wordBreak** attribute. 1406 1407```ts 1408// xxx.ets 1409@Entry 1410@Component 1411struct TextAreaExample { 1412 build() { 1413 Column() { 1414 Text("WordBreakType as NORMAL: ").fontSize(16).fontColor(0xFF0000) 1415 TextArea({ 1416 text: 'This is set wordBreak to WordBreak text Taumatawhakatangihangakoauauotamateaturipukakapikimaungahoronukupokaiwhenuakitanatahu.' 1417 }) 1418 .fontSize(16) 1419 .border({ width: 1 }) 1420 .wordBreak(WordBreak.NORMAL) 1421 Text("WordBreakType as BREAK_ALL: ").fontSize(16).fontColor(0xFF0000) 1422 TextArea({ 1423 text: 'This is set wordBreak to WordBreak text Taumatawhakatangihangakoauauotamateaturipukakapikimaungahoronukupokaiwhenuakitanatahu.' 1424 }) 1425 .fontSize(16) 1426 .border({ width: 1 }) 1427 .wordBreak(WordBreak.BREAK_ALL) 1428 Text("WordBreakType as BREAK_ALL: ").fontSize(16).fontColor(0xFF0000) 1429 TextArea({ 1430 text: 'The TextArea component automatically wraps text so that each line does not have more than the width of the component.\nIf the component does not have its height set, it adapts its height to the content. If the component does not have its width set, it takes the maximum available width.' 1431 }) 1432 .fontSize(16) 1433 .border({ width: 1 }) 1434 .wordBreak(WordBreak.BREAK_ALL) 1435 Text("WordBreakType as BREAK_WORD: ").fontSize(16).fontColor(0xFF0000) 1436 TextArea({ 1437 text: 'This is set wordBreak to WordBreak text Taumatawhakatangihangakoauauotamateaturipukakapikimaungahoronukupokaiwhenuakitanatahu.' 1438 }) 1439 .fontSize(16) 1440 .border({ width: 1 }) 1441 .wordBreak(WordBreak.BREAK_WORD) 1442 } 1443 } 1444} 1445``` 1446 1447 1448 1449### Example 6: Setting the Text Style 1450 1451This example showcases various text styles by using the **lineHeight**, **letterSpacing**, and **decoration** attributes. 1452 1453```ts 1454// xxx.ets 1455@Entry 1456@Component 1457struct TextAreaExample { 1458 build() { 1459 Row() { 1460 Column() { 1461 Text('lineHeight').fontSize(9).fontColor(0xCCCCCC) 1462 TextArea({ text: 'lineHeight unset' }) 1463 .border({ width: 1 }).padding(10).margin(5) 1464 TextArea({ text: 'lineHeight 15' }) 1465 .border({ width: 1 }).padding(10).margin(5).lineHeight(15) 1466 TextArea({ text: 'lineHeight 30' }) 1467 .border({ width: 1 }).padding(10).margin(5).lineHeight(30) 1468 1469 Text('letterSpacing').fontSize(9).fontColor(0xCCCCCC) 1470 TextArea({ text: 'letterSpacing 0' }) 1471 .border({ width: 1 }).padding(5).margin(5).letterSpacing(0) 1472 TextArea({ text: 'letterSpacing 3' }) 1473 .border({ width: 1 }).padding(5).margin(5).letterSpacing(3) 1474 TextArea({ text: 'letterSpacing -1' }) 1475 .border({ width: 1 }).padding(5).margin(5).letterSpacing(-1) 1476 1477 Text('decoration').fontSize(9).fontColor(0xCCCCCC) 1478 TextArea({ text: 'LineThrough, Red\nsecond line' }) 1479 .border({ width: 1 }).padding(5).margin(5) 1480 .decoration({ type: TextDecorationType.LineThrough, color: Color.Red }) 1481 TextArea({ text: 'Overline, Red, DOTTED\nsecond line' }) 1482 .border({ width: 1 }).padding(5).margin(5) 1483 .decoration({ type: TextDecorationType.Overline, color: Color.Red, style: TextDecorationStyle.DOTTED }) 1484 TextArea({ text: 'Underline, Red, WAVY\nsecond line' }) 1485 .border({ width: 1 }).padding(5).margin(5) 1486 .decoration({ type: TextDecorationType.Underline, color: Color.Red, style: TextDecorationStyle.WAVY }) 1487 }.height('90%') 1488 } 1489 .width('90%') 1490 .margin(10) 1491 } 1492} 1493``` 1494 1495 1496 1497### Example 7: Setting Text Feature Effects 1498 1499This example demonstrates how to use the **fontFeature** attribute to display text with various typographic features. 1500 1501```ts 1502// xxx.ets 1503@Entry 1504@Component 1505struct TextAreaExample { 1506 @State text1: string = 'This is ss01 on : 0123456789' 1507 @State text2: string = 'This is ss01 off: 0123456789' 1508 1509 build() { 1510 Column() { 1511 TextArea({ text: this.text1 }) 1512 .fontSize(20) 1513 .margin({ top: 200 }) 1514 .fontFeature("\"ss01\" on") 1515 TextArea({ text: this.text2 }) 1516 .margin({ top: 10 }) 1517 .fontSize(20) 1518 .fontFeature("\"ss01\" off") 1519 } 1520 .width("90%") 1521 .margin("5%") 1522 } 1523} 1524``` 1525 1526 1527### Example 8: Setting Custom Keyboard Avoidance 1528 1529This example illustrates the implementation of a custom keyboard that automatically adjusts its position to avoid covering the text box. 1530 1531```ts 1532// xxx.ets 1533@Entry 1534@Component 1535struct TextAreaExample { 1536 controller: TextAreaController = new TextAreaController() 1537 @State inputValue: string = "" 1538 @State height1: string | number = '80%' 1539 @State height2: number = 100 1540 @State supportAvoidance: boolean = true; 1541 1542 // Create a custom keyboard component. 1543 @Builder 1544 CustomKeyboardBuilder() { 1545 Column() { 1546 Row() { 1547 Button('x').onClick(() => { 1548 // Disable the custom keyboard. 1549 this.controller.stopEditing() 1550 }).margin(10) 1551 } 1552 1553 Grid() { 1554 ForEach([1, 2, 3, 4, 5, 6, 7, 8, 9, '*', 0, '#'], (item: number | string) => { 1555 GridItem() { 1556 Button(item + "") 1557 .width(110).onClick(() => { 1558 this.inputValue += item 1559 }) 1560 } 1561 }) 1562 }.maxCount(3).columnsGap(10).rowsGap(10).padding(5) 1563 }.backgroundColor(Color.Gray) 1564 } 1565 1566 build() { 1567 Column() { 1568 Row() { 1569 Button("20%") 1570 .fontSize(24) 1571 .onClick(() => { 1572 this.height1 = "20%" 1573 }) 1574 Button("80%") 1575 .fontSize(24) 1576 .margin({ left: 20 }) 1577 .onClick(() => { 1578 this.height1 = "80%" 1579 }) 1580 } 1581 .justifyContent(FlexAlign.Center) 1582 .alignItems(VerticalAlign.Bottom) 1583 .height(this.height1) 1584 .width("100%") 1585 .padding({ bottom: 50 }) 1586 1587 TextArea({ controller: this.controller, text: this.inputValue }) 1588 .height(100) 1589 .customKeyboard(this.CustomKeyboardBuilder(), { supportAvoidance: this.supportAvoidance })// Bind a custom keyboard. 1590 .margin(10) 1591 .border({ width: 1 }) 1592 } 1593 } 1594} 1595``` 1596 1597 1598### Example 9: Setting Text Auto-Adaptation 1599 1600This example showcases the implementation of text auto-adaptation features using the **minFontSize**, **maxFontSize**, and **heightAdaptivePolicy** attributes. 1601 1602```ts 1603// xxx.ets 1604@Entry 1605@Component 1606struct TextAreaExample { 1607 build() { 1608 Row() { 1609 Column() { 1610 Text('heightAdaptivePolicy').fontSize(9).fontColor(0xCCCCCC) 1611 TextArea({text: 'This is the text with the height adaptive policy set'}) 1612 .width('80%').height(90).borderWidth(1).margin(1) 1613 .minFontSize(4) 1614 .maxFontSize(40) 1615 .maxLines(3) 1616 .heightAdaptivePolicy(TextHeightAdaptivePolicy.MAX_LINES_FIRST) 1617 TextArea({text: 'This is the text with the height adaptive policy set'}) 1618 .width('80%').height(90).borderWidth(1).margin(1) 1619 .minFontSize(4) 1620 .maxFontSize(40) 1621 .maxLines(3) 1622 .heightAdaptivePolicy(TextHeightAdaptivePolicy.MIN_FONT_SIZE_FIRST) 1623 TextArea({text: 'This is the text with the height adaptive policy set'}) 1624 .width('80%').height(90).borderWidth(1).margin(1) 1625 .minFontSize(4) 1626 .maxFontSize(40) 1627 .maxLines(3) 1628 .heightAdaptivePolicy(TextHeightAdaptivePolicy.LAYOUT_CONSTRAINT_FIRST) 1629 }.height('90%') 1630 } 1631 .width('90%') 1632 .margin(10) 1633 } 1634} 1635``` 1636 1637 1638 1639### Example 10: Setting the Text Line Spacing 1640 1641This example demonstrates how to use the **lineSpacing** attribute to set different line spacing values for text presentation. 1642 1643```ts 1644// xxx.ets 1645import { LengthMetrics } from '@kit.ArkUI' 1646 1647@Entry 1648@Component 1649struct TextAreaExample { 1650 build() { 1651 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start, justifyContent: FlexAlign.SpaceBetween }) { 1652 Text('TextArea lineSpacing.').fontSize(9).fontColor(0xCCCCCC) 1653 TextArea({ text: 'This is the TextArea with no lineSpacing set.' }) 1654 .fontSize(12) 1655 TextArea({ text: 'This is the TextArea with lineSpacing set to 20_px.' }) 1656 .fontSize(12) 1657 .lineSpacing(LengthMetrics.px(20)) 1658 TextArea({ text: 'This is the TextArea with lineSpacing set to 20_vp.' }) 1659 .fontSize(12) 1660 .lineSpacing(LengthMetrics.vp(20)) 1661 TextArea({ text: 'This is the TextArea with lineSpacing set to 20_fp.' }) 1662 .fontSize(12) 1663 .lineSpacing(LengthMetrics.fp(20)) 1664 TextArea({ text: 'This is the TextArea with lineSpacing set to 20_lpx.' }) 1665 .fontSize(12) 1666 .lineSpacing(LengthMetrics.lpx(20)) 1667 TextArea({ text: 'This is the TextArea with lineSpacing set to 100%.' }) 1668 .fontSize(12) 1669 .lineSpacing(LengthMetrics.percent(1)) 1670 }.height(600).width(350).padding({ left: 35, right: 35, top: 35 }) 1671 } 1672} 1673``` 1674 1675 1676 1677### Example 11: Setting Autofill 1678 1679This example illustrates how to implement the autofill feature for text input using the **contentType** and **enableAutoFill** attributes. 1680 1681```ts 1682// xxx.ets 1683@Entry 1684@Component 1685struct TextAreaExample { 1686 @State text: string = '' 1687 1688 build() { 1689 Column() { 1690 // Email address autofill. 1691 TextArea({ placeholder: 'input your email...' }) 1692 .width('95%') 1693 .height(40) 1694 .margin(20) 1695 .contentType(ContentType.EMAIL_ADDRESS) 1696 .enableAutoFill(true) 1697 .maxLength(20) 1698 // Full street address autofill. 1699 TextArea({ placeholder: 'input your street address...' }) 1700 .width('95%') 1701 .height(40) 1702 .margin(20) 1703 .contentType(ContentType.FULL_STREET_ADDRESS) 1704 .enableAutoFill(true) 1705 .maxLength(20) 1706 }.width('100%').height('100%').backgroundColor('#F1F3F5') 1707 } 1708} 1709``` 1710 1711 1712 1713### Example 12: Setting Line Break Rules 1714 1715This example demonstrates the effects of different line break rules using the **wordBreak** attribute. 1716 1717```ts 1718// xxx.ets 1719@Entry 1720@Component 1721struct TextAreaExample { 1722 @State message1: string = 1723 "They can be classified as built-in components–those directly provided by the ArkUI framework and custom components – those defined by developers" + 1724 "The built-in components include buttons radio buttonsprogress indicators and text You can set the rendering effectof thesecomponents in method chaining mode," + 1725 "page components are divided into independent UI units to implementindependent creation development and reuse of different units on pages making pages more engineering-oriented." 1726 @State lineBreakStrategyIndex: number = 0 1727 @State lineBreakStrategy: LineBreakStrategy[] = 1728 [LineBreakStrategy.GREEDY, LineBreakStrategy.HIGH_QUALITY, LineBreakStrategy.BALANCED] 1729 @State lineBreakStrategyStr: string[] = ['GREEDY', 'HIGH_QUALITY', 'BALANCED'] 1730 1731 build() { 1732 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start }) { 1733 Text('lineBreakStrategy').fontSize(9).fontColor(0xCCCCCC) 1734 TextArea({ text: this.message1 }) 1735 .fontSize(12) 1736 .border({ width: 1 }) 1737 .padding(10) 1738 .width('100%') 1739 .lineBreakStrategy(this.lineBreakStrategy[this.lineBreakStrategyIndex]) 1740 Row() { 1741 Button('Current lineBreakStrategy value: ' + this.lineBreakStrategyStr[this.lineBreakStrategyIndex]).onClick(() => { 1742 this.lineBreakStrategyIndex++ 1743 if (this.lineBreakStrategyIndex > (this.lineBreakStrategyStr.length - 1)) { 1744 this.lineBreakStrategyIndex = 0 1745 } 1746 }) 1747 }.padding({ top: 10 }) 1748 }.height(700).width(370).padding({ left: 35, right: 35, top: 35 }) 1749 } 1750} 1751``` 1752 1753 1754 1755### Example 13: Setting Insert and Delete Callbacks 1756 1757This example showcases the implementation of insert and delete operations using the **onWillInsert**, **onDidInsert**, **onWillDelete**, and **onDidDelete** APIs. 1758 1759```ts 1760// xxx.ets 1761@Entry 1762@Component 1763struct TextAreaExample { 1764 @State insertValue: string = "" 1765 @State deleteValue: string = "" 1766 @State insertOffset: number = 0 1767 @State deleteOffset: number = 0 1768 @State deleteDirection: number = 0 1769 1770 build() { 1771 Row() { 1772 Column() { 1773 TextArea({ text: "Insert callbacks" }) 1774 .width(300) 1775 .height(60) 1776 .onWillInsert((info: InsertValue) => { 1777 this.insertValue = info.insertValue 1778 return true; 1779 }) 1780 .onDidInsert((info: InsertValue) => { 1781 this.insertOffset = info.insertOffset 1782 }) 1783 1784 Text("insertValue:" + this.insertValue + " insertOffset:" + this.insertOffset).height(30) 1785 1786 TextArea({ text: "Delete callbacks" }) 1787 .width(300) 1788 .height(60) 1789 .onWillDelete((info: DeleteValue) => { 1790 this.deleteValue = info.deleteValue 1791 info.direction 1792 return true; 1793 }) 1794 .onDidDelete((info: DeleteValue) => { 1795 this.deleteOffset = info.deleteOffset 1796 this.deleteDirection = info.direction 1797 }) 1798 1799 Text("deleteValue:" + this.deleteValue + " deleteOffset:" + this.deleteOffset).height(30) 1800 Text("deleteDirection:" + (this.deleteDirection == 0 ? "BACKWARD" : "FORWARD")).height(30) 1801 1802 }.width('100%') 1803 } 1804 .height('100%') 1805 } 1806} 1807``` 1808 1809 1810 1811### Example 14: Setting Custom Menu Extensions 1812 1813This example demonstrates how to use the **editMenuOptions** API to create custom menu extensions for text settings. It includes customizing text content, icons, and callbacks for these extensions. 1814 1815```ts 1816// xxx.ets 1817@Entry 1818@Component 1819struct TextAreaExample { 1820 @State text: string = 'TextArea editMenuOptions' 1821 onCreateMenu = (menuItems: Array<TextMenuItem>) => { 1822 let item1: TextMenuItem = { 1823 content: 'Custom 1', 1824 icon: $r('app.media.startIcon'), 1825 id: TextMenuItemId.of('Custom 1'), 1826 } 1827 let item2: TextMenuItem = { 1828 content: 'Custom 2', 1829 id: TextMenuItemId.of('Custom 2'), 1830 icon: $r('app.media.startIcon'), 1831 } 1832 menuItems.push(item1) 1833 menuItems.unshift(item2) 1834 return menuItems 1835 } 1836 onMenuItemClick = (menuItem: TextMenuItem, textRange: TextRange) => { 1837 if (menuItem.id.equals(TextMenuItemId.of("custom2"))) { 1838 console.log("Intercept id: custom2 start:" + textRange.start + "; end:" + textRange.end) 1839 return true 1840 } 1841 if (menuItem.id.equals(TextMenuItemId.COPY)) { 1842 console.log("Intercept COPY start:" + textRange.start + "; end:" + textRange.end) 1843 return true 1844 } 1845 if (menuItem.id.equals(TextMenuItemId.SELECT_ALL)) { 1846 console.log("Do not intercept SELECT_ALL start:" + textRange.start + "; end:" + textRange.end) 1847 return false 1848 } 1849 return false 1850 } 1851 @State editMenuOptions: EditMenuOptions = { 1852 onCreateMenu: this.onCreateMenu, onMenuItemClick: this.onMenuItemClick 1853 } 1854 1855 build() { 1856 Column() { 1857 TextArea({ text: this.text }) 1858 .width('95%') 1859 .height(56) 1860 .editMenuOptions(this.editMenuOptions) 1861 .margin({ top: 100 }) 1862 } 1863 .width("90%") 1864 .margin("5%") 1865 } 1866} 1867``` 1868 1869 1870 1871### Example 15: Setting Text Overflow 1872 1873This example demonstrates how to use **textOverflow**, **ellipsisMode**, and **maxlines** to display excess content with an ellipsis (...) when the text is too long. 1874 1875```ts 1876// xxx.ets 1877@Entry 1878@Component 1879struct EllipsisModeExample { 1880 @State textIndex: number = 0 1881 @State text: string = "As the sun begins to set, casting a warm golden hue across the sky," + 1882 "the world seems to slow down and breathe a sigh of relief. The sky is painted with hues of orange, " + 1883 " pink, and lavender, creating a breath taking tapestry that stretches as far as the eye can see." + 1884 "The air is filled with the sweet scent of blooming flowers, mingling with the earthy aroma of freshly turned soil." 1885 @State ellipsisModeIndex: number = 0 1886 @State ellipsisMode: (EllipsisMode | undefined | null)[] = 1887 [EllipsisMode.START, EllipsisMode.END, EllipsisMode.CENTER, undefined, null] 1888 @State ellipsisModeStr: string[] = ['START ', 'END', 'CENTER', 'undefined', 'null'] 1889 @State textOverflowIndex: number = 0 1890 @State textOverflow: TextOverflow[] = [TextOverflow.Ellipsis, TextOverflow.Clip] 1891 @State textOverflowStr: string[] = ['Ellipsis', 'Clip'] 1892 @State maxLinesIndex: number = 0 1893 @State maxLines: number[] = [1, 2, 3] 1894 @State maxLinesStr: string[] = ['1', '2', '3'] 1895 @State styleAreaIndex: number = 0 1896 @State styleArea: TextContentStyle[] = [TextContentStyle.INLINE, TextContentStyle.DEFAULT] 1897 @State styleAreaStr: string[] = ['Inline', 'Default'] 1898 1899 build() { 1900 Column() { 1901 TextArea({ text: this.text }) 1902 .textOverflow(this.textOverflow[this.textOverflowIndex]) 1903 .ellipsisMode(this.ellipsisMode[this.ellipsisModeIndex]) 1904 .maxLines(this.maxLines[this.maxLinesIndex]) 1905 .style(this.styleArea[this.styleAreaIndex]) 1906 .fontSize(30) 1907 .margin(30) 1908 1909 Button('ellipsisMode Value: ' + this.ellipsisModeStr[this.ellipsisModeIndex]).onClick(() => { 1910 this.ellipsisModeIndex++ 1911 if (this.ellipsisModeIndex > (this.ellipsisModeStr.length - 1)) { 1912 this.ellipsisModeIndex = 0 1913 } 1914 }).fontSize(20) 1915 Button('textOverflow Value: ' + this.textOverflowStr[this.textOverflowIndex]).onClick(() => { 1916 this.textOverflowIndex++ 1917 if (this.textOverflowIndex > (this.textOverflowStr.length - 1)) { 1918 this.textOverflowIndex = 0 1919 } 1920 }).fontSize(20) 1921 Button('maxLines Value: ' + this.maxLinesStr[this.maxLinesIndex]).onClick(() => { 1922 this.maxLinesIndex++ 1923 if (this.maxLinesIndex > (this.maxLinesStr.length - 1)) { 1924 this.maxLinesIndex = 0 1925 } 1926 }).fontSize(20) 1927 Button('Style Value: ' + this.styleAreaStr[this.styleAreaIndex]).onClick(() => { 1928 1929 this.styleAreaIndex++ 1930 if (this.styleAreaIndex > (this.styleAreaStr.length - 1)) { 1931 this.styleAreaIndex = 0 1932 } 1933 }).fontSize(20) 1934 }.height(600).width('100%').padding({ left: 35, right: 35, top: 35 }) 1935 } 1936} 1937``` 1938 1939 1940 1941### Example 16: Implementing Custom Copy, Cut, and Paste Behavior 1942 1943This example demonstrates how to listen for the copy, cut, and paste buttons in the text selection menu, how to disable the system paste functionality, and how to implement custom paste behavior. 1944 1945```ts 1946// xxx.ets 1947@Entry 1948@Component 1949struct TextAreaExample { 1950 @State text: string = '' 1951 controller: TextAreaController = new TextAreaController() 1952 1953 build() { 1954 Column() { 1955 TextArea({ 1956 text: this.text, 1957 placeholder: 'placeholder', 1958 controller: this.controller 1959 }) 1960 .placeholderColor(Color.Red) 1961 .textAlign(TextAlign.Center) 1962 .caretColor(Color.Green) 1963 .caretStyle({ width: '2vp' }) 1964 .fontStyle(FontStyle.Italic) 1965 .fontWeight(FontWeight.Bold) 1966 .fontFamily('HarmonyOS Sans') 1967 .inputFilter('[a-zA-Z]+', (value) => { // Only alphabetic input is allowed. 1968 console.error(`unsupport char ${value}`) 1969 }) 1970 .copyOption(CopyOptions.LocalDevice) 1971 .enableKeyboardOnFocus(false) 1972 .selectionMenuHidden(false) 1973 .barState(BarState.On) 1974 .type(TextAreaType.NORMAL) 1975 .selectedBackgroundColor(Color.Orange) 1976 .textIndent(2) 1977 .halfLeading(true) 1978 .minFontScale(1) 1979 .maxFontScale(2) 1980 .enablePreviewText(true) 1981 .enableHapticFeedback(true) 1982 .stopBackPress(false)// Delegate back press to other components. 1983 .width(336) 1984 .height(56) 1985 .margin(20) 1986 .fontSize(16) 1987 .onEditChange((isEditing: boolean) => { 1988 console.log(`isEditing ${isEditing}`) 1989 }) 1990 .onCopy((value) => { 1991 console.log(`copy ${value}`) 1992 }) 1993 .onCut((value) => { 1994 console.log(`cut ${value}`) 1995 }) 1996 .onPaste((value, event) => { 1997 // Prevent the default system paste behavior and implement custom logic. 1998 if (event.preventDefault) { 1999 event.preventDefault() 2000 } 2001 console.log(`paste:${value}`) 2002 this.text = value 2003 }) 2004 .onTextSelectionChange((start: number, end: number) => { 2005 console.log(`onTextSelectionChange start ${start}, end ${end}`) 2006 }) 2007 .onContentScroll((totalOffsetX: number, totalOffsetY: number) => { 2008 console.log(`onContentScroll offsetX ${totalOffsetX}, offsetY ${totalOffsetY}`) 2009 }) 2010 }.width('100%').height('100%').backgroundColor('#F1F3F5') 2011 } 2012} 2013``` 2014 2015 2016### Example 17: Setting the Minimum and Maximum Font Scale Factor 2017 2018This example demonstrates how to set the minimum and maximum font scale factor using **minFontScale** and **maxFontScale**. 2019 2020```ts 2021import { abilityManager, Configuration } from '@kit.AbilityKit'; 2022import { BusinessError } from '@kit.BasicServicesKit'; 2023 2024// xxx.ets 2025@Entry 2026@Component 2027export struct TextAreaExample11 { 2028 @State minFontScale: number = 0.85; 2029 @State maxFontScale: number = 2; 2030 @State changeValue: string = 'abcde'; 2031 2032 build() { 2033 Column() { 2034 Column({ space: 30 }) { 2035 Text("System font size changes: small and large, small and large") 2036 TextArea({ 2037 placeholder: 'The text area can hold an unlimited amount of text. input your word...', 2038 }) 2039 // Set the minimum font scale factor; if the value is undefined, the text follows the default font scale factor. 2040 .minFontScale(0.85) 2041 // Set the maximum font scale factor; if the value is undefined, the text follows the default font scale factor. 2042 .maxFontScale(2) 2043 }.width('100%') 2044 } 2045 } 2046} 2047``` 2048 2049```ts 2050Create a new directory named profile in the following path: AppScope/resources/base. 2051Inside the newly created profile directory, create a file named configuration.json. 2052Add the following JSON code to the configuration.json file: 2053{ 2054 "configuration":{ 2055 "fontSizeScale": "followSystem", 2056 "fontSizeMaxScale": "3.2" 2057} 2058} 2059``` 2060 2061```ts 2062Modify the app.json5 file in AppScope as follows: 2063{ 2064 "app": { 2065 "bundleName": "com.example.myapplication", 2066 "vendor": "example", 2067 "versionCode": 1000000, 2068 "versionName": "1.0.0", 2069 "icon": "$media:app_icon", 2070 "label": "$string:app_name", 2071 "configuration": "$profile:configuration" 2072 } 2073} 2074``` 2075
