1# 文本输入 (TextInput/TextArea)
2
3
4TextInput、TextArea是输入框组件，通常用于响应用户的输入操作，比如评论区的输入、聊天框的输入、表格的输入等，也可以结合其它组件构建功能页面，例如登录注册页面。具体用法请参考[TextInput](../reference/apis-arkui/arkui-ts/ts-basic-components-textinput.md)、[TextArea](../reference/apis-arkui/arkui-ts/ts-basic-components-textarea.md)。
5
6
7## 创建输入框
8
9TextInput为单行输入框、TextArea为多行输入框。通过以下接口来创建。
10
11```ts
12TextInput(value?:{placeholder?: ResourceStr, text?: ResourceStr, controller?: TextInputController})
13```
14
15```ts
16TextArea(value?:{placeholder?: ResourceStr, text?: ResourceStr, controller?: TextAreaController})
17```
18
19- 单行输入框
20
21  ```ts
22  TextInput()
23  ```
24
25  ![zh-cn_image_0000001511580844](figures/zh-cn_image_0000001511580844.png)
26
27
28- 多行输入框
29
30  ```ts
31  TextArea()
32  ```
33
34  ![zh-cn_image_0000001562940481](figures/zh-cn_image_0000001562940481.png)
35
36  多行输入框文字超出一行时会自动折行。
37
38
39  ```ts
40  TextArea({ text: "我是TextArea我是TextArea我是TextArea我是TextArea" }).width(300)
41  ```
42
43  ![zh-cn_image_0000001511580836](figures/zh-cn_image_0000001511580836.png)
44
45
46## 设置输入框类型
47
48TextInput有9种可选类型，分别为Normal基本输入模式、Password密码输入模式、Email邮箱地址输入模式、Number纯数字输入模式、PhoneNumber电话号码输入模式、USER_NAME用户名输入模式、NEW_PASSWORD新密码输入模式、NUMBER_PASSWORD纯数字密码输入模式、<!--Del-->SCREEN_LOCK_PASSWORD锁屏应用密码输入模式、<!--DelEnd-->NUMBER_DECIMAL带小数点的数字输入模式。通过type属性进行设置：
49
50
51- 基本输入模式（默认类型）
52
53  ```ts
54  TextInput()
55    .type(InputType.Normal)
56  ```
57
58  ![zh-cn_image_0000001562820765](figures/zh-cn_image_0000001562820765.png)
59
60- 密码输入模式
61
62  ```ts
63  TextInput()
64    .type(InputType.Password)
65  ```
66
67  ![zh-cn_image_0000001511580840](figures/zh-cn_image_0000001511580840.png)
68
69
70## 自定义样式
71
72- 设置无输入时的提示文本。
73
74
75  ```ts
76  TextInput({ placeholder: '我是提示文本' })
77  ```
78
79  ![zh-cn_image_0000001511900400](figures/zh-cn_image_0000001511900400.png)
80
81
82- 设置输入框当前的文本内容。
83
84  ```ts
85  TextInput({ placeholder: '我是提示文本', text: '我是当前文本内容' })
86  ```
87
88  ![zh-cn_image_0000001562820761](figures/zh-cn_image_0000001562820761.png)
89
90- 添加backgroundColor改变输入框的背景颜色。
91
92  ```ts
93  TextInput({ placeholder: '我是提示文本', text: '我是当前文本内容' })
94    .backgroundColor(Color.Pink)
95  ```
96
97  ![zh-cn_image_0000001511740444](figures/zh-cn_image_0000001511740444.png)
98
99  更丰富的样式可以结合[通用属性](../reference/apis-arkui/arkui-ts/ts-universal-attributes-size.md)实现。
100
101
102## 添加事件
103
104文本框主要用于获取用户输入的信息，把信息处理成数据进行上传，绑定onChange事件可以获取输入框内改变的内容。用户也可以使用通用事件来进行相应的交互操作。
105
106```ts
107TextInput()
108  .onChange((value: string) => {
109    console.info(value);
110  })
111  .onFocus(() => {
112    console.info('获取焦点');
113  })
114```
115
116## 场景示例
117
118在登录/注册页面，用户进行登录或注册。
119
120```ts
121@Entry
122@Component
123struct TextInputSample {
124  build() {
125    Column() {
126      TextInput({ placeholder: 'input your username' }).margin({ top: 20 })
127        .onSubmit((EnterKeyType) => {
128          console.info(EnterKeyType + '输入法回车键的类型值');
129        })
130      TextInput({ placeholder: 'input your password' }).type(InputType.Password).margin({ top: 20 })
131        .onSubmit((EnterKeyType) => {
132          console.info(EnterKeyType + '输入法回车键的类型值');
133        })
134      Button('Sign in').width(150).margin({ top: 20 })
135    }.padding(20)
136  }
137}
138```
139
140![textinput](figures/textinput.gif)
141
142## 键盘避让
143
144键盘抬起后，具有滚动能力的容器组件在横竖屏切换时，才会生效键盘避让，若希望无滚动能力的容器组件也生效键盘避让，建议在组件外嵌套一层具有滚动能力的容器组件，比如[Scroll](../reference/apis-arkui/arkui-ts/ts-container-scroll.md)、[List](../reference/apis-arkui/arkui-ts/ts-container-list.md)、[Grid](../reference/apis-arkui/arkui-ts/ts-container-grid.md)。
145
146```ts
147// xxx.ets
148@Entry
149@Component
150struct Index {
151  placeHolderArr: string[] = ['1', '2', '3', '4', '5', '6', '7'];
152
153  build() {
154    Scroll() {
155      Column() {
156        ForEach(this.placeHolderArr, (placeholder: string) => {
157          TextInput({ placeholder: 'TextInput ' + placeholder })
158            .margin(30)
159        })
160      }
161    }
162    .height('100%')
163    .width('100%')
164  }
165}
166```
167
168![textinputkeyboardavoid](figures/TextInputKeyboardAvoid.gif)
169
170## 光标避让
171
172[keyBoardAvoidMode](../../application-dev/reference/apis-arkui/arkui-ts/ts-types.md#keyboardavoidmode11)默认的OFFSET和RESIZE在键盘抬起后，不支持二次避让，如果想要支持光标位置在点击或者通过接口设置变化后发生二次避让，可以考虑使用OFFSET_WITH_CARET和RESIZE_CARET替换原有的OFFSET和RESIZE模式。<br>
173对于滚动容器更推荐使用RESIZE_WITH_CARET，非滚动容器应该使用OFFSET_WITH_CARET。
174
175```ts
176// EntryAbility.ets
177import { KeyboardAvoidMode } from '@kit.ArkUI';
178
179// Used in UIAbility
180onWindowStageCreate(windowStage: window.WindowStage) {
181  // Main window is created, set main page for this ability
182  hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate');
183
184  windowStage.loadContent('pages/Index', (err, data) => {
185    let keyboardAvoidMode = windowStage.getMainWindowSync().getUIContext().getKeyboardAvoidMode();
186  windowStage.getMainWindowSync().getUIContext().setKeyboardAvoidMode(KeyboardAvoidMode.OFFSET_WITH_CARET);
187    if (err.code) {
188      hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? '');
189      return;
190    }
191    hilog.info(0x0000, 'testTag', 'Succeeded in loading the content. Data: %{public}s', JSON.stringify(data) ?? '');
192  });
193}
194```
195
196```ts
197// xxx.ets
198@Entry
199@Component
200struct Index {
201  @State caretPosition: number = 600;
202  areaController: TextAreaController = new TextAreaController();
203  text = "Most of us compare ourselves with anyone we think is happier — a relative, someone we know a lot, or someone we hardly know. As a result, what we do remember is anything that makes others happy, anything that makes ourselves unhappy, totally forgetting that there is something happy in our own life.\
204  So the best way to destroy happiness is to look at something and focus on even the smallest flaw. It is the smallest flaw that would make us complain. And it is the complaint that leads to us becoming unhappy.\
205  If one chooses to be happy, he will be blessed; if he chooses to be unhappy, he will be cursed. Happiness is just what you think will make you happy.Most of us compare ourselves with anyone we think is happier — a relative, someone we know a lot, or someone we hardly know. As a result, what we do remember is anything that makes others happy, anything that makes ourselves unhappy, totally forgetting that there is something happy in our own life.\
206  So the best way to destroy happiness is to look at something and focus on even the smallest flaw. It is the smallest flaw that would make us complain. And it is the complaint that leads to us becoming unhappy.\
207  If one chooses to be happy, he will be blessed; if he chooses to be unhappy, he will be cursed. Happiness is just what you think will make you happy.Most of us compare ourselves with anyone we think is happier — a relative, someone we know a lot, or someone we hardly know. As a result, what we do remember is anything that makes others happy, anything that makes ourselves unhappy, totally forgetting that there is something happy in our own life.\
208  So the best way to destroy happiness is to look at something and focus on even the smallest flaw. It is the smallest flaw that would make us complain. And it is the complaint that leads to us becoming unhappy.\
209  If one chooses to be happy, he will be blessed; if he chooses to be unhappy, he will be cursed. Happiness is just what you think will make you happy.Most of us compare ourselves with anyone we think is happier — a relative, someone we know a lot, or someone we hardly know. As a result, what we do remember is anything that makes others happy, anything that makes ourselves unhappy, totally forgetting that there is something happy in our own life.\
210  So the best way to destroy happiness is to look at something and focus on even the smallest flaw. It is the smallest flaw that would make us complain. And it is the complaint that leads to us becoming unhappy.\
211  If one chooses to be happy, he will be blessed; if he chooses to be unhappy, he will be cursed. Happiness is just what you think will make you happy.Most of us compare ourselves with anyone we think is happier — a relative, someone we know a lot, or someone we hardly know. As a result, what we do remember is anything that makes others happy, anything that makes ourselves unhappy, totally forgetting that there is something happy in our own life.\
212  ";
213
214  build() {
215    Scroll() {
216      Column() {
217        Row() {
218          Button('CaretPostiion++: ' + this.caretPosition).onClick(() => {
219            this.caretPosition += 1;
220          }).fontSize(10)
221          Button('CaretPostiion--: ' + this.caretPosition).onClick(() => {
222            this.caretPosition -= 1;
223          }).fontSize(10)
224          Button('SetCaretPostion: ').onClick(() => {
225            this.areaController.caretPosition(this.caretPosition);
226          }).fontSize(10)
227        }
228
229        TextArea({ text: this.text, controller: this.areaController })
230          .width('100%')
231          .fontSize('20fp')
232      }
233    }.width('100%').height('100%')
234  }
235}
236```
237
238![textinputkeyboardavoid](figures/caretavoid.gif)
239
240## 相关实例
241
242针对文本输入开发，有以下相关实例可供参考：
243
244- [简易计算器（ArkTS）（API9）](https://gitee.com/openharmony/codelabs/tree/master/ETSUI/SimpleCalculator)