1# TextInput 2 3单行文本输入框组件。 4 5> **说明：** 6> 7> 该组件从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8 9 10## 子组件 11 12无 13 14 15## 接口 16 17TextInput(value?:{placeholder?: ResourceStr, text?: ResourceStr, controller?: TextInputController}) 18 19**参数：** 20 21| 参数名 | 参数类型 | 必填 | 参数描述 | 22| ----------------------- | ---------------------------------------- | ---- | --------------- | 23| placeholder | [ResourceStr](ts-types.md#resourcestr) | 否 | 设置无输入时的提示文本。 | 24| text | [ResourceStr](ts-types.md#resourcestr) | 否 | 设置输入框当前的文本内容。</br>当组件设置[stateStyles](ts-universal-attributes-polymorphic-style.md)等刷新属性时，建议通过onChange事件将状态变量与文本实时绑定，</br>避免组件刷新时TextInput中的文本内容异常。 | 25| controller<sup>8+</sup> | [TextInputController](#textinputcontroller8) | 否 | 设置TextInput控制器。 | 26 27 28## 属性 29 30除支持[通用属性](ts-universal-attributes-size.md)外，还支持以下属性： 31 32| 名称 | 参数类型 | 描述 | 33| ------------------------ | ---------------------------------------- | ---------------------------------------- | 34| type | [InputType](#inputtype枚举说明) | 设置输入框类型。<br/>默认值：InputType.Normal | 35| placeholderColor | [ResourceColor](ts-types.md#resourcecolor) | 设置placeholder文本颜色。| 36| placeholderFont | [Font](ts-types.md#font) | 设置placeholder文本样式。 | 37| enterKeyType | EnterKeyType | 设置输入法回车键类型，目前仅支持默认类型显示。<br/>默认值：EnterKeyType.Done | 38| caretColor | [ResourceColor](ts-types.md#resourcecolor) | 设置输入框光标颜色。 | 39| maxLength | number | 设置文本的最大输入字符数。 | 40| inputFilter<sup>8+</sup> | {<br/>value: [ResourceStr](ts-types.md#resourcestr),<br/>error?: (value: string) => void<br/>} | 正则表达式，匹配表达式的输入允许显示，不匹配的输入将被过滤。目前仅支持单个字符匹配，不支持字符串匹配。<br/>- value：设置正则表达式。<br/>- error：正则匹配失败时，返回被过滤的内容。 | 41| copyOption<sup>9+</sup> | [CopyOptions](ts-appendix-enums.md#copyoptions9) | 设置输入的文本是否可复制。<br>设置CopyOptions.None时，当前TextInput中的文字无法被复制或剪切，仅支持粘贴。 | 42| showPasswordIcon<sup>9+</sup> | boolean | 密码输入模式时，输入框末尾的图标是否显示。<br/>默认值：true | 43| style<sup>9+</sup> | TextInputStyle | 设置输入框为默认风格或内联输入风格。<br/>默认值：TextInputStyle.Default | 44| textAlign<sup>9+</sup> | [TextAlign](ts-appendix-enums.md#textalign) | 设置输入文本在输入框中的对齐方式。<br/>默认值：TextAlign.Start | 45 46> **说明：** 47> 48> [通用属性padding](ts-universal-attributes-size.md)的默认值为：<br>{<br> top: 8 vp,<br> right: 16 vp,<br> bottom: 8 vp,<br> left: 16 vp<br> } 49 50## EnterKeyType枚举说明 51 52| 名称 | 描述 | 53| ------------------- | --------- | 54| Go | 显示为前往样式。 | 55| Search | 显示为搜索样式。 | 56| Send | 显示为发送样式。 | 57| Next | 显示为下一个样式。 | 58| Done | 显示为确认样式。 | 59 60## InputType枚举说明 61 62| 名称 | 描述 | 63| ------------------ | ------------- | 64| Normal | 基本输入模式。<br/>支持输入数字、字母、下划线、空格、特殊字符。 | 65| Password | 密码输入模式。支持输入数字、字母、下划线、空格、特殊字符。密码显示小眼睛图标并且默认会将文字变成圆点。 | 66| Email | 邮箱地址输入模式。支持数字，字母，下划线，以及@字符（只能存在一个@字符）。 | 67| Number | 纯数字输入模式。 | 68| PhoneNumber<sup>9+</sup> | 电话号码输入模式。<br/>支持输入数字、+ 、-、*、#，长度不限。 | 69 70## TextInputStyle<sup>9+</sup>枚举说明 71 72| 名称 | 描述 | 73| ------------------ | ------------- | 74| Default | 默认风格，光标宽1.5vp，光标高度与文本选中底板高度和字体大小相关。 | 75| Inline | 内联输入风格。文本选中底板高度与输入框高度相同。 | 76 77## 事件 78 79除支持[通用事件](ts-universal-events-click.md)外，还支持以下事件： 80 81| 名称 | 功能描述 | 82| ------------------------------------------------------------ | ------------------------------------------------------------ | 83| onChange(callback: (value: string) => void) | 输入内容发生变化时，触发该回调。<br/>value：输入的文本内容。<br/>触发该事件的条件：<br/>1、键盘输入。<br/>2、粘贴、剪切。<br/>3、键盘快捷键Ctrl+v。 | 84| onSubmit(callback: (enterKey: EnterKeyType) => void) | 按下输入法回车键触发该回调，返回值为当前输入法回车键的类型。<br/>enterKeyType：输入法回车键类型。具体类型见[EnterKeyType枚举说明](#enterkeytype枚举说明)。 | 85| onEditChanged(callback: (isEditing: boolean) => void)<sup>(deprecated)</sup> | 输入状态变化时，触发该回调。从API 8开始，建议使用onEditChange。 | 86| onEditChange(callback: (isEditing: boolean) => void)<sup>8+</sup> | 输入状态变化时，触发该回调。有光标时为编辑态，无光标时为非编辑态。isEditing为true表示正在输入。 | 87| onCopy(callback:(value: string) => void)<sup>8+</sup> | 长按输入框内部区域弹出剪贴板后，点击剪切板复制按钮，触发该回调。<br/>value：复制的文本内容。 | 88| onCut(callback:(value: string) => void)<sup>8+</sup> | 长按输入框内部区域弹出剪贴板后，点击剪切板剪切按钮，触发该回调。<br/>value：剪切的文本内容。 | 89| onPaste(callback:(value: string) => void)<sup>8+</sup> | 长按输入框内部区域弹出剪贴板后，点击剪切板粘贴按钮，触发该回调。<br/>value：粘贴的文本内容。 | 90## TextInputController<sup>8+</sup> 91 92TextInput组件的控制器。 93 94### 导入对象 95``` 96controller: TextInputController = new TextInputController() 97``` 98### caretPosition 99 100caretPosition(value: number): void 101 102设置输入光标的位置。 103 104**参数：** 105 106| 参数名 | 参数类型 | 必填 | 参数描述 | 107| ------ | -------- | ---- | -------------------------------------- | 108| value | number | 是 | 从字符串开始到光标所在位置的字符长度。 | 109 110 111## 示例 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 // 将光标移动至第一个字符后 143 this.controller.caretPosition(1) 144 }) 145 // 密码输入框 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 // 内联风格输入框 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
