ArkUI TextInput 组件详解
在 ArkUI 中，TextInput 是用于文本输入的核心组件，提供了丰富的功能和自定义选项。下面我将详细介绍 TextInput 的使用方法，包含示例代码和详细注释。
基础 TextInput 用法
@Entry
@Component
struct TextInputDemo {
@State inputText: string = ''; // 存储输入文本的状态变量
build() {
Column() {
// 基础单行文本输入框
TextInput({ text: this.inputText }) // 绑定输入文本
.onChange((value: string) => { // 文本改变回调
this.inputText = value; // 更新状态
})
.placeholder('请输入内容') // 未输入时的提示文字
.placeholderColor(Color.Gray) // 提示文字颜色
.placeholderFont({ size: 16 }) // 提示文字样式
.width('100%') // 宽度填满父容器
.height(40) // 设置高度
.backgroundColor('#FFFFFF') // 输入框背景色
.margin({ bottom: 15 }) // 下边距
// 显示当前输入的文本
Text(`当前输入: ${this.inputText}`)
.fontSize(18)
.margin({ top: 15 })
}
.padding(16)
}
}
完整 TextInput 功能示例
@Entry
@Component
struct TextInputAdvancedDemo {
@State userName: string = ''; // 用户名输入
@State password: string = ''; // 密码输入
@State email: string = ''; // 邮箱输入
@State searchText: string = ''; // 搜索框文本
@State multilineText: string = ''; // 多行文本
@State isPasswordVisible: boolean = false; // 密码是否可见状态
build() {
Column({ space: 20 }) { // 垂直布局，子项间间距20
// 用户名输入框
TextInput({ text: this.userName })
.onChange(value => this.userName = value)
.placeholder('请输入用户名')
.placeholderFont({ size: 16, style: FontStyle.Italic }) // 倾斜提示文字
.fontSize(18)
.height(45)
.backgroundColor(Color.White)
.border({ width: 1, color: '#e0e0e0', radius: 8 }) // 添加圆角边框
.type(InputType.Normal) // 文本输入类型
// 密码输入框（带显示/隐藏功能）
Row() { // 水平布局
TextInput({ text: this.password })
.width('90%') // 占90%宽度
.placeholder('请输入密码')
.type(this.isPasswordVisible ? InputType.Normal : InputType.Password) // 控制显示类型
.onChange(value => this.password = value)
.height(45)
.backgroundColor(Color.White)
.border({ width: 1, color: '#e0e0e0', radius: 8 })
// 切换密码可见性的按钮
Button(this.isPasswordVisible ? '隐藏' : '显示')
.width(60)
.height(45)
.backgroundColor(Color.Transparent) // 透明背景
.fontColor(Color.Blue)
.onClick(() => this.isPasswordVisible = !this.isPasswordVisible)
}
.width('100%')
.margin({ top: 10 })
// 邮箱输入框（带验证）
TextInput({ text: this.email })
.onChange(value => this.email = value)
.placeholder('请输入邮箱')
.type(InputType.Email) // 邮件输入类型（会弹出邮箱键盘）
.height(45)
.backgroundColor(Color.White)
.border({ width: 1, color: '#e0e0e0', radius: 8 })
.margin({ top: 10 })
// 搜索框（带搜索图标）
Row() {
Image($r('app.media.ic_search')) // 搜索图标
.width(24)
.height(24)
.margin({ left: 10, right: 10 })
TextInput({ text: this.searchText })
.width('80%')
.placeholder('搜索关键词...')
.onChange(value => this.searchText = value)
.type(InputType.Normal)
}
.width('100%')
.height(45)
.backgroundColor(Color.White)
.border({ width: 1, color: '#e0e0e0', radius: 25 }) // 圆形边框
.margin({ top: 10 })
// 多行文本输入
TextArea({ text: this.multilineText })
.onChange(value => this.multilineText = value)
.placeholder('请输入多行文本...')
.height(100)
.width('100%')
.backgroundColor(Color.White)
.border({ width: 1, color: '#e0e0e0', radius: 8 })
.margin({ top: 15 })
}
.padding(20)
.width('100%')
.height('100%')
.backgroundColor('#f5f5f5')
}
}
TextInput 关键属性详解
| 属性/方法 | 类型/值 | 说明 |
|---|---|---|
.type() | InputType | 输入框类型: - Normal: 常规文本- Password: 密码（显示为点）- Email: 邮箱（优化键盘）- Number: 数字输入- PhoneNumber: 电话号码 |
.onChange() | (value: string) => void | 文本变化回调函数 |
.onEditChange() | (isEditing: boolean) => void | 编辑状态变化回调 |
.onSubmit() | () => void | 提交事件回调（点击键盘完成） |
.placeholder() | string | 提示文字 |
.caretColor() | ResourceColor | 光标颜色 |
.maxLength() | number | 最大字符数限制 |
.inputFilter() | string | 输入过滤的正则表达式 |
.style() | TextInputStyle | 输入框样式: - Default: 默认样式- Inline: 行内样式 |
实用技巧
1. 键盘优化
typescript
复制
TextInput()
.enterKeyType(EnterKeyType.Search) // 键盘的完成键文本为"搜索"
.keyboardType(InputType.Normal) // 显示普通键盘
.autoFocus(true) // 自动聚焦
2. 文本样式控制
TextInput()
.font({ size: 20, weight: 700 }) // 加粗大字号
.fontColor(Color.Red) // 红色文字
.fontStyle(FontStyle.Italic) // 斜体
3. 输入过滤
// 只允许输入数字和小写字母
TextInput()
.inputFilter('[a-z0-9]')
// 禁止输入空格
TextInput()
.inputFilter('[^\s]*')
4. 自定义图标按钮控制
Row() {
TextInput({ text: this.customInput })
.width('80%')
// 清除按钮
Button() {
Image($r('app.media.ic_close'))
.width(20)
.height(20)
}
.onClick(() => this.customInput = '')
.opacity(this.customInput ? 1 : 0) // 有内容时显示
}
提示：实际开发中，要避免在一个页面上使用过多 TextInput，建议采用表单组件管理多个输入项，使用状态管理统一处理数据验证和提交逻辑。
TextInput 组件在 ArkUI 中功能强大且灵活，适用于各种文本输入场景。通过合理使用其属性，可以创建出既美观又用户友好的输入体验。
