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 5> **NOTE** 6> 7> This component is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. 8 9 10## Child Components 11 12Not supported 13 14 15## APIs 16 17TextArea(value?:{placeholder?: ResourceStr, text?: ResourceStr, controller?: TextAreaController}) 18 19**Parameters** 20 21| Name | Type | Mandatory | Description | 22| ----------------------- | ---------------------------------------- | ---- | -------------- | 23| placeholder | [ResourceStr](ts-types.md#resourcestr) | No | Placeholder text displayed when there is no input. | 24| text | [ResourceStr](ts-types.md#resourcestr) | No | Current text input. | 25| controller<sup>8+</sup> | [TextAreaController](#textareacontroller8) | No | Text area controller.| 26 27 28## Attributes 29 30In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported. 31 32| Name | Type | Description | 33| ------------------------ | ---------------------------------------- | ---------------------------------------- | 34| placeholderColor | [ResourceColor](ts-types.md#resourcecolor) | Placeholder text color. | 35| placeholderFont | [Font](ts-types.md#font) | Placeholder text style. | 36| textAlign | [TextAlign](ts-appendix-enums.md#textalign) | Horizontal alignment of the text.<br>Default value: **TextAlign.Start**| 37| caretColor | [ResourceColor](ts-types.md#resourcecolor) | Color of the caret in the text box. | 38| inputFilter<sup>8+</sup> | {<br>value: [ResourceStr](ts-types.md#resourcestr),<br>error?: (value: string) => void<br>} | 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.<br>- **value**: regular expression to set.<br>- **error**: filtered-out content to return when regular expression matching fails.| 39| copyOption<sup>9+</sup> | [CopyOptions](ts-appendix-enums.md#copyoptions9) | Whether copy and paste is allowed.<br>If this attribute is set to **CopyOptions.None**, the paste operation is allowed, but not the copy or cut operation.| 40 41 42## Events 43 44In addition to the [universal events](ts-universal-events-click.md), the following events are supported. 45 46| Name | Description | 47| ------------------------------------------------------------ | ------------------------------------------------------------ | 48| onChange(callback: (value: string) => void) | Triggered when the input in the text box changes.<br>- **value**: text entered. | 49| onCopy<sup>8+</sup>(callback:(value: string) => void) | Triggered when the copy button on the pasteboard, which displays when the text box is long pressed, is clicked.<br>- **value**: text to be copied.| 50| onCut<sup>8+</sup>(callback:(value: string) => void) | Triggered when the cut button on the pasteboard, which displays when the text box is long pressed, is clicked.<br>- **value**: text to be cut.| 51| onPaste<sup>8+</sup>(callback:(value: string) => void) | Triggered when the paste button on the pasteboard, which displays when the text box is long pressed, is clicked.<br>- **value**: text to be pasted.| 52 53## TextAreaController<sup>8+</sup> 54 55Defines the controller for controlling the **\<TextArea>** component. Currently, the controller can be used to control the caret position. 56 57### Objects to Import 58 59``` 60controller: TextAreaController = new TextAreaController() 61``` 62 63### caretPosition<sup>8+</sup> 64 65caretPosition(value: number): void 66 67Sets the position of the caret. 68 69**Parameters** 70 71| Name| Type| Mandatory| Description | 72| ------ | -------- | ---- | -------------------------------------- | 73| value | number | Yes | Length from the start of the string to the position where the caret is located.| 74 75 76## Example 77 78```ts 79// xxx.ets 80@Entry 81@Component 82struct TextAreaExample { 83 @State text: string = '' 84 controller: TextAreaController = new TextAreaController() 85 86 build() { 87 Column() { 88 TextArea({ 89 placeholder: 'The text area can hold an unlimited amount of text. input your word...', 90 controller: this.controller 91 }) 92 .placeholderFont({ size: 16, weight: 400 }) 93 .width(336) 94 .height(56) 95 .margin(20) 96 .fontSize(16) 97 .fontColor('#182431') 98 .backgroundColor('#FFFFFF') 99 .onChange((value: string) => { 100 this.text = value 101 }) 102 Text(this.text) 103 Button('Set caretPosition 1') 104 .backgroundColor('#007DFF') 105 .margin(15) 106 .onClick(() => { 107 // Move the caret to after the first entered character. 108 this.controller.caretPosition(1) 109 }) 110 }.width('100%').height('100%').backgroundColor('#F1F3F5') 111 } 112} 113``` 114 115 116
