ts-basic-components-textinput.md 13.8 KB
Newer Older
Z
zengyawen 已提交
1 2
# TextInput

3
单行文本输入框组件。
T
explain  
tianyu 已提交
4

H
geshi  
HelloCrease 已提交
5
>  **说明:**
G
gmy 已提交
6 7
>
>  该组件从API Version 7开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
Z
zengyawen 已提交
8

Z
zengyawen 已提交
9 10

## 子组件
Z
zengyawen 已提交
11 12 13



Z
zengyawen 已提交
14 15 16

## 接口

K
kangchongtao 已提交
17
TextInput(value?:{placeholder?: ResourceStr, text?: ResourceStr, controller?: TextInputController})
Z
zengyawen 已提交
18

G
gmy 已提交
19
**参数:**
G
gmy 已提交
20 21 22

| 参数名                     | 参数类型                                     | 必填   | 参数描述            |
| ----------------------- | ---------------------------------------- | ---- | --------------- |
23
| placeholder   | [ResourceStr](ts-types.md#resourcestr)       | 否    | 设置无输入时的提示文本。      |
L
limeng 已提交
24
| text          | [ResourceStr](ts-types.md#resourcestr)       | 否    | 设置输入框当前的文本内容。</br>当组件设置[stateStyles](ts-universal-attributes-polymorphic-style.md)等刷新属性时,建议通过onChange事件将状态变量与文本实时绑定,</br>避免组件刷新时TextInput中的文本内容异常。<br />从API version 10开始,该参数支持[$$](../../quick-start/arkts-two-way-sync.md)双向绑定变量。 |
G
gmy 已提交
25
| controller<sup>8+</sup> | [TextInputController](#textinputcontroller8) | 否    | 设置TextInput控制器。 |
Z
zengyawen 已提交
26 27 28


## 属性
Z
zengyawen 已提交
29

N
nickyjd 已提交
30
除支持[通用属性](ts-universal-attributes-size.md)[文本通用属性](ts-universal-attributes-text-style.md)的fontColor、fontSize、fontStyle、fontWeight、fontFamily外,还支持以下属性:
Z
zengyawen 已提交
31

G
gmy 已提交
32 33
| 名称                       | 参数类型                                     | 描述                                       |
| ------------------------ | ---------------------------------------- | ---------------------------------------- |
Y
yamila 已提交
34
| type                     | [InputType](#inputtype枚举说明)     | 设置输入框类型。<br/>默认值:InputType.Normal        |
N
nickyjd 已提交
35
| placeholderColor         | [ResourceColor](ts-types.md#resourcecolor)     | 设置placeholder文本颜色。<br/>默认值跟随主题。   |
H
HelloCrease 已提交
36
| placeholderFont          | [Font](ts-types.md#font) | 设置placeholder文本样式。 |
Y
yamila 已提交
37
| enterKeyType             | [EnterKeyType](#enterkeytype枚举说明) | 设置输入法回车键类型,目前仅支持默认类型显示。<br/>默认值:EnterKeyType.Done |
N
nickyjd 已提交
38
| caretColor               | [ResourceColor](ts-types.md#resourcecolor)    | 设置输入框光标颜色。<br/>默认值:'#007DFF'。                                |
G
gmy 已提交
39
| maxLength                | number                                   | 设置文本的最大输入字符数。                            |
40
| inputFilter<sup>8+</sup> | {<br/>value:&nbsp;[ResourceStr](ts-types.md#resourcestr),<br/>error?:&nbsp;(value:&nbsp;string)&nbsp;=&gt;&nbsp;void<br/>} | 正则表达式,匹配表达式的输入允许显示,不匹配的输入将被过滤。目前仅支持单个字符匹配,不支持字符串匹配。<br/>-&nbsp;value:设置正则表达式。<br/>-&nbsp;error:正则匹配失败时,返回被过滤的内容。 |
N
nickyjd 已提交
41
| copyOption<sup>9+</sup>  | [CopyOptions](ts-appendix-enums.md#copyoptions9) | 设置输入的文本是否可复制。<br/>默认值:CopyOptions.LocalDevice,支持设备内复制。<br/>设置CopyOptions.None时,当前TextInput中的文字无法被复制或剪切,仅支持粘贴。 |
42
| showPasswordIcon<sup>9+</sup> | boolean | 密码输入模式时,输入框末尾的图标是否显示。<br/>默认值:true |
S
sunjiakun 已提交
43
| style<sup>9+</sup> | [TextInputStyle](#textinputstyle9枚举说明) \| [TextContentStyle](ts-appendix-enums.md#textcontentstyle10) | 设置输入框为默认风格或内联输入风格。<br/>默认值:TextInputStyle.Default |
44
| textAlign<sup>9+</sup>   | [TextAlign](ts-appendix-enums.md#textalign) | 设置文本在输入框中的水平对齐方式。<br/>默认值:TextAlign.Start<br/>**说明:**<br/>仅支持TextAlign.Start、TextAlign.Center和TextAlign.End。<br/>可通过[align](ts-universal-attributes-location.md)属性控制文本段落在垂直方向上的位置,此组件中不可通过align属性控制文本段落在水平方向上的位置,即align属性中Alignment.TopStart、Alignment.Top、Alignment.TopEnd效果相同,控制内容在顶部,Alignment.Start、Alignment.Center、Alignment.End效果相同,控制内容垂直居中,Alignment.BottomStart、Alignment.Bottom、Alignment.BottomEnd效果相同,控制内容在底部。  |
45
| selectedBackgroundColor<sup>10+</sup> | [ResourceColor](ts-types.md#resourcecolor) | 设置文本选中底板颜色。<br/>如果未设置透明度,默认为不透明(例如:“0x80000000”为50%透明度黑色)。 |
C
chensi10 已提交
46
| caretStyle<sup>10+</sup> | {<br/>width:&nbsp;[Length](ts-types.md#length)<br/>} | 设置光标风格。                                        |
C
chensi10 已提交
47
| caretPosition<sup>10+</sup> | number | 设置光标位置。 |
S
sunjiakun 已提交
48 49
| showUnit<sup>10+</sup>                | &nbsp;[CustomBuilder](ts-types.md#CustomBuilder8)         | 设置控件作为文本框单位。<br/>默认无单位。 |
| showError<sup>10+</sup> | string&nbsp;\|&nbsp;undefined | 设置错误状态下提示的错误文本或者不显示错误状态。<br/>默认不显示错误状态。 |
N
nickyjd 已提交
50
| showUnderline<sup>10+</sup> | boolean | 设置是否开启下划线。<br/>默认值:false |
S
sunjiakun 已提交
51
| passwordIcon<sup>10+</sup> | [PasswordIcon](#passwordicon10对象说明) | 密码输入模式时,设置输入框末尾的图标。<br/>默认为系统提供的密码图标。 |
X
xiexiyun 已提交
52
| enableKeyboardOnFocus<sup>10+</sup> | boolean | TextInput获焦时,是否绑定输入法<br/>默认值:true。从API version 10开始,获焦默认绑定输入法。 |
53
| selectionMenuHidden<sup>10+</sup> | boolean | 设置长按输入框或者右键输入框时,是否弹出文本选择菜单。<br />默认值:false |
G
gmy 已提交
54

Y
yamila 已提交
55 56
>  **说明:**
>
Y
yamila 已提交
57
>  [通用属性padding](ts-universal-attributes-size.md)的默认值为:<br>{<br>&nbsp;top: 8 vp,<br>&nbsp;right: 16 vp,<br>&nbsp;bottom: 8 vp,<br>&nbsp;left: 16 vp<br> }
Y
yamila 已提交
58

G
gmy 已提交
59 60 61 62
## EnterKeyType枚举说明

| 名称                  | 描述        |
| ------------------- | --------- |
63
| Go     | 显示为前往样式。   |
G
gmy 已提交
64 65 66
| Search | 显示为搜索样式。  |
| Send   | 显示为发送样式。  |
| Next   | 显示为下一个样式。 |
67
| Done   | 显示为确认样式。     |
G
gmy 已提交
68 69 70 71 72 73

## InputType枚举说明

| 名称                 | 描述            |
| ------------------ | ------------- |
| Normal   | 基本输入模式。<br/>支持输入数字、字母、下划线、空格、特殊字符。 |
Y
yamila 已提交
74 75
| Password | 密码输入模式。支持输入数字、字母、下划线、空格、特殊字符。密码显示小眼睛图标并且默认会将文字变成圆点。 |
| Email    | 邮箱地址输入模式。支持数字,字母,下划线,以及@字符(只能存在一个@字符)。 |
G
gmy 已提交
76 77 78
| Number   | 纯数字输入模式。      |
| PhoneNumber<sup>9+</sup> | 电话号码输入模式。<br/>支持输入数字、+ 、-、*、#,长度不限。 |

79
## TextInputStyle<sup>9+</sup>枚举说明
G
gmy 已提交
80 81 82

| 名称                 | 描述            |
| ------------------ | ------------- |
83 84
| Default   | 默认风格,光标宽1.5vp,光标高度与文本选中底板高度和字体大小相关。   |
| Inline    | 内联输入风格。文本选中底板高度与输入框高度相同。      |
Z
zengyawen 已提交
85

S
sunjiakun 已提交
86 87 88 89 90 91 92
## PasswordIcon<sup>10+</sup>对象说明

| 名称       | 类型                                               | 必填 | 描述                                               |
| ---------- | -------------------------------------------------- | ---- | -------------------------------------------------- |
| onIconSrc  | string&nbsp;\|[Resource](ts-types.md#resource类型) | 否   | 密码输入模式时,能够切换密码隐藏的显示状态的图标。 |
| offIconSrc | string&nbsp;\|[Resource](ts-types.md#resource类型) | 否   | 密码输入模式时,能够切换密码显示的隐藏状态的图标。 |

93 94
## 事件

95 96
除支持[通用事件](ts-universal-events-click.md)外,还支持以下事件:

Y
yamila 已提交
97 98
| 名称                                                         | 功能描述                                                     |
| ------------------------------------------------------------ | ------------------------------------------------------------ |
Y
yamila 已提交
99
| onChange(callback:&nbsp;(value:&nbsp;string)&nbsp;=&gt;&nbsp;void) | 输入内容发生变化时,触发该回调。<br/>value:输入的文本内容。<br/>触发该事件的条件:<br/>1、键盘输入。<br/>2、粘贴、剪切。<br/>3、键盘快捷键Ctrl+v。 |
Y
yamila 已提交
100 101
| onSubmit(callback:&nbsp;(enterKey:&nbsp;EnterKeyType)&nbsp;=&gt;&nbsp;void) | 按下输入法回车键触发该回调,返回值为当前输入法回车键的类型。<br/>enterKeyType:输入法回车键类型。具体类型见[EnterKeyType枚举说明](#enterkeytype枚举说明)。 |
| onEditChanged(callback:&nbsp;(isEditing:&nbsp;boolean)&nbsp;=&gt;&nbsp;void)<sup>(deprecated)</sup> | 输入状态变化时,触发该回调。从API 8开始,建议使用onEditChange。 |
Y
yamila 已提交
102
| onEditChange(callback:&nbsp;(isEditing:&nbsp;boolean)&nbsp;=&gt;&nbsp;void)<sup>8+</sup> | 输入状态变化时,触发该回调。有光标时为编辑态,无光标时为非编辑态。isEditing为true表示正在输入。 |
103 104 105
| onCopy(callback:(value:&nbsp;string)&nbsp;=&gt;&nbsp;void)<sup>8+</sup> | 长按输入框内部区域弹出剪贴板后,点击剪切板复制按钮,触发该回调。<br/>value:复制的文本内容。 |
| onCut(callback:(value:&nbsp;string)&nbsp;=&gt;&nbsp;void)<sup>8+</sup> | 长按输入框内部区域弹出剪贴板后,点击剪切板剪切按钮,触发该回调。<br/>value:剪切的文本内容。 |
| onPaste(callback:(value:&nbsp;string)&nbsp;=&gt;&nbsp;void)<sup>8+</sup> | 长按输入框内部区域弹出剪贴板后,点击剪切板粘贴按钮,触发该回调。<br/>value:粘贴的文本内容。 |
106 107
| onTextSelectionChange(callback: (selectionStart: number, selectionEnd: number) => void)<sup>10+</sup> | 文本选择的位置发生变化时,触发该回调。<br />selectionStart:文本选择区域起始位置,文本框中文字的起始位置为0。<br />selectionEnd:文本选择区域结束位置。 |
| onContentScroll(callback: (totalOffsetX: number, totalOffsetY: number) => void)<sup>10+</sup> | 文本内容滚动时,触发该回调。<br />totalOffsetX:文本在内容区的横坐标偏移。<br />totalOffsetY:文本在内容区的纵坐标偏移。 |
108

G
gmy 已提交
109
## TextInputController<sup>8+</sup>
Z
zengyawen 已提交
110

Y
yaoyuchi 已提交
111
TextInput组件的控制器。
Z
zengyawen 已提交
112

G
gmy 已提交
113
### 导入对象
Y
yaoyuchi 已提交
114 115 116
```
controller: TextInputController = new TextInputController()
```
117
### caretPosition<sup>8+</sup>
Y
yaoyuchi 已提交
118 119 120

caretPosition(value:&nbsp;number): void

121
设置输入光标的位置。
Y
yaoyuchi 已提交
122

G
gmy 已提交
123 124 125 126 127
**参数:**

| 参数名 | 参数类型 | 必填 | 参数描述                               |
| ------ | -------- | ---- | -------------------------------------- |
| value  | number   | 是   | 从字符串开始到光标所在位置的字符长度。 |
128
### setTextSelection<sup>10+</sup>
Z
zengyawen 已提交
129

130 131 132 133 134 135 136 137 138 139
setTextSelection(selectionStart:&nbsp;number, selectionStart:&nbsp;number): void

设置文本选择区域并高亮显示。

**参数:**

| 参数名         | 参数类型 | 必填 | 参数描述               |
| -------------- | -------- | ---- | ---------------------- |
| selectionStart | number   | 是   | 文本选择区域起始位置,文本框中文字的起始位置为0。 |
| selectionEnd   | number   | 是   | 文本选择区域结束位置。 |
Z
zengyawen 已提交
140

141 142 143 144 145 146
### stopEditing<sup>10+</sup>

stopEditing(): void

退出编辑态。

147 148 149 150
### getTextContentRect<sup>10+</sup>

getTextContentRect(): [RectResult](#rectresult)

151
获取已编辑文本内容区域相对组件的位置和大小,返回值单位为像素。
152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187

**返回值:**

| 类型       | 说明       |
| -------------------  | -------- |
| [RectResult](#rectresult) | 已编辑文本内容的相对组件的位置和大小。 |

> **说明:**
>
> - 初始不输入文本时,返回值中有相对组件的位置信息,大小为0。
> - 返回值中的位置信息是第一个字符相对于可编辑组件的位置。

### RectResult<sup>10+</sup>

位置和大小。

| 参数      | 类型     | 描述 |
| ------- | ------ | ----------------------- |
| x     | number | 水平方向横坐标。|
| y     | number | 竖直方向纵坐标。|
| width | number | 内容宽度大小。|
| height | number | 内容高度大小。|


### getTextContentLineCount<sup>10+</sup>

getTextContentLineCount(): number

获取已编辑文本内容的行数。

**返回值:**

| 类型  | 说明       |
| ----- | -------- |
| number| 已编辑文本内容行数。 |

Z
zengyawen 已提交
188 189
## 示例

H
geshi  
HelloCrease 已提交
190 191
```ts
// xxx.ets
Z
zengyawen 已提交
192 193
@Entry
@Component
194
struct TextInputExample {
Y
yamila 已提交
195 196
  @State text: string = ''
  controller: TextInputController = new TextInputController()
Z
zengyawen 已提交
197 198 199

  build() {
    Column() {
200
      TextInput({ text: this.text, placeholder: 'input your word...', controller: this.controller })
201 202
        .placeholderColor(Color.Grey)
        .placeholderFont({ size: 14, weight: 400 })
Z
zengyawen 已提交
203
        .caretColor(Color.Blue)
204 205 206 207 208
        .width(400)
        .height(40)
        .margin(20)
        .fontSize(14)
        .fontColor(Color.Black)
Y
yamila 已提交
209 210 211
        .inputFilter('[a-z]', (e) => {
          console.log(JSON.stringify(e))
        })
Z
zengyawen 已提交
212
        .onChange((value: string) => {
Y
yamila 已提交
213
          this.text = value
214 215 216 217 218 219
        })
      Text(this.text)
      Button('Set caretPosition 1')
        .margin(15)
        .onClick(() => {
          // 将光标移动至第一个字符后
Y
yamila 已提交
220
          this.controller.caretPosition(1)
Z
zengyawen 已提交
221
        })
222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237
      // 密码输入框
      TextInput({ placeholder: 'input your password...' })
        .width(400)
        .height(40)
        .margin(20)
        .type(InputType.Password)
        .maxLength(9)
        .showPasswordIcon(true)
      // 内联风格输入框
      TextInput({ placeholder: 'inline style' })
        .width(400)
        .height(50)
        .margin(20)
        .borderRadius(0)
        .style(TextInputStyle.Inline)
    }.width('100%')
Z
zengyawen 已提交
238 239 240 241
  }
}
```

Y
yamila 已提交
242
![textInput](figures/textInput.gif)