1# TextArea 2 3The **TextArea** component provides multi-line text input and automatically wraps text so that each line does not have more than the width of the component. 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 takes 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).| 41| controller<sup>8+</sup> | [TextAreaController](#textareacontroller8) | No | Text area controller.| 42 43 44## Attributes 45 46In addition to the [universal attributes](ts-universal-attributes-size.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. Currently, only the default font family is 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**Widget capability**: This API can be used in ArkTS widgets since API version 9. 136 137**Atomic service API**: This API can be used in atomic services since API version 11. 138 139**System capability**: SystemCapability.ArkUI.ArkUI.Full 140 141**Parameters** 142 143| Name| Type | Mandatory| Description | 144| ------ | ------------------------------------------ | ---- | ---------- | 145| value | [ResourceColor](ts-types.md#resourcecolor) | Yes | Font color.| 146 147### fontSize 148 149fontSize(value: number | string | Resource) 150 151Sets the text size. 152 153**Widget capability**: This API can be used in ArkTS widgets since API version 9. 154 155**Atomic service API**: This API can be used in atomic services since API version 11. 156 157**System capability**: SystemCapability.ArkUI.ArkUI.Full 158 159**Parameters** 160 161| Name| Type | Mandatory| Description | 162| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 163| value | [Resource](ts-types.md#resource) \| number \| string | Yes | Font size. If **fontSize** is of the number type, the unit fp is used. The default font size is 16 fp. This parameter cannot be set in percentage.| 164 165### fontStyle 166 167fontStyle(value: FontStyle) 168 169Sets the font style. 170 171**Widget capability**: This API can be used in ArkTS widgets since API version 9. 172 173**Atomic service API**: This API can be used in atomic services since API version 11. 174 175**System capability**: SystemCapability.ArkUI.ArkUI.Full 176 177**Parameters** 178 179| Name| Type | Mandatory| Description | 180| ------ | ------------------------------------------- | ---- | --------------------------------------- | 181| value | [FontStyle](ts-appendix-enums.md#fontstyle) | Yes | Font style.<br>Default value: **FontStyle.Normal**| 182 183### fontWeight 184 185fontWeight(value: number | FontWeight | string) 186 187Sets the font weight. If the value is too large, the text may be clipped depending on the font. 188 189**Widget capability**: This API can be used in ArkTS widgets since API version 9. 190 191**Atomic service API**: This API can be used in atomic services since API version 11. 192 193**System capability**: SystemCapability.ArkUI.ArkUI.Full 194 195**Parameters** 196 197| Name| Type | Mandatory| Description | 198| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 199| value | [FontWeight](ts-appendix-enums.md#fontweight) \| number \| 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**| 200 201### fontFamily 202 203fontFamily(value: string | Resource) 204 205Sets the font family. 206 207**Widget capability**: This API can be used in ArkTS widgets since API version 9. 208 209**Atomic service API**: This API can be used in atomic services since API version 11. 210 211**System capability**: SystemCapability.ArkUI.ArkUI.Full 212 213**Parameters** 214 215| Name| Type | Mandatory| Description | 216| ------ | ---------------------------------------------------- | ---- | ------------------------------------------------------------ | 217| value | [Resource](ts-types.md#resource) \| string | 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.| 218 219### inputFilter<sup>8+</sup> 220 221inputFilter(value: ResourceStr, error?: (value: string) => void) 222 223Sets 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. 224 225**Atomic service API**: This API can be used in atomic services since API version 11. 226 227**System capability**: SystemCapability.ArkUI.ArkUI.Full 228 229**Parameters** 230 231| Name| Type | Mandatory| Description | 232| ------ | -------------------------------------- | ---- | ---------------------------------- | 233| value | [ResourceStr](ts-types.md#resourcestr) | Yes | Regular expression. | 234| error | (value: string) => void | No | Filtered-out content to return when regular expression matching fails.| 235 236### copyOption<sup>9+</sup> 237 238copyOption(value: CopyOptions) 239 240Sets whether copy and paste is allowed. If this attribute is set to **CopyOptions.None**, the paste operation is allowed, but the copy and cut operations are not. 241 242Dragging is not allowed when **CopyOptions.None** is set. 243 244**Atomic service API**: This API can be used in atomic services since API version 11. 245 246**System capability**: SystemCapability.ArkUI.ArkUI.Full 247 248**Parameters** 249 250| Name| Type | Mandatory| Description | 251| ------ | ------------------------------------------------ | ---- | ------------------------------------------------------------ | 252| value | [CopyOptions](ts-appendix-enums.md#copyoptions9) | Yes | Whether copy and paste is allowed.<br>Default value: **CopyOptions.LocalDevice**| 253 254### maxLength<sup>10+</sup> 255 256maxLength(value: number) 257 258Sets 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. 259 260**Atomic service API**: This API can be used in atomic services since API version 11. 261 262**System capability**: SystemCapability.ArkUI.ArkUI.Full 263 264**Parameters** 265 266| Name| Type | Mandatory| Description | 267| ------ | ------ | ---- | ---------------------- | 268| value | number | Yes | Maximum number of characters for text input.| 269 270### showCounter<sup>10+</sup> 271 272showCounter(value: boolean, options?: InputCounterOptions) 273 274Sets the character counter displayed when the number of characters entered exceeds the threshold. 275 276**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. 277 278It 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. 279 280**Atomic service API**: This API can be used in atomic services since API version 11. 281 282**System capability**: SystemCapability.ArkUI.ArkUI.Full 283 284**Parameters** 285 286| Name | Type | Mandatory| Description | 287| --------------------- | ------------------------------------------------------------ | ---- | ---------------- | 288| value | boolean | Yes | Whether to display the character counter.| 289| options<sup>11+</sup> | [InputCounterOptions](ts-types.md#inputcounteroptions11) | No | Threshold percentage of the character counter.| 290 291### style<sup>10+</sup> 292 293style(value: TextContentStyle) 294 295Sets the polymorphic style of the text box. The inline input style is only available for the **TextAreaType.Normal** type. 296 297**Atomic service API**: This API can be used in atomic services since API version 11. 298 299**System capability**: SystemCapability.ArkUI.ArkUI.Full 300 301**Parameters** 302 303| Name| Type | Mandatory| Description | 304| ------ | ----------------------------------------------------------- | ---- | ----------------------------------------------------- | 305| value | [TextContentStyle](ts-appendix-enums.md#textcontentstyle10) | Yes | Polymorphic style of the text box.<br>Default value: **TextContentStyle.DEFAULT**| 306 307### enableKeyboardOnFocus<sup>10+</sup> 308 309enableKeyboardOnFocus(value: boolean) 310 311Sets whether to enable the input method when the component obtains focus in a way other than clicking. 312 313 314 315**Atomic service API**: This API can be used in atomic services since API version 11. 316 317**System capability**: SystemCapability.ArkUI.ArkUI.Full 318 319**Parameters** 320 321| Name| Type | Mandatory| Description | 322| ------ | ------- | ---- | ----------------------------------------------------------- | 323| value | boolean | Yes | Whether to enable the input method when the component obtains focus in a way other than clicking.<br>Default value: **true**| 324 325### selectionMenuHidden<sup>10+</sup> 326 327selectionMenuHidden(value: boolean) 328 329Sets whether to hide the system text selection menu. 330 331**Atomic service API**: This API can be used in atomic services since API version 11. 332 333**System capability**: SystemCapability.ArkUI.ArkUI.Full 334 335**Parameters** 336 337| Name| Type | Mandatory| Description | 338| ------ | ------- | ---- | ------------------------------------------------------------ | 339| value | boolean | Yes | Whether to hide the system text selection menu.<br>**true**: Tapping, long-pressing, double-tapping, triple-tapping, or right-clicking the text box will not trigger the system text selection menu.<br>**false**: Tapping, long-pressing, double-tapping, triple-tapping, or right-clicking the text box will trigger the system text selection menu.<br>Default value: **false**| 340 341### barState<sup>10+</sup> 342 343barState(value: BarState) 344 345Sets the scrollbar display mode when the text box is editable. 346 347**Atomic service API**: This API can be used in atomic services since API version 11. 348 349**System capability**: SystemCapability.ArkUI.ArkUI.Full 350 351**Parameters** 352 353| Name| Type | Mandatory| Description | 354| ------ | ----------------------------------------- | ---- | ------------------------------------------------------------ | 355| value | [BarState](ts-appendix-enums.md#barstate) | Yes | Scrollbar display mode when the text box is editable.<br>Default value: **BarState.Auto**| 356 357### maxLines<sup>10+</sup> 358 359maxLines(value: number) 360 361Sets 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. 362 363**Atomic service API**: This API can be used in atomic services since API version 11. 364 365**System capability**: SystemCapability.ArkUI.ArkUI.Full 366 367**Parameters** 368 369| Name| Type | Mandatory| Description | 370| ------ | ----------------------------------------- | ---- | ------------------------------------------------------------ | 371| 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, +∞)| 372 373### customKeyboard<sup>10+</sup> 374 375customKeyboard(value: CustomBuilder, options?: KeyboardOptions) 376 377Custom keyboard. 378 379When a custom keyboard is set, activating the text box opens the specified custom component, instead of the system input method. 380 381The 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. 382 383The 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. 384 385The custom keyboard cannot obtain the focus, but it blocks gesture events. 386 387By 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. 388 389When a custom keyboard is set, the text box does not support camera input, even when the device supports. 390 391**Atomic service API**: This API can be used in atomic services since API version 11. 392 393**System capability**: SystemCapability.ArkUI.ArkUI.Full 394 395**Parameters** 396 397| Name | Type | Mandatory| Description | 398| --------------------- | ------------------------------------------- | ---- | ------------------------------------------------------------ | 399| 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.| 400| options<sup>12+</sup> | [KeyboardOptions](ts-basic-components-richeditor.md#keyboardoptions12) | No | Whether to support keyboard avoidance. | 401 402### type<sup>11+</sup> 403 404type(value: TextAreaType) 405 406Sets the text box type. 407 408**Atomic service API**: This API can be used in atomic services since API version 12. 409 410**System capability**: SystemCapability.ArkUI.ArkUI.Full 411 412**Parameters** 413 414| Name| Type | Mandatory| Description | 415| ------ | --------------------------------------- | ---- | -------------------------------------------- | 416| value | [TextAreaType](#textareatype11) | Yes | Text box type.<br>Default value: **TextAreaType.Normal**| 417 418### enterKeyType<sup>11+</sup> 419 420enterKeyType(value: EnterKeyType) 421 422Sets the type of the Enter key. 423 424**Atomic service API**: This API can be used in atomic services since API version 12. 425 426**System capability**: SystemCapability.ArkUI.ArkUI.Full 427 428**Parameters** 429 430| Name| Type | Mandatory| Description | 431| ------ | ------------------------------------------------ | ---- | ---------------------------------------------------- | 432| value | [EnterKeyType](ts-types.md#enterkeytype) | Yes | Type of the Enter key.<br>Default value: **EnterKeyType.NEW_LINE**| 433 434### enableAutoFill<sup>12+</sup> 435 436enableAutoFill(value: boolean) 437 438Sets whether to enable autofill. 439 440**Atomic service API**: This API can be used in atomic services since API version 12. 441 442**System capability**: SystemCapability.ArkUI.ArkUI.Full 443 444**Parameters** 445 446| Name| Type | Mandatory| Description | 447| ------ | ------- | ---- | ------------------------------------------------------------ | 448| value | boolean | Yes | Whether to enable autofill.<br>**true**: enable<br>**false**: disable<br><br>Default value: **true**| 449 450### contentType<sup>12+</sup> 451 452contentType(contentType: ContentType) 453 454Sets the content type for autofill. 455 456**Atomic service API**: This API can be used in atomic services since API version 12. 457 458**System capability**: SystemCapability.ArkUI.ArkUI.Full 459 460**Parameters** 461 462| Name | Type | Mandatory| Description | 463| ----------- | ------------------------------------- | ---- | -------------- | 464| contentType | [ContentType](#contenttype12) | Yes | Content type for autofill.| 465 466### lineHeight<sup>12+</sup> 467 468lineHeight(value: number | string | Resource) 469 470Sets 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. 471 472**Atomic service API**: This API can be used in atomic services since API version 12. 473 474**System capability**: SystemCapability.ArkUI.ArkUI.Full 475 476**Parameters** 477 478| Name| Type | Mandatory| Description | 479| ------ | ------------------------------------------------------------ | ---- | ---------------- | 480| value | number \| string \| [Resource](ts-types.md#resource) | Yes | Text line height.| 481 482### decoration<sup>12+</sup> 483 484decoration(value: TextDecorationOptions) 485 486Sets the color, type, and style of the text decorative line. 487 488**Atomic service API**: This API can be used in atomic services since API version 12. 489 490**System capability**: SystemCapability.ArkUI.ArkUI.Full 491 492**Parameters** 493 494| Name| Type | Mandatory| Description | 495| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 496| 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>} | 497 498### letterSpacing<sup>12+</sup> 499 500letterSpacing(value: number | string | Resource) 501 502Sets the letter spacing for a text style. If the value specified is a percentage or 0, the default value is used. 503 504If 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. 505 506**Atomic service API**: This API can be used in atomic services since API version 12. 507 508**System capability**: SystemCapability.ArkUI.ArkUI.Full 509 510**Parameters** 511 512| Name| Type | Mandatory| Description | 513| ------ | -------------------------- | ---- | -------------- | 514| value | number \| string \| [Resource](ts-types.md#resource) | Yes | Letter spacing.| 515 516### fontFeature<sup>12+</sup> 517 518fontFeature(value: string) 519 520Sets the font feature, for example, monospaced digits. 521 522Format: normal \| \<feature-tag-value\> 523 524Format of **\<feature-tag-value\>**: \<string\> \[ \<integer\> \| on \| off ] 525 526There can be multiple **\<feature-tag-value\>** values, which are separated by commas (,). 527 528For example, the input format for monospaced clock fonts is "ss01" on. 529 530**Atomic service API**: This API can be used in atomic services since API version 12. 531 532**System capability**: SystemCapability.ArkUI.ArkUI.Full 533 534**Parameters** 535 536| Name| Type | Mandatory| Description | 537| ------ | ------ | ---- | -------------- | 538| value | string | Yes | Font feature.| 539 540For details about the supported font features, see [Font Feature List](ts-basic-components-text.md#fontfeature12). 541Font 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. 542For 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/). 543### wordBreak<sup>12+</sup> 544 545wordBreak(value: WordBreak) 546 547Sets the word break rule. This attribute does not take effect for the placeholder text. 548 549**Atomic service API**: This API can be used in atomic services since API version 12. 550 551**System capability**: SystemCapability.ArkUI.ArkUI.Full 552 553**Parameters** 554 555| Name| Type | Mandatory| Description | 556| ------ | --------------------------------------------- | ---- | --------------------------------------------- | 557| value | [WordBreak](ts-appendix-enums.md#wordbreak11) | Yes | Word break rule.<br>Default value: **WordBreak.BREAK_WORD**| 558 559> **NOTE** 560> 561> The component does not support the **clip** attribute. Therefore, setting this attribute does not affect text clipping. 562 563### selectedBackgroundColor<sup>12+</sup> 564 565selectedBackgroundColor(value: ResourceColor) 566 567Sets the background color of the selected text. If the opacity is not set, a 20% opacity will be used. 568 569**Atomic service API**: This API can be used in atomic services since API version 12. 570 571**System capability**: SystemCapability.ArkUI.ArkUI.Full 572 573**Parameters** 574 575| Name| Type | Mandatory| Description | 576| ------ | ------------------------------------------ | ---- | ------------------------------------------ | 577| value | [ResourceColor](ts-types.md#resourcecolor) | Yes | Background color of the selected text.<br>By default, a 20% opacity is applied.| 578 579### caretStyle<sup>12+</sup> 580 581caretStyle(value: CaretStyle) 582 583Sets the caret style. 584 585**Atomic service API**: This API can be used in atomic services since API version 12. 586 587**System capability**: SystemCapability.ArkUI.ArkUI.Full 588 589**Parameters** 590 591| Name| Type | Mandatory| Description | 592| ------ | ----------------------------------- | ---- | ------------ | 593| value | [CaretStyle](ts-text-common.md#caretstyle10) | Yes | Caret style.| 594 595### textIndent<sup>12+</sup> 596 597textIndent(value: Dimension) 598 599Sets the indent of the first line text. 600 601**Atomic service API**: This API can be used in atomic services since API version 12. 602 603**System capability**: SystemCapability.ArkUI.ArkUI.Full 604 605**Parameters** 606 607| Name| Type | Mandatory| Description | 608| ------ | ----------------------------------- | ---- | ---------------------------- | 609| value | [Dimension](ts-types.md#dimension10)| Yes | Indent of the first line text.<br>Default value: **0**| 610 611### textOverflow<sup>12+</sup> 612 613textOverflow(value: TextOverflow) 614 615Sets the display mode when the text is too long. 616 617In inline style, the effect of truncating text according to **maxLines** only applies when **textOverflow** is set. 618 619Text is clipped at the transition between words. To clip text in the middle of a word, set **wordBreak** to **WordBreak.BREAK_ALL**. 620 621If **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**. 622 623**Widget capability**: This API can be used in ArkTS widgets. 624 625**Atomic service API**: This API can be used in atomic services since API version 12. 626 627**System capability**: SystemCapability.ArkUI.ArkUI.Full 628 629**Parameters** 630 631| Name| Type | Mandatory| Description | 632| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 633| value | [TextOverflow](ts-appendix-enums.md#textoverflow) | Yes | Display mode when the text is too long.<br>Default value: **TextOverflow.Clip** | 634 635> **NOTE** 636> The **TextArea** component does not support the **TextOverflow.MARQUEE** mode. If this attribute is set to **TextOverflow.MARQUEE**, **TextOverflow.Clip** is used instead. 637 638### minFontSize<sup>12+</sup> 639 640minFontSize(value: number | string | Resource) 641 642Sets the minimum font size. 643 644For the setting to take effect, this attribute must be used together with [maxFontSize](#maxfontsize12) and [maxLines](#maxlines10), or layout constraint settings. 645 646When the adaptive font size is used, the **fontSize** settings do not take effect. 647 648**Atomic service API**: This API can be used in atomic services since API version 12. 649 650**System capability**: SystemCapability.ArkUI.ArkUI.Full 651 652**Parameters** 653 654| Name| Type | Mandatory| Description | 655| ------ | ------------------------------------------------------------ | ---- | ------------------ | 656| value | number \| string \| [Resource](ts-types.md#resource) | Yes | Minimum font size.| 657 658### maxFontSize<sup>12+</sup> 659 660maxFontSize(value: number | string | Resource) 661 662Sets the maximum font size. 663 664For the setting to take effect, this attribute must be used together with [minFontSize](#minfontsize12) and [maxLines](#maxlines10), or layout constraint settings. 665 666When the adaptive font size is used, the **fontSize** settings do not take effect. 667 668**Atomic service API**: This API can be used in atomic services since API version 12. 669 670**System capability**: SystemCapability.ArkUI.ArkUI.Full 671 672**Parameters** 673 674| Name| Type | Mandatory| Description | 675| ------ | ------------------------------------------------------------ | ---- | ------------------ | 676| value | number \| string \| [Resource](ts-types.md#resource) | Yes | Maximum font size.| 677 678### heightAdaptivePolicy<sup>12+</sup> 679 680heightAdaptivePolicy(value: TextHeightAdaptivePolicy) 681 682Sets how the adaptive height is determined for the text. 683 684When 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. 685If the text box is in inline input style, the font size in the editing state is different from that in the non-editing state. 686 687If 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**. 688 689If 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. 690 691**Atomic service API**: This API can be used in atomic services since API version 12. 692 693**System capability**: SystemCapability.ArkUI.ArkUI.Full 694 695**Parameters** 696 697| Name| Type | Mandatory| Description | 698| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 699| value | [TextHeightAdaptivePolicy](ts-appendix-enums.md#textheightadaptivepolicy10) | Yes | How the adaptive height is determined for the text.<br>Default value: **TextHeightAdaptivePolicy.MAX_LINES_FIRST**| 700 701### lineSpacing<sup>12+</sup> 702 703lineSpacing(value: LengthMetrics) 704 705Sets the line spacing of the text. If the value specified is less than or equal to 0, the default value **0** is used. 706 707**Atomic service API**: This API can be used in atomic services since API version 12. 708 709**System capability**: SystemCapability.ArkUI.ArkUI.Full 710 711**Parameters** 712 713| Name| Type | Mandatory| Description | 714| ------ | ------------------------------------------------------------ | ---- | ---------------- | 715| value | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) | Yes | Line spacing. Default value: **0**| 716 717### lineBreakStrategy<sup>12+</sup> 718 719lineBreakStrategy(strategy: LineBreakStrategy) 720 721Sets the line break rule. This attribute takes effect when **wordBreak** is not set to **breakAll**. Hyphens are not supported. 722 723**Atomic service API**: This API can be used in atomic services since API version 12. 724 725**System capability**: SystemCapability.ArkUI.ArkUI.Full 726 727**Parameters** 728 729| Name | Type | Mandatory| Description | 730| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------- | 731| strategy | [LineBreakStrategy](ts-appendix-enums.md#linebreakstrategy12) | Yes | Line break rule.<br>Default value: **LineBreakStrategy.GREEDY**| 732 733### editMenuOptions<sup>12+</sup> 734 735editMenuOptions(editMenu: EditMenuOptions) 736 737Sets the extended options of the custom context menu on selection, including the text content, icon, and callback. 738 739**Atomic service API**: This API can be used in atomic services since API version 12. 740 741**System capability**: SystemCapability.ArkUI.ArkUI.Full 742 743**Parameters** 744 745| Name| Type | Mandatory| Description | 746| ------ | --------------------------------------------- | ---- | --------------------------------------------- | 747| editMenu | [EditMenuOptions](ts-text-common.md#editmenuoptions) | Yes | Extended options of the custom context menu on selection.| 748 749### enablePreviewText<sup>12+</sup> 750 751enablePreviewText(enable: boolean) 752 753Sets whether to enable preview text. 754 755Preview text is in a temporary state and does not support text interception. As such, it does not trigger **onWillInsert**, **onDidInsert**, **onWillDelete**, or **onDidDelete** callbacks. 756 757**Atomic service API**: This API can be used in atomic services since API version 12. 758 759**System capability**: SystemCapability.ArkUI.ArkUI.Full 760 761**Parameters** 762 763| Name| Type | Mandatory| Description | 764| ------ | ------- | ---- | ---------------------------------- | 765| enable | boolean | Yes | Whether to enable preview text.<br>Default value: **true**| 766 767## Events 768 769In addition to the [universal events](ts-universal-events-click.md), the following events are supported. 770 771### onChange 772 773onChange(callback: EditableTextOnChangeCallback) 774 775Called when the input in the text box changes. 776 777**Atomic service API**: This API can be used in atomic services since API version 11. 778 779**System capability**: SystemCapability.ArkUI.ArkUI.Full 780 781**Parameters** 782 783| Name| Type | Mandatory| Description | 784| ------ | ------ | ---- | -------------------- | 785| callback | [EditableTextOnChangeCallback](ts-text-common.md#editabletextonchangecallback12) | Yes | Callback invoked when the input in the text box changes.| 786 787### onEditChange<sup>10+</sup> 788 789onEditChange(callback: (isEditing: boolean) => void) 790 791Called 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. 792 793**Atomic service API**: This API can be used in atomic services since API version 11. 794 795**System capability**: SystemCapability.ArkUI.ArkUI.Full 796 797**Parameters** 798 799| Name | Type | Mandatory| Description | 800| --------- | ------- | ---- | -------------------- | 801| 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.| 802 803### onCopy<sup>8+</sup> 804 805onCopy(callback: (value: string) => void) 806 807Invoked when a copy operation is performed. 808 809**Atomic service API**: This API can be used in atomic services since API version 11. 810 811**System capability**: SystemCapability.ArkUI.ArkUI.Full 812 813**Parameters** 814 815| Name| Type | Mandatory| Description | 816| ------ | ------ | ---- | ---------------- | 817| value | string | Yes | Text that is copied.| 818 819### onCut<sup>8+</sup> 820 821onCut(callback: (value: string) => void) 822 823Invoked when a cut operation is performed. 824 825**Atomic service API**: This API can be used in atomic services since API version 11. 826 827**System capability**: SystemCapability.ArkUI.ArkUI.Full 828 829**Parameters** 830 831| Name| Type | Mandatory| Description | 832| ------ | ------ | ---- | ---------------- | 833| value | string | Yes | Text that is cut.| 834 835### onPaste 836 837onPaste(callback: (value: string, event: PasteEvent) => void) 838 839Invoked when a paste operation is performed. 840 841**Atomic service API**: This API can be used in atomic services since API version 11. 842 843**System capability**: SystemCapability.ArkUI.ArkUI.Full 844 845**Parameters** 846 847| Name | Type | Mandatory| Description | 848| ------------------- | ------------------------------------------------------------ | ---- | ---------------------- | 849| value | string | Yes | Text to be pasted. | 850| event<sup>11+</sup> | [PasteEvent](ts-basic-components-richeditor.md#pasteevent11) | Yes | Custom paste event.| 851 852### onTextSelectionChange<sup>10+</sup> 853 854onTextSelectionChange(callback: (selectionStart: number, selectionEnd: number) => void) 855 856Invoked when the position of the text selection changes or when the cursor position changes during the editing state. 857 858**Atomic service API**: This API can be used in atomic services since API version 11. 859 860**System capability**: SystemCapability.ArkUI.ArkUI.Full 861 862**Parameters** 863 864| Name | Type | Mandatory| Description | 865| -------------- | ------ | ---- | --------------------------------------- | 866| selectionStart | number | Yes | Start position of the selected text. The start position of text is **0**.| 867| selectionEnd | number | Yes | End position of the selected text. | 868 869### onContentScroll<sup>10+</sup> 870 871onContentScroll(callback: (totalOffsetX: number, totalOffsetY: number) => void) 872 873Called when the text content is scrolled. 874 875**Atomic service API**: This API can be used in atomic services since API version 11. 876 877**System capability**: SystemCapability.ArkUI.ArkUI.Full 878 879**Parameters** 880 881| Name | Type | Mandatory| Description | 882| ------------ | ------ | ---- | ---------------------------------- | 883| totalOffsetX | number | Yes | Offset in the X coordinate of the text in the content area, in px.| 884| totalOffsetY | number | Yes | Offset in the Y coordinate of the text in the content area, in px.| 885 886### onSubmit<sup>11+</sup> 887 888onSubmit(callback: (enterKey: EnterKeyType) => void) 889 890Called when the Enter key on the keyboard is pressed. 891 892**Atomic service API**: This API can be used in atomic services since API version 12. 893 894**System capability**: SystemCapability.ArkUI.ArkUI.Full 895 896**Parameters** 897 898| Name | Type | Mandatory| Description | 899| -------- | ------------------------------------------------ | ---- | ------------------------------------------------------------ | 900| enterKey | [EnterKeyType](ts-types.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.| 901 902### onWillInsert<sup>12+</sup> 903 904onWillInsert(callback: Callback\<InsertValue, boolean>) 905 906Called when text is about to be inserted. 907 908**Atomic service API**: This API can be used in atomic services since API version 12. 909 910**System capability**: SystemCapability.ArkUI.ArkUI.Full 911 912**Parameters** 913 914| Name| Type | Mandatory| Description | 915| ------ | ------------------------------------------------------------ | ---- | ------------------ | 916| 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 called for text preview.<br>It is available only for system input methods.| 917 918### onDidInsert<sup>12+</sup> 919 920onDidInsert(callback: Callback\<InsertValue>) 921 922Called when text is inserted. 923 924**Atomic service API**: This API can be used in atomic services since API version 12. 925 926**System capability**: SystemCapability.ArkUI.ArkUI.Full 927 928**Parameters** 929 930| Name| Type | Mandatory| Description | 931| ------ | ------------------------------------------------------------ | ---- | ------------------ | 932| callback | Callback\<[InsertValue](ts-text-common.md#insertvalue12)> | Yes | Callback triggered when text is inserted.<br>It is available only for system input methods.| 933 934### onWillDelete<sup>12+</sup> 935 936onWillDelete(callback: Callback\<DeleteValue, boolean>) 937 938Called when text is about to be deleted. 939 940**Atomic service API**: This API can be used in atomic services since API version 12. 941 942**System capability**: SystemCapability.ArkUI.ArkUI.Full 943 944**Parameters** 945 946| Name| Type | Mandatory| Description | 947| ------ | ------------------------------------------------------------ | ---- | ------------------ | 948| 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.| 949 950### onDidDelete<sup>12+</sup> 951 952onDidDelete(callback: Callback\<DeleteValue>) 953 954Called when text is deleted. 955 956**Atomic service API**: This API can be used in atomic services since API version 12. 957 958**System capability**: SystemCapability.ArkUI.ArkUI.Full 959 960**Parameters** 961 962| Name| Type | Mandatory| Description | 963| ------ | ------------------------------------------------------------ | ---- | ------------------ | 964| callback | Callback\<[DeleteValue](ts-text-common.md#deletevalue12)> | Yes | Callback triggered when text is deleted.<br>It is available only for system input methods.| 965 966## TextAreaController<sup>8+</sup> 967 968Inherits from [TextContentControllerBase](ts-types.md#textcontentcontrollerbase10). 969 970**Atomic service API**: This API can be used in atomic services since API version 11. 971 972**System capability**: SystemCapability.ArkUI.ArkUI.Full 973 974### Objects to Import 975 976``` 977controller: TextAreaController = new TextAreaController() 978``` 979 980### constructor<sup>8+</sup> 981 982constructor() 983 984A constructor used to create a **TextAreaController** object. 985 986**Atomic service API**: This API can be used in atomic services since API version 11. 987 988**System capability**: SystemCapability.ArkUI.ArkUI.Full 989 990### caretPosition<sup>8+</sup> 991 992caretPosition(value: number): void 993 994Sets the position of the caret. 995 996**Atomic service API**: This API can be used in atomic services since API version 11. 997 998**System capability**: SystemCapability.ArkUI.ArkUI.Full 999 1000**Parameters** 1001 1002| Name| Type| Mandatory| Description | 1003| ------ | ---- | ---- | ---- | 1004| value | number | Yes | Length from the start of the string to the position where the caret is located.| 1005 1006### setTextSelection<sup>10+</sup> 1007 1008setTextSelection(selectionStart: number, selectionEnd: number, options?: SelectionOptions): void 1009 1010Sets 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**. 1011 1012**Atomic service API**: This API can be used in atomic services since API version 11. 1013 1014**System capability**: SystemCapability.ArkUI.ArkUI.Full 1015 1016**Parameters** 1017 1018| Name| Type| Mandatory| Description | 1019| ------ | ---- | ---- | ---- | 1020| 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.| 1021| 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.| 1022| 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.| 1023 1024> **NOTE** 1025> 1026> 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**. 1027> 1028> If the selected text contains an emoji, the emoji is selected when its start position is within the text selection range. 1029 1030### stopEditing<sup>10+</sup> 1031 1032stopEditing(): void 1033 1034Exits the editing state. 1035 1036**Atomic service API**: This API can be used in atomic services since API version 11. 1037 1038**System capability**: SystemCapability.ArkUI.ArkUI.Full 1039 1040## TextAreaType<sup>11+</sup> 1041 1042**Atomic service API**: This API can be used in atomic services since API version 12. 1043 1044**System capability**: SystemCapability.ArkUI.ArkUI.Full 1045 1046| Name | Value | Description| 1047| ------ | ----- | ------ | 1048| NORMAL | 0 | Normal input mode.<br>The value can contain digits, letters, underscores (_), spaces, and special characters.| 1049| NUMBER | 2 | Digit input mode. | 1050| 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.| 1051| 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)| 1052| NUMBER_DECIMAL<sup>12+</sup> | 12 | Number input mode with a decimal point.<br>The value can contain digits and one decimal point.| 1053| URL<sup>12+</sup> | 13 | URL input mode.| 1054 1055## ContentType<sup>12+</sup> 1056 1057Enumerates the content types for autofill. 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| Name | Value | Description | 1064| -------------------------- | ---- | ------------------------------------------------------------ | 1065| USER_NAME | 0 | Username. Password Vault, when enabled, can automatically save and fill in usernames.| 1066| PASSWORD | 1 | Password. Password Vault, when enabled, can automatically save and fill in passwords.| 1067| NEW_PASSWORD | 2 | New password. Password Vault, when enabled, can automatically generate a new password. | 1068| FULL_STREET_ADDRESS | 3 | Full street address. The scenario-based autofill feature, when enabled, can automatically save and fill in full street addresses.| 1069| HOUSE_NUMBER | 4 | House number. The scenario-based autofill feature, when enabled, can automatically save and fill in house numbers.| 1070| DISTRICT_ADDRESS | 5 | District and county. The scenario-based autofill feature, when enabled, can automatically save and fill in districts and counties.| 1071| CITY_ADDRESS | 6 | City. The scenario-based autofill feature, when enabled, can automatically save and fill in cities.| 1072| PROVINCE_ADDRESS | 7 | Province. The scenario-based autofill feature, when enabled, can automatically save and fill in provinces.| 1073| COUNTRY_ADDRESS | 8 | Country. The scenario-based autofill feature, when enabled, can automatically save and fill in countries.| 1074| PERSON_FULL_NAME | 9 | Full name. The scenario-based autofill feature, when enabled, can automatically save and fill in full names.| 1075| PERSON_LAST_NAME | 10 | Last name. The scenario-based autofill feature, when enabled, can automatically save and fill in last names.| 1076| PERSON_FIRST_NAME | 11 | First name. The scenario-based autofill feature, when enabled, can automatically save and fill in first names.| 1077| PHONE_NUMBER | 12 | Phone number. The scenario-based autofill feature, when enabled, can automatically save and fill in phone numbers.| 1078| PHONE_COUNTRY_CODE | 13 | Country code. The scenario-based autofill feature, when enabled, can automatically save and fill in country codes.| 1079| FULL_PHONE_NUMBER | 14 | Phone number with country code. The scenario-based autofill feature, when enabled, can automatically save and fill in phone numbers with country codes.| 1080| EMAIL_ADDRESS | 15 | Email address. The scenario-based autofill feature, when enabled, can automatically save and fill in email addresses.| 1081| BANK_CARD_NUMBER | 16 | Bank card number. The scenario-based autofill feature, when enabled, can automatically save and fill in bank card numbers.| 1082| ID_CARD_NUMBER | 17 | ID card number. The scenario-based autofill feature, when enabled, can automatically save and fill in ID card numbers.| 1083| NICKNAME | 23 | Nickname. The scenario-based autofill feature, when enabled, can automatically save and fill in nicknames.| 1084| DETAIL_INFO_WITHOUT_STREET | 24 | Address information without street address. The scenario-based autofill feature, when enabled, can automatically save and fill in address information without street addresses.| 1085| FORMAT_ADDRESS | 25 | Standard address. The scenario-based autofill feature, when enabled, can automatically save and fill in standard addresses.| 1086 1087## Example 1088 1089### Example 1 1090This example demonstrates the basic usage of **TextArea**. 1091```ts 1092// xxx.ets 1093@Entry 1094@Component 1095struct TextAreaExample { 1096 @State text: string = '' 1097 @State positionInfo: CaretOffset = { index: 0, x: 0, y: 0 } 1098 controller: TextAreaController = new TextAreaController() 1099 1100 build() { 1101 Column() { 1102 TextArea({ 1103 text: this.text, 1104 placeholder: 'The text area can hold an unlimited amount of text. input your word...', 1105 controller: this.controller 1106 }) 1107 .placeholderFont({ size: 16, weight: 400 }) 1108 .width(336) 1109 .height(56) 1110 .margin(20) 1111 .fontSize(16) 1112 .fontColor('#182431') 1113 .backgroundColor('#FFFFFF') 1114 .onChange((value: string) => { 1115 this.text = value 1116 }) 1117 Text(this.text) 1118 Button('Set caretPosition 1') 1119 .backgroundColor('#007DFF') 1120 .margin(15) 1121 .onClick(() => { 1122 // Move the caret to after the first entered character. 1123 this.controller.caretPosition(1) 1124 }) 1125 Button('Get CaretOffset') 1126 .backgroundColor('#007DFF') 1127 .margin(15) 1128 .onClick(() => { 1129 this.positionInfo = this.controller.getCaretOffset() 1130 }) 1131 }.width('100%').height('100%').backgroundColor('#F1F3F5') 1132 } 1133} 1134``` 1135 1136 1137 1138### Example 2 1139This example shows how to set the **maxLength** and **showCounter** attributes. 1140```ts 1141// xxx.ets 1142@Entry 1143@Component 1144struct TextAreaExample { 1145 @State text: string = 'test' 1146 @State counterVisible: boolean = false 1147 @State maxNumber: number = -1 1148 controller: TextAreaController = new TextAreaController() 1149 1150 build() { 1151 Column() { 1152 TextArea({ 1153 text: this.text, 1154 placeholder: 'The text area can hold an unlimited amount of text. input your word...', 1155 controller: this.controller 1156 }) 1157 .placeholderFont({ size: 16, weight: 400 }) 1158 .width(336) 1159 .height(56) 1160 .margin(20) 1161 .fontSize(16) 1162 .fontColor('#182431') 1163 .maxLength(4) 1164 .showCounter(true) 1165 .backgroundColor('#FFFFFF') 1166 .onChange((value: string) => { 1167 this.text = value 1168 }) 1169 }.width('100%').height('100%').backgroundColor('#F1F3F5') 1170 } 1171} 1172``` 1173 1174 1175 1176 1177### Example 3 1178This example illustrates how to bind a custom keyboard to the **TextArea** component. 1179```ts 1180// xxx.ets 1181@Entry 1182@Component 1183struct TextAreaExample { 1184 controller: TextAreaController = new TextAreaController() 1185 @State inputValue: string = "" 1186 1187 // Create a custom keyboard component. 1188 @Builder CustomKeyboardBuilder() { 1189 Column() { 1190 Button('x').onClick(() => { 1191 // Disable the custom keyboard. 1192 this.controller.stopEditing() 1193 }) 1194 Grid() { 1195 ForEach([1, 2, 3, 4, 5, 6, 7, 8, 9, '*', 0, '#'], (item: number | string) => { 1196 GridItem() { 1197 Button(item + "") 1198 .width(110).onClick(() => { 1199 this.inputValue += item 1200 }) 1201 } 1202 }) 1203 }.maxCount(3).columnsGap(10).rowsGap(10).padding(5) 1204 }.backgroundColor(Color.Gray) 1205 } 1206 1207 build() { 1208 Column() { 1209 TextArea({ controller: this.controller, text: this.inputValue}) 1210 // Bind the custom keyboard. 1211 .customKeyboard(this.CustomKeyboardBuilder()).margin(10).border({ width: 1 }) 1212 .height(200) 1213 } 1214 } 1215} 1216``` 1217 1218 1219 1220### Example 4 1221This example illustrates the use of a character counter with the **TextArea** component. 1222```ts 1223// xxx.ets 1224@Entry 1225@Component 1226struct TextAreaExample { 1227 @State text: string = '' 1228 controller: TextAreaController = new TextAreaController() 1229 1230 build() { 1231 Column() { 1232 TextArea({ text: this.text, controller: this.controller }) 1233 .placeholderFont({ size: 16, weight: 400 }) 1234 .width(336) 1235 .height(56) 1236 .maxLength(6) 1237 .showCounter(true, { thresholdPercentage: 50, highlightBorder: true }) 1238 // The character counter is in this format: Number of characters that have been entered/Maximum number of characters allowed, which is specified by maxLength(). 1239 // 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). 1240 // 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. 1241 .onChange((value: string) => { 1242 this.text = value 1243 }) 1244 }.width('100%').height('100%').backgroundColor('#F1F3F5') 1245 } 1246} 1247``` 1248 1249 1250 1251 1252### Example 5 1253This example shows how to set the **enterKeyType** attribute. 1254```ts 1255// xxx.ets 1256@Entry 1257@Component 1258struct TextInputExample { 1259 @State Text: string = '' 1260 @State enterTypes: Array<EnterKeyType> = [EnterKeyType.Go, EnterKeyType.Search, EnterKeyType.Send, EnterKeyType.Done, EnterKeyType.Next, EnterKeyType.PREVIOUS, EnterKeyType.NEW_LINE] 1261 @State index: number = 0 1262 build() { 1263 Column({ space: 20 }) { 1264 TextArea({ placeholder: 'Enter user name', text: this.Text }) 1265 .width(380) 1266 .enterKeyType(this.enterTypes[this.index]) 1267 .onChange((value: string) => { 1268 this.Text = value 1269 }) 1270 .onSubmit((enterKey: EnterKeyType) => { 1271 console.log("trigger area onsubmit" + enterKey); 1272 }) 1273 Button ('Change EnterKeyType').onClick () => { 1274 this.index = (this.index + 1) % this.enterTypes.length; 1275 }) 1276 1277 }.width('100%') 1278 } 1279} 1280``` 1281 1282 1283 1284 1285### Example 6 1286This example shows how to set the **wordBreak** attribute for the **TextArea** component. 1287 1288```ts 1289// xxx.ets 1290@Entry 1291@Component 1292struct TextAreaExample { 1293 build() { 1294 Column() { 1295 Text("WordBreakType as NORMAL: ").fontSize(16).fontColor(0xFF0000) 1296 TextArea({ 1297 text: 'This is set wordBreak to WordBreak text Taumatawhakatangihangakoauauotamateaturipukakapikimaungahoronukupokaiwhenuakitanatahu.' 1298 }) 1299 .fontSize(16) 1300 .border({ width: 1 }) 1301 .wordBreak(WordBreak.NORMAL) 1302 Text ("WordBreakType as BREAK_ALL") .fontSize (16).fontColor (0xFF0000) 1303 TextArea({ 1304 text: 'This is set wordBreak to WordBreak text Taumatawhakatangihangakoauauotamateaturipukakapikimaungahoronukupokaiwhenuakitanatahu.' 1305 }) 1306 .fontSize(16) 1307 .border({ width: 1 }) 1308 .wordBreak(WordBreak.BREAK_ALL) 1309 Text("WordBreakType as BREAK_WORD: ").fontSize(16).fontColor(0xFF0000) 1310 TextArea({ 1311 text: 'This is set wordBreak to WordBreak text Taumatawhakatangihangakoauauotamateaturipukakapikimaungahoronukupokaiwhenuakitanatahu.' 1312 }) 1313 .fontSize(16) 1314 .border({ width: 1 }) 1315 .wordBreak(WordBreak.BREAK_WORD) 1316 } 1317 } 1318} 1319``` 1320 1321 1322 1323### Example 7 1324 1325This example shows how to use the **lineHeight**, **letterSpacing**, and **decoration** attributes. 1326 1327```ts 1328// xxx.ets 1329@Entry 1330@Component 1331struct TextAreaExample { 1332 build() { 1333 Row() { 1334 Column() { 1335 Text('lineHeight').fontSize(9).fontColor(0xCCCCCC) 1336 TextArea({text: 'lineHeight unset'}) 1337 .border({ width: 1 }).padding(10).margin(5) 1338 TextArea({text: 'lineHeight 15'}) 1339 .border({ width: 1 }).padding(10).margin(5).lineHeight(15) 1340 TextArea({text: 'lineHeight 30'}) 1341 .border({ width: 1 }).padding(10).margin(5).lineHeight(30) 1342 1343 Text('letterSpacing').fontSize(9).fontColor(0xCCCCCC) 1344 TextArea({text: 'letterSpacing 0'}) 1345 .border({ width: 1 }).padding(5).margin(5).letterSpacing(0) 1346 TextArea({text: 'letterSpacing 3'}) 1347 .border({ width: 1 }).padding(5).margin(5).letterSpacing(3) 1348 TextArea({text: 'letterSpacing -1'}) 1349 .border({ width: 1 }).padding(5).margin(5).letterSpacing(-1) 1350 1351 Text('decoration').fontSize(9).fontColor(0xCCCCCC) 1352 TextArea({text: 'LineThrough, Red\nsecond line'}) 1353 .border({ width: 1 }).padding(5).margin(5) 1354 .decoration({type: TextDecorationType.LineThrough, color: Color.Red}) 1355 TextArea({text: 'Overline, Red, DOTTED\nsecond line'}) 1356 .border({ width: 1 }).padding(5).margin(5) 1357 .decoration({type: TextDecorationType.Overline, color: Color.Red, style: TextDecorationStyle.DOTTED}) 1358 TextArea({text: 'Underline, Red, WAVY\nsecond line'}) 1359 .border({ width: 1 }).padding(5).margin(5) 1360 .decoration({type: TextDecorationType.Underline, color: Color.Red, style: TextDecorationStyle.WAVY}) 1361 }.height('90%') 1362 } 1363 .width('90%') 1364 .margin(10) 1365 } 1366} 1367``` 1368 1369 1370 1371### Example 8 1372This example shows how to set the **fontFeature** attribute, with a comparison between the ss01-enabled and ss01-disabled effects. 1373 1374```ts 1375@Entry 1376@Component 1377struct textArea { 1378 @State text1: string = 'This is ss01 on: 0123456789' 1379 @State text2: string = 'This is ss01 off: 0123456789' 1380 1381 build() { 1382 Column(){ 1383 TextArea({text: this.text1}) 1384 .fontSize(20) 1385 .margin({top:200}) 1386 .fontFeature("\"ss01\" on") 1387 TextArea({text : this.text2}) 1388 .margin({top:10}) 1389 .fontSize(20) 1390 .fontFeature("\"ss01\" off") 1391 } 1392 .width("90%") 1393 .margin("5%") 1394 } 1395} 1396``` 1397 1398 1399### Example 9 1400 1401This example shows how to support custom keyboard avoidance. 1402 1403```ts 1404@Entry 1405@Component 1406struct TextAreaExample { 1407 controller: TextAreaController = new TextAreaController() 1408 @State inputValue: string = "" 1409 @State height1:string|number = '80%' 1410 @State height2:number = 100 1411 @State supportAvoidance:boolean = true; 1412 1413 // Create a custom keyboard component. 1414 @Builder CustomKeyboardBuilder() { 1415 Column() { 1416 Row(){ 1417 Button('x').onClick(() => { 1418 // Disable the custom keyboard. 1419 this.controller.stopEditing() 1420 }).margin(10) 1421 } 1422 Grid() { 1423 ForEach([1, 2, 3, 4, 5, 6, 7, 8, 9, '*', 0, '#'], (item: number | string) => { 1424 GridItem() { 1425 Button(item + "") 1426 .width(110).onClick(() => { 1427 this.inputValue += item 1428 }) 1429 } 1430 }) 1431 }.maxCount(3).columnsGap(10).rowsGap(10).padding(5) 1432 }.backgroundColor(Color.Gray) 1433 } 1434 1435 build() { 1436 Column() { 1437 Row(){ 1438 Button("20%") 1439 .fontSize(24) 1440 .onClick(()=>{ 1441 this.height1 = "20%" 1442 }) 1443 Button("80%") 1444 .fontSize(24) 1445 .margin({left:20}) 1446 .onClick(()=>{ 1447 this.height1 = "80%" 1448 }) 1449 } 1450 .justifyContent(FlexAlign.Center) 1451 .alignItems(VerticalAlign.Bottom) 1452 .height(this.height1) 1453 .width("100%") 1454 .padding({bottom:50}) 1455 TextArea({ controller: this.controller, text: this.inputValue}) 1456 .height(100) 1457 // Bind the custom keyboard. 1458 .customKeyboard(this.CustomKeyboardBuilder(),{ supportAvoidance: this.supportAvoidance }).margin(10).border({ width: 1 }) 1459 // .height(200) 1460 } 1461 } 1462} 1463``` 1464 1465 1466### Example 10 1467 1468This example shows how to set **minFontSize**, **maxFontSize**, and **heightAdaptivePolicy**. 1469 1470```ts 1471// xxx.ets 1472@Entry 1473@Component 1474struct TextAreaExample { 1475 build() { 1476 Row() { 1477 Column() { 1478 Text('heightAdaptivePolicy').fontSize(9).fontColor(0xCCCCCC) 1479 TextArea({text: 'This is the text with the height adaptive policy set'}) 1480 .width('80%').height(90).borderWidth(1).margin(1) 1481 .minFontSize(4) 1482 .maxFontSize(40) 1483 .maxLines(3) 1484 .heightAdaptivePolicy(TextHeightAdaptivePolicy.MAX_LINES_FIRST) 1485 TextArea({text: 'This is the text with the height adaptive policy set'}) 1486 .width('80%').height(90).borderWidth(1).margin(1) 1487 .minFontSize(4) 1488 .maxFontSize(40) 1489 .maxLines(3) 1490 .heightAdaptivePolicy(TextHeightAdaptivePolicy.MIN_FONT_SIZE_FIRST) 1491 TextArea({text: 'This is the text with the height adaptive policy set'}) 1492 .width('80%').height(90).borderWidth(1).margin(1) 1493 .minFontSize(4) 1494 .maxFontSize(40) 1495 .maxLines(3) 1496 .heightAdaptivePolicy(TextHeightAdaptivePolicy.LAYOUT_CONSTRAINT_FIRST) 1497 }.height('90%') 1498 } 1499 .width('90%') 1500 .margin(10) 1501 } 1502} 1503``` 1504 1505 1506 1507### Example 11 1508 1509This example shows how to set the **lineSpacing** attribute, with a comparison of line spacing effects. 1510 1511```ts 1512import { LengthMetrics } from '@kit.ArkUI' 1513 1514@Entry 1515@Component 1516struct LineSpacingExample { 1517 build() { 1518 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start, justifyContent: FlexAlign.SpaceBetween }) { 1519 Text('TextArea lineSpacing.').fontSize(9).fontColor(0xCCCCCC) 1520 TextArea({ placeholder: 'This is the TextArea with no lineSpacing set.' }) 1521 .fontSize(12) 1522 TextArea({ placeholder: 'This is the TextArea with lineSpacing set to 20_px.' }) 1523 .fontSize(12) 1524 .lineSpacing(LengthMetrics.px(20)) 1525 TextArea({ placeholder: 'This is the TextArea with lineSpacing set to 20_vp.' }) 1526 .fontSize(12) 1527 .lineSpacing(LengthMetrics.vp(20)) 1528 TextArea({ placeholder: 'This is the TextArea with lineSpacing set to 20_fp.' }) 1529 .fontSize(12) 1530 .lineSpacing(LengthMetrics.fp(20)) 1531 TextArea({ placeholder: 'This is the TextArea with lineSpacing set to 20_lpx.' }) 1532 .fontSize(12) 1533 .lineSpacing(LengthMetrics.lpx(20)) 1534 TextArea({ placeholder: 'This is the TextArea with lineSpacing set to 100%.' }) 1535 .fontSize(12) 1536 .lineSpacing(LengthMetrics.percent(1)) 1537 }.height(600).width(350).padding({ left: 35, right: 35, top: 35 }) 1538 } 1539} 1540``` 1541 1542 1543 1544### Example 12 1545 1546This example shows how to use autofill. 1547 1548```ts 1549// xxx.ets 1550@Entry 1551@Component 1552struct TextAreaExample { 1553 @State text: string = '' 1554 1555 build() { 1556 Column() { 1557 // Email address autofill. 1558 TextArea({ placeholder: 'input your email...' }) 1559 .width('95%') 1560 .height(40) 1561 .margin(20) 1562 .contentType(ContentType.EMAIL_ADDRESS) 1563 .enableAutoFill(true) 1564 .maxLength(20) 1565 // Full street address autofill. 1566 TextArea({ placeholder: 'input your street address...' }) 1567 .width('95%') 1568 .height(40) 1569 .margin(20) 1570 .contentType(ContentType.FULL_STREET_ADDRESS) 1571 .enableAutoFill(true) 1572 .maxLength(20) 1573 }.width('100%').height('100%').backgroundColor('#F1F3F5') 1574 } 1575} 1576``` 1577 1578 1579 1580### Example 13 1581 1582This example shows how to set the **lineBreakStrategy** attribute, with a comparison of line break rules. 1583 1584```ts 1585@Entry 1586@Component 1587struct TextExample1 { 1588 @State message1: string = "They can be classified as built-in components–those directly provided by the ArkUI framework and custom components – those defined by developers" + 1589 "The built-in components include buttons radio buttonsprogress indicators and text You can set the rendering effectof thesecomponents in method chaining mode," + 1590 "page components are divided into independent UI units to implementindependent creation development and reuse of different units on pages making pages more engineering-oriented."; 1591 1592 build() { 1593 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start }) { 1594 Text('LineBreakStrategy.GREEDY').fontSize(9).fontColor(0xCCCCCC).width('90%').padding(10) 1595 TextArea({text: this.message1}) 1596 .fontSize(12) 1597 .border({ width: 1 }) 1598 .padding(10) 1599 .width('100%') 1600 .lineBreakStrategy(LineBreakStrategy.GREEDY) 1601 Text('LineBreakStrategy.HIGH_QUALITY').fontSize(9).fontColor(0xCCCCCC).width('90%').padding(10) 1602 TextArea({text: this.message1}) 1603 .fontSize(12) 1604 .border({ width: 1 }) 1605 .padding(10) 1606 .width('100%') 1607 .lineBreakStrategy(LineBreakStrategy.HIGH_QUALITY) 1608 Text('LineBreakStrategy.BALANCED').fontSize(9).fontColor(0xCCCCCC).width('90%').padding(10) 1609 TextArea({text: this.message1}) 1610 .fontSize(12) 1611 .border({ width: 1 }) 1612 .padding(10) 1613 .width('100%') 1614 .lineBreakStrategy(LineBreakStrategy.BALANCED) 1615 }.height(700).width(370).padding({ left: 35, right: 35, top: 35 }) 1616 } 1617} 1618``` 1619 1620 1621 1622### Example 14 1623 1624This example shows how to use the insert and delete callbacks. 1625 1626```ts 1627// xxx.ets 1628@Entry 1629@Component 1630struct TextAreaExample { 1631 @State insertValue: string = "" 1632 @State deleteValue: string = "" 1633 @State insertOffset: number = 0 1634 @State deleteOffset: number = 0 1635 @State deleteDirection: number = 0 1636 1637 build() { 1638 Row() { 1639 Column() { 1640 TextArea({ text: "Insert callbacks" }) 1641 .width(300) 1642 .height(60) 1643 .onWillInsert((info: InsertValue) => { 1644 this.insertValue = info.insertValue 1645 return true; 1646 }) 1647 .onDidInsert((info: InsertValue) => { 1648 this.insertOffset = info.insertOffset 1649 }) 1650 1651 Text("insertValue:" + this.insertValue + " insertOffset:" + this.insertOffset).height(30) 1652 1653 TextArea({ text: "Delete callbacks" }) 1654 .width(300) 1655 .height(60) 1656 .onWillDelete((info: DeleteValue) => { 1657 this.deleteValue = info.deleteValue 1658 info.direction 1659 return true; 1660 }) 1661 .onDidDelete((info: DeleteValue) => { 1662 this.deleteOffset = info.deleteOffset 1663 this.deleteDirection = info.direction 1664 }) 1665 1666 Text("deleteValue:" + this.deleteValue + " deleteOffset:" + this.deleteOffset).height(30) 1667 Text("deleteDirection:" + (this.deleteDirection == 0 ? "BACKWARD" : "FORWARD")).height(30) 1668 1669 }.width('100%') 1670 } 1671 .height('100%') 1672 } 1673} 1674``` 1675 1676 1677 1678### Example 15 1679 1680This example shows how to set **editMenuOptions**. 1681 1682```ts 1683// xxx.ets 1684@Entry 1685@Component 1686struct TextAreaExample { 1687 @State text: string = 'TextArea editMenuOptions' 1688 1689 onCreateMenu(menuItems: Array<TextMenuItem>) { 1690 menuItems.forEach((value, index) => { 1691 value.icon = $r('app.media.startIcon') 1692 if (value.id.equals(TextMenuItemId.COPY)) { 1693 value.content = "Copy" 1694 } 1695 if (value.id.equals(TextMenuItemId.SELECT_ALL)) { 1696 value.content = "Select All" 1697 } 1698 }) 1699 let item1: TextMenuItem = { 1700 content: 'Custom 1', 1701 icon: $r('app.media.startIcon'), 1702 id: TextMenuItemId.of('Custom 1'), 1703 } 1704 let item2: TextMenuItem = { 1705 content: 'Custom 2', 1706 id: TextMenuItemId.of('Custom 2'), 1707 icon: $r('app.media.startIcon'), 1708 } 1709 menuItems.push(item1) 1710 menuItems.unshift(item2) 1711 return menuItems 1712 } 1713 1714 build() { 1715 Column() { 1716 TextArea({ text: this.text }) 1717 .width('95%') 1718 .height(56) 1719 .editMenuOptions({ 1720 onCreateMenu: this.onCreateMenu, onMenuItemClick: (menuItem: TextMenuItem, textRange: TextRange) => { 1721 if (menuItem.id.equals(TextMenuItemId.of("custom2"))) { 1722 console.log("Intercept id: custom2 start:" + textRange.start + "; end:" + textRange.end) 1723 return true; 1724 } 1725 if (menuItem.id.equals(TextMenuItemId.COPY)) { 1726 console.log("Intercept COPY start:" + textRange.start + "; end:" + textRange.end) 1727 return true; 1728 } 1729 if (menuItem.id.equals(TextMenuItemId.SELECT_ALL)) { 1730 console.log("Do not intercept SELECT_ALL start:" + textRange.start + "; end:" + textRange.end) 1731 return false; 1732 } 1733 return false; 1734 } 1735 }) 1736 .margin({ top: 100 }) 1737 } 1738 .width("90%") 1739 .margin("5%") 1740 } 1741} 1742``` 1743 1744 1745
