4.ArkUI TextInput的介绍和使用

ArkUI TextInput 组件详解与使用指南

TextInput 是 ArkUI 中用于文本输入的核心组件，支持单行、多行输入及多种输入格式控制。以下是 TextInput 的详细使用方法及示例：

---

基础使用

1. 基本输入框

@Entry
@Component
struct BasicInputExample {@State text: string = ''build() {Column() {TextInput({ placeholder: '请输入内容' }).width('80%').height(40).onChange((value: string) => {this.text = value})Text('输入内容: ' + this.text).margin({ top: 10 })}.width('100%').height('100%').justifyContent(FlexAlign.Center)}
}

---

核心功能

1. 输入类型控制

TextInput().type(InputType.Normal)      // 常规文本（默认）.type(InputType.Password)    // 密码输入.type(InputType.Email)       // 邮箱格式.type(InputType.Number)      // 数字键盘.type(InputType.PhoneNumber) // 电话号码

2. 输入限制

TextInput().maxLength(10)             // 最大输入长度.maxLines(3)               // 最大行数（多行模式）.inputFilter('[a-zA-Z]')   // 正则过滤（只允许字母）

3. 样式定制

TextInput().fontSize(16)              // 字体大小.fontColor('#333')         // 字体颜色.placeholderColor('#999')  // 提示文字颜色.backgroundColor('#FFF')   // 背景颜色.border({                  // 边框样式width: 1,color: '#DDD',radius: 8}).padding(10)               // 内边距

---

高级功能

1. 多行输入

@State multiText: string = ''build() {TextInput({ text: this.multiText }).width('90%').height(120).type(InputType.MultiLine) // 启用多行模式.onChange((value: string) => {this.multiText = value})
}

2. 焦点控制

private controller: TextInputController = new TextInputController()build() {Column() {TextInput({ controller: this.controller }).onClick(() => {this.controller.caretPosition(5) // 设置光标位置})Button('获取焦点').onClick(() => {this.controller.focus() // 手动聚焦})Button('失去焦点').onClick(() => {this.controller.blur() // 取消聚焦})}
}

3. 输入验证

@State email: string = ''
@State errorMsg: string = ''validateEmail(email: string) {const pattern = /^[^\s@]+@[^\s@]+\.[^\s@]+$/this.errorMsg = pattern.test(email) ? '' : '邮箱格式不正确'
}build() {Column() {TextInput({ placeholder: '输入邮箱' }).type(InputType.Email).onChange((value: string) => {this.email = valuethis.validateEmail(value)})Text(this.errorMsg).fontSize(12).fontColor(Color.Red)}
}

---

最佳实践

1. 搜索框实现

@Entry
@Component
struct SearchExample {@State keyword: string = ''@State searchResults: string[] = []build() {Column() {// 搜索框TextInput({ placeholder: '搜索内容...' }).width('90%').height(40).icon(Image($r('app.media.ic_search'))) // 搜索图标.onSubmit((value: string) => {         // 提交事件（点击键盘确认）this.performSearch(value)}).onChange((value: string) => {this.keyword = value})// 搜索结果列表List() {ForEach(this.searchResults, (item) => {ListItem() {Text(item)}})}}}performSearch(keyword: string) {// 模拟搜索逻辑this.searchResults = ['结果1', '结果2', '结果3']}
}

2. 密码可见性切换

@Entry
@Component
struct PasswordInput {@State password: string = ''@State showPassword: boolean = falsebuild() {Row() {TextInput({ placeholder: '输入密码',text: this.password }).type(this.showPassword ? InputType.Normal : InputType.Password).layoutWeight(1)Button(this.showPassword ? '👁️' : '👁️🗨️').onClick(() => {this.showPassword = !this.showPassword})}.width('80%').padding(10).border({ width: 1, color: '#DDD' }).borderRadius(8)}
}

---

注意事项

1. 性能优化：

   • 避免在 onChange 中执行耗时操作
   • 大数据量实时搜索使用防抖（300-500ms）

2. 无障碍支持：

   TextInput().accessibilityLabel('用户名输入框').accessibilityHint('请输入您的用户名')
   

3. 键盘控制：

   TextInput().enterKeyType(EnterKeyType.Go)       // 键盘确认键类型.onSubmit((value: string) => {       // 确认键回调// 处理提交逻辑})
   

4. 多语言支持：

   TextInput({ placeholder: $r('app.string.enter_username') })
   

---

通过合理使用 TextInput 组件，可以实现从简单到复杂的各种文本输入场景。关键点在于：

• 根据场景选择合适的输入类型
• 结合状态管理实现数据绑定
• 通过样式定制提升用户体验
• 添加必要的输入验证和安全措施