1# TextInput 2 3The **\<TextInput>** component provides single-line text input. 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 17TextInput(value?:{placeholder?: ResourceStr, text?: ResourceStr, controller?: TextInputController}) 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.<br>If the component has [stateStyles](ts-universal-attributes-polymorphic-style.md) or any other attribute that may trigger updating configured, 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. | 25| controller<sup>8+</sup> | [TextInputController](#textinputcontroller8) | No | Text input 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| type | [InputType](#inputtype) | Input box type.<br>Default value: **InputType.Normal** | 35| placeholderColor | [ResourceColor](ts-types.md#resourcecolor) | Placeholder text color.| 36| placeholderFont | [Font](ts-types.md#font) | Placeholder text font.| 37| enterKeyType | EnterKeyType | Type of the Enter key. Currently, only the default value is supported.<br>Default value: **EnterKeyType.Done**| 38| caretColor | [ResourceColor](ts-types.md#resourcecolor) | Color of the caret in the text box. | 39| maxLength | number | Maximum number of characters in the text input. | 40| 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 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.| 41| 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.| 42| showPasswordIcon<sup>9+</sup> | boolean | Whether to display the show password icon at the end of the password text box.<br>Default value: **true**| 43| style<sup>9+</sup> | TextInputStyle | Text input style.<br>Default value: **TextInputStyle.Default**| 44| textAlign<sup>9+</sup> | [TextAlign](ts-appendix-enums.md#textalign) | Alignment mode of the text in the text box.<br>Default value: **TextAlign.Start** | 45 46> **NOTE** 47> 48> The default value of the universal attribute [padding](ts-universal-attributes-size.md) is as follows: { top: 8 vp, right: 16 vp, bottom: 8 vp, left: 16 vp } 49 50## EnterKeyType 51 52| Name | Description | 53| ------------------- | --------- | 54| Go | The Enter key is labeled "Go." | 55| Search | The Enter key is labeled "Search." | 56| Send | The Enter key is labeled "Send." | 57| Next | The Enter key is labeled "Next."| 58| Done | The Enter key is labeled "Done." | 59 60## InputType 61 62| Name | Description | 63| ------------------ | ------------- | 64| Normal | Normal input mode.<br>The value can contain digits, letters, underscores (_), spaces, and special characters.| 65| Password | Password input mode. The value can contain digits, letters, underscores (_), spaces, and special characters. An eye icon is used to show or hide the password, and the password is hidden behind dots by default.| 66| Email | Email address input mode. The value can contain digits, letters, underscores (_), and at signs (@). Only one at sign (@) is allowed.| 67| Number | Digit input mode. | 68| PhoneNumber<sup>9+</sup> | Phone number input mode.<br>The value can contain digits, plus signs (+), hyphens (-), asterisks (*), and number signs (#). The length is not limited.| 69 70## TextInputStyle<sup>9+</sup> 71 72| Name | Description | 73| ------------------ | ------------- | 74| Default | Default style. The caret width is fixed at 1.5 vp, and the caret height is subject to the background height and font size of the selected text. | 75| Inline | Inline input style. The background height of the selected text is the same as the height of the text box.<br>This style is used in scenarios where editing and non-editing states are obvious, for example, renaming in the file list view.| 76 77## Events 78 79In addition to the [universal events](ts-universal-events-click.md), the following events are supported. 80 81| Name | Description | 82| ------------------------------------------------------------ | ------------------------------------------------------------ | 83| onChange(callback: (value: string) => void) | Triggered when the input changes.<br>**value**: text content.<br>This event is triggered when any of the following conditions is met:<br>1. Keyboard input is received.<br>2. Paste and cut is performed.<br>3. Ctrl+V is pressed. | 84| onSubmit(callback: (enterKey: EnterKeyType) => void) | Triggered when the Enter key on the keyboard is pressed. The return value is the current type of the Enter key.<br>**enterKeyType**: type of the Enter key. For details, see [EnterKeyType](#enterkeytype). | 85| onEditChanged(callback: (isEditing: boolean) => void)<sup>(deprecated)</sup> | Triggered when the input status changes. Since API version 8, **onEditChange** is recommended. | 86| onEditChange(callback: (isEditing: boolean) => void)<sup>8+</sup> | Triggered when the input status changes. When the cursor is placed in the text box, it is in the editing state. Otherwise, it is in the non-editing state. If the value of **isEditing** is **true**, text input is in progress. | 87| onCopy(callback:(value: string) => void)<sup>8+</sup> | 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. | 88| onCut(callback:(value: string) => void)<sup>8+</sup> | 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. | 89| onPaste(callback:(value: string) => void)<sup>8+</sup> | 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. | 90 91## TextInputController<sup>8+</sup> 92 93Implements the controller of the **\<TextInput>** component. 94 95### Objects to Import 96``` 97controller: TextInputController = new TextInputController() 98``` 99### caretPosition 100 101caretPosition(value: number): void 102 103Sets the position of the caret. 104 105**Parameters** 106 107| Name| Type| Mandatory| Description | 108| ------ | -------- | ---- | -------------------------------------- | 109| value | number | Yes | Length from the start of the string to the position where the caret is located.| 110 111## Example 112 113```ts 114// xxx.ets 115@Entry 116@Component 117struct TextInputExample { 118 @State text: string = '' 119 controller: TextInputController = new TextInputController() 120 121 build() { 122 Column() { 123 TextInput({ text: this.text, placeholder: 'input your word...', controller: this.controller }) 124 .placeholderColor(Color.Grey) 125 .placeholderFont({ size: 14, weight: 400 }) 126 .caretColor(Color.Blue) 127 .width(400) 128 .height(40) 129 .margin(20) 130 .fontSize(14) 131 .fontColor(Color.Black) 132 .inputFilter('[a-z]', (e) => { 133 console.log(JSON.stringify(e)) 134 }) 135 .onChange((value: string) => { 136 this.text = value 137 }) 138 Text(this.text) 139 Button('Set caretPosition 1') 140 .margin(15) 141 .onClick(() => { 142 // Move the caret to after the first entered character. 143 this.controller.caretPosition(1) 144 }) 145 // Password text box. 146 TextInput({ placeholder: 'input your password...' }) 147 .width(400) 148 .height(40) 149 .margin(20) 150 .type(InputType.Password) 151 .maxLength(9) 152 .showPasswordIcon(true) 153 // Inline-style text box. 154 TextInput({ placeholder: 'inline style' }) 155 .width(400) 156 .height(50) 157 .margin(20) 158 .borderRadius(0) 159 .style(TextInputStyle.Inline) 160 }.width('100%') 161 } 162} 163``` 164 165 166
