鸿蒙（HarmonyOS）开发中TextInput组件的详细使用

本文同步发表于我的微信公众号，微信搜索 程语新视界 即可关注，每个工作日都有文章更新

一、组件概述

TextInput 是鸿蒙 ArkUI 中用于接收用户单行文本输入的组件，支持密码输入、数字键盘、自定义样式、输入验证等功能，广泛应用于登录、搜索、表单等场景。

二、基础用法

1. 创建基本输入框

TextInput({ placeholder: '请输入内容' })  // 设置占位提示文本
  .width('70%')                         // 宽度设置
  .type(InputType.Normal)               // 默认输入类型（支持普通文本）

说明：placeholder 属性用于无输入时的提示文本，width 控制输入框宽度。

2. 密码输入模式

TextInput({ placeholder: '请输入密码' })
  .type(InputType.Password)             // 输入内容显示为密文
  .caretColor(Color.Red)                // 设置光标颜色为红色

3. 数字输入模式 

TextInput({ placeholder: '请输入数字' })
  .type(InputType.Number)               // 仅允许输入数字

三、核心 API 与方法

1. 参数定义

• 构造函数：

TextInput(value?: { 
  placeholder?: string | Resource, 
  text?: string | Resource, 
  controller?: TextInputController 
})

• text：初始文本内容（需配合 onChange 事件实现双向绑定） 。
• controller：用于控制光标位置等高级操作

2. 常用属性方法 

 3. 控制器方法（TextInputController）

let controller = new TextInputController();

// 设置光标位置
controller.caretPosition(2);  // 将光标移动到第2个字符后

4. 禁用状态‌ 

TextInput()
  .enabled(false)  // 禁用输入框

四、事件处理

1. 输入变化事件（onChange）

@State inputText: string = '';

TextInput({ placeholder: '请输入内容' })
  .onChange((value: string) => {
    this.inputText = value;  // 实时更新输入内容到状态变量（实现双向绑定）
    console.log('当前输入:', value);
  })

注意：直接通过 text 参数绑定状态变量可能导致刷新异常，建议优先使用 onChange 事件。

2. 焦点事件

TextInput()
  .onFocus(() => {
    console.log('输入框获得焦点');
  })
  .onBlur(() => {
    console.log('输入框失去焦点');
  })

3. 提交事件（onSubmit）

TextInput()
  .onSubmit((enterKeyType: EnterKeyType) => {
    console.log('回车键类型:', enterKeyType);  // 如搜索、发送等
  })

五、高级功能

1. 输入验证

TextInput({ placeholder: '仅允许数字' })
  .onChange((value: string) => {
    if (/^[0-9]*$/.test(value)) {  // 正则验证数字输入
      this.inputText = value;
    }
  })

 2. 动态样式控制

@State isFocused: boolean = false;

TextInput()
  .backgroundColor(this.isFocused ? '#F0F0F0' : '#FFFFFF')  // 焦点时背景色变化
  .onFocus(() => { this.isFocused = true; })
  .onBlur(() => { this.isFocused = false; })

3. 结合按钮实现搜索

@State searchText: string = '';

Row({ space: 10 }) {
  TextInput({ placeholder: '搜索' })
    .width('70%')
    .onChange((value) => this.searchText = value)
  
  Button('搜索')
    .onClick(() => {
      console.log('搜索关键词:', this.searchText);
    })
}

4.键盘避让与动态布局调整

// 通过 setKeyboardAvoidMode 实现键盘弹出时组件动态避让
@Entry
@Component
struct KeyboardAvoidDemo {
  @State inputText: string = ''

  build() {
    Column() {
      TextInput({ placeholder: '评论输入框' })
        .defaultFocus(true) // 自动获焦触发键盘
        .onFocus(() => {
          // 设置键盘避让模式为 RESIZE
          getContext().setKeyboardAvoidMode(KeyboardAvoidMode.RESIZE)
        })
      
      // 底部固定按钮
      Button('发布')
        .margin({ top: 300 })
    }
    .height('100%')
  }
}

特性‌：键盘弹出时页面自动调整布局，避免遮挡输入框，支持实时感知键盘高度变化

5.自定义软键盘交互 

// 使用自定义键盘按钮扩展输入功能
@Entry
@Component
struct CustomKeyboard {
  private inputController: TextInputController = new TextInputController()

  build() {
    Column() {
      TextInput({ controller: this.inputController })
      
      // 自定义数字键盘
      Grid() {
        ForEach(Array.from({ length: 9 }, (_, i) => i + 1), (num) => {
          Button(num.toString())
            .onClick(() => this.inputController.insertText(num.toString()))
        })
      }
      .columnsTemplate('1fr 1fr 1fr')
    }
  }
}

应用场景‌：适用于密码输入、金额输入等需要限制输入类型的场景 

6.输入防抖实现（搜索优化）

@Entry
@Component
struct DebounceSearch {
  @State searchText: string = ''
  private timerId: number = 0

  // 防抖函数封装（300ms延迟）
  private debounceSearch = (value: string) => {
    clearTimeout(this.timerId)
    this.timerId = setTimeout(() => {
      this.requestSearchAPI(value) // 实际网络请求方法
    }, 300)
  }

  build() {
    TextInput({ placeholder: '输入搜索内容' })
      .onChange((value) => {
        this.searchText = value
        this.debounceSearch(value) // 触发防抖逻辑
      })
  }
}

六、注意事项

1. 多行输入：TextInput 仅支持单行输入，多行输入需使用 TextArea 组件 。
2. 键盘类型：EnterKeyType 可设置回车键样式（如搜索、前往等） 。
3. 性能优化：频繁输入场景建议配合防抖/节流处理