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 = value
        this.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 = false

  build() {
    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 组件，可以实现从简单到复杂的各种文本输入场景。关键点在于：

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