HarmonyOS NEXT鸿蒙开发：TextInput 单行文本输入组件

作者：马育民 • • 阅读：10053

介绍

TextInput 单行文本输入组件，是用于接收用户文本输入的基础组件，类似于 HTML 中的 <input> 标签

应用场景

广泛应用于 登录界面、注册界面：

  • 登录名输入框
  • 手机号输入框
  • 密码输入框

基本用法

TextInput({
    text:"李雷",
    placeholder:"请输入姓名"
})

常用属性

基础属性

  • type：输入类型，可选值：TextInputType.Normal（默认，普通文本）、TextInputType.Password（密码，显示为圆点）、TextInputType.Number（数字输入）等
  • enabled：是否可编辑，false 时输入框禁用（灰显，不可输入）
  • placeholderColor：提示文本（hint）的颜色
  • textAlign：文本对齐方式，如 TextAlign.Center（居中）、TextAlign.Left（左对齐）

样式属性

  • width/height：输入框的宽高
  • border：边框样式，如 border({ width: 1, color: “#ddd” })
  • padding：内边距，调整文本与边框的距离
  • backgroundColor：背景色

事件

  • onChange：输入内容变化时触发，返回当前输入的文本值
  • onFocus：输入框获取焦点时触发（如用户点击输入框）
  • onBlur：输入框失去焦点时触发（如用户点击其他区域）
  • onSubmit：点击软键盘的 “完成” 按钮时触发（仅单行输入有效）

获取控件内容

TextInput 的核心功能是获取用户输入的文本，通过 onChange 事件实时监听输入内容变化，基本使用示例如下：

@Entry
@Component
struct TextInputExample {
  @State inputValue: string = ""; // 用于存储输入内容

  build() {
    Column() {
      TextInput({
        text:this.inputValue, // 绑定输入值
        placeholder:"请输入姓名" // 提示文本
      })
        .onChange((value: string) => {
          this.inputValue = value; // 实时更新输入内容
        })

      Button('获取值')
        .onClick(() => {
          console.log("姓名：",this.inputValue)
        })

      Button('修改值')
        .onClick(() => {
          this.inputValue = "李雷"
        })
    }
  }
}

例子

密码输入框

TextInput({
  text:this.inputValue,
  placeholder:"请输入密码"
})
  .type(InputType.Password) // 输入内容显示为圆点
  .width(300)
  .height(40)
  .border({ width: 1 })

数字输入框

TextInput({
  text:this.inputValue,
  placeholder:"请输入手机号"
})
  .type(InputType.Number) // 仅允许输入数字
  .maxLength(11) // 限制最大长度为11位
  .width(300)
  .height(40)
  .border({ width: 1 })

带焦点监听的输入框

TextInput({
  text:this.inputValue,
  placeholder:"点击获取焦点"
})
  .onFocus(() => {
    console.log("输入框已获取焦点");
  })
  .onBlur(() => {
    console.log("输入框已失去焦点");
    // 可在此处执行输入校验
  })
  .width(300)
  .height(40)
  .border({ width: 1 })

提交事件监听

TextInput({
  text:this.inputValue,
  placeholder:"输入后点击完成"
})
  .onSubmit(() => {
    console.log("用户点击了软键盘的完成按钮");
    // 可在此处执行提交逻辑
  })
  .width(300)
  .height(40)
  .border({ width: 1 })

综合例子

TextInput 的核心功能是获取用户输入的文本，通过 onChange 事件实时监听输入内容变化，基本使用示例如下：

@Entry
@Component
struct TextInputExample {
  @State inputValue: string = ""; // 用于存储输入内容

  build() {
    Column() {
      TextInput({
        text:this.inputValue, // 绑定输入值
        placeholder:"请输入姓名" // 提示文本
      })
        .width(300)
        .height(40)
        .border({ width: 1, color: "#cccccc" }) // 边框样式
        .padding({ left: 10 }) // 内边距
        .onChange((value: string) => {
          this.inputValue = value; // 实时更新输入内容
        })

      Button('获取值')
        .margin(15)
        .onClick(() => {
          console.log("姓名：",this.inputValue)
        })

      Button('修改值')
        .margin(15)
        .onClick(() => {
          this.inputValue = "李雷"
        })
    }
  }
}

注意事项

  1. 双向绑定：通过 value 属性与 @State 变量绑定，结合 onChange 事件实现输入内容的实时同步。
  2. 输入限制：使用 maxLength 限制输入文本长度，type 限制输入类型（如数字、密码）。
  3. 性能优化：避免在 onChange 中执行复杂逻辑（如频繁网络请求），可通过防抖处理（setTimeout）优化。
  4. 兼容性：API 5 中 TextInput 功能相对基础，更高版本（如 API 6+）扩展了更多特性（如多行输入 TextArea）。

通过 TextInput 组件，可快速实现用户文本输入交互，结合事件处理和样式配置，满足各类表单场景需求。

原文出处：/show_1GW1xpLJ39YM.html

吉ICP备15003043号