HarmonyOS6 ArkTS TextInput组件使用文档

文章目录完整代码核心基础配置1. 组件初始化参数2. 控制器创建3. 响应式状态变量基础样式自定义1. 占位符样式定制2. 输入文字样式定制3. 光标与文本对齐样式4. 通用布局样式核心输入控制能力1. 输入类型切换InputType2. 字数限制与计数器3. 输入过滤inputFilter交互增强功能1. 密码显隐切换2. 下划线模式3. 右侧清除按钮cancelButton4. 回车提交与键盘类型全量事件监听1. 内容变化事件onChange2. 剪贴板操作事件3. 密码状态事件onSecurityStateChange4. 回车提交事件onSubmit组件运行效果总结完整代码Entry Component struct TextInputFullDemo { State inputText: string ; State password: string ; State phoneNumber: string ; State showError: string ; controller: TextInputController new TextInputController(); build() { Column({ space: 20 }) { Text(TextInput 完整功能演示) .fontSize(22) .fontWeight(FontWeight.Bold) .margin({ top: 30 }); // 1. 普通输入框 双向绑定 TextInput({ text: this.inputText, placeholder: 请输入用户名/普通文本, controller: this.controller }) .placeholderColor(#999) .placeholderFont({ size: 16 }) .fontSize(16) .fontColor(#333) .caretColor(#007DFF) .textAlign(TextAlign.Start) .maxLength(20) .showCounter(true, { thresholdPercentage: 80 }) .width(90%) .height(50) .backgroundColor(#f8f8f8) .border({ width: 1, color: #e0e0e0 }) .borderRadius(12) .padding({ left: 15, right: 15 }) // 输入过滤只允许字母、数字、中文 .inputFilter([a-zA-Z0-9\u4e00-\u9fa5]*) // 内容变化 .onChange((value) { this.inputText value; // 简单校验 this.showError value.length 2 ? 用户名至少2个字符 : ; }) // 回车提交 .enterKeyType(EnterKeyType.Done) .onSubmit((type) { console.info(回车提交, type); }); // 错误提示 Text(this.showError) .fontSize(12) .fontColor(Color.Red) .width(90%) .textAlign(TextAlign.Start); // 2. 密码输入框显隐图标 TextInput({ text: this.password, placeholder: 请输入密码 }) .type(InputType.Password) .placeholderColor(#999) .fontSize(16) .caretColor(#007DFF) .showPasswordIcon(true) .width(90%) .height(50) .backgroundColor(#f8f8f8) .border({ width: 1, color: #e0e0e0 }) .borderRadius(12) .padding({ left: 15, right: 15 }) .maxLength(16) .onChange((value) { this.password value; }) .onSecurityStateChange((isShow) { console.info(密码是否显示, isShow); }); // 3. 手机号输入框下划线模式 TextInput({ text: this.phoneNumber, placeholder: 请输入手机号 }) .type(InputType.PhoneNumber) .placeholderColor(#999) .fontSize(16) .caretColor(#007DFF) .showUnderline(true) .underlineColor({ normal: #e0e0e0, typing: #007DFF, error: #FF3300 }) .width(90%) .maxLength(11) .showCounter(true) .onChange((value) { this.phoneNumber value; }) // 剪贴板监听 .onCopy((v) console.log(复制, v)) .onCut((v) console.log(剪切, v)) .onPaste((v) console.log(粘贴, v)); // 4. 右侧清除按钮 TextInput({ placeholder: 带清除按钮输入框 }) .width(90%) .height(50) .backgroundColor(#f8f8f8) .border({ width: 1, color: #e0e0e0 }) .borderRadius(12) .padding({ left: 15, right: 15 }) .cancelButton({ style: CancelButtonStyle.CONSTANT }) .onChange((v) { }); } .width(100%) .padding({ bottom: 40 }) .backgroundColor(#fff) } }运行效果如图核心基础配置1. 组件初始化参数TextInput通过构造函数传入核心初始化参数实现初始值绑定、占位符提示和控制器关联是组件使用的基础参数说明如下构造参数传入值官方API说明功能作用text响应式变量如this.inputText输入框初始文本内容实现输入内容与状态变量的双向绑定变量更新同步输入框输入框变化更新变量placeholder字符串输入框为空时的提示文本提示用户输入规则或内容方向提升交互体验如“请输入用户名”controllerTextInputController实例输入框控制器用于后续扩展光标定位、手动聚焦/失焦、选中文本等高级操作2. 控制器创建通过TextInputController创建组件控制器为输入框提供高级操作能力创建方式简单直接实例化即可controller: TextInputController new TextInputController();官方扩展能力可通过控制器调用focus()手动获取焦点、blur()手动失去焦点、caretPosition(pos)设置光标位置适配自定义交互场景。3. 响应式状态变量使用State装饰器定义输入绑定变量实现输入内容的实时响应变量值随输入框内容变化而更新支持关联其他组件如错误提示、字数统计State inputText: string ; State password: string ;注意必须使用State/Link/Prop等响应式装饰器普通变量无法实现双向绑定。基础样式自定义1. 占位符样式定制针对输入框为空时的提示文本通过placeholderColor和placeholderFont实现颜色、字号的定制让占位符与整体界面风格统一提升视觉层次感链式属性传入值功能作用placeholderColor颜色值十六进制/系统色/RGB设置占位符文本颜色推荐使用浅灰色如#999与输入文字区分placeholderFont字体配置对象size/weight/family设置占位符字号、粗细、字体示例中仅配置字号16保持简洁2. 输入文字样式定制对用户输入的文本进行样式配置支持字号、颜色的自定义保证文本展示的可读性与占位符样式配合形成视觉区分链式属性传入值功能作用fontSize数值设置输入文字字号单位默认vp适配不同屏幕示例中统一为16fontColor颜色值设置输入文字颜色推荐使用深灰色如#333保证在各种背景下的可读性3. 光标与文本对齐样式定制输入光标颜色和文本对齐方式适配不同的界面布局和交互需求光标颜色建议使用项目主题色提升视觉焦点链式属性传入值功能作用caretColor颜色值设置输入光标颜色示例中使用鸿蒙默认主题色#007DFF提升焦点辨识度textAlignTextAlign枚举设置文本对齐方式可选Start左对齐/Center居中/End右对齐推荐使用Start适配多语言排版4. 通用布局样式继承鸿蒙通用布局样式实现输入框宽高、背景、边框、圆角、内边距的定制让输入框融入整体界面设计示例中统一了基础样式保证界面一致性链式属性传入值功能作用width/height数值/百分比设置输入框宽高宽度推荐使用百分比如90%适配不同设备高度统一为50保证交互舒适度backgroundColor颜色值设置输入框背景色使用浅灰色#f8f8f8区分输入框与页面背景border边框配置对象设置输入框边框width:1color:#e0e0e0实现轻量边框效果提升边界感borderRadius数值设置输入框圆角值为12让界面更柔和符合现代UI设计风格padding对象/数值设置输入框内边距left:15right:15避免文字与边框重叠提升输入可读性核心输入控制能力1. 输入类型切换InputType通过type属性切换输入框的专属输入模式鸿蒙官方提供多种内置类型适配密码、手机号、数字等专属场景示例中使用3种高频类型属性说明如下类型值适用场景官方特性InputType.Normal默认普通文本输入如用户名、备注支持所有字符输入无特殊限制InputType.Password密码输入如登录、支付密码输入内容默认隐藏显示为●支持显隐切换InputType.PhoneNumber手机号输入自动唤起数字键盘限制仅输入数字适配手机号11位规则扩展类型官方还支持InputType.Number纯数字、InputType.Email邮箱、InputType.Url网址等按需选择即可。2. 字数限制与计数器通过maxLength和showCounter组合实现最大输入字符数限制和实时字数统计并支持阈值提醒是表单输入场景的高频能力组合使用规则如下链式属性传入值功能作用maxLength数值设置最大可输入字符数超出后禁止继续输入示例中用户名20位、密码16位、手机号11位showCounter布尔值配置对象第一个参数为true时显示字数计数器配置对象中thresholdPercentage为计数阈值如80表示80%时提醒计数器颜色自动变化示例中手机号输入框直接传true使用默认阈值用户名输入框设置80%阈值适配不同业务需求。3. 输入过滤inputFilter通过inputFilter传入正则表达式实现非法字符的自动过滤只允许符合规则的字符输入从源头限制输入内容格式示例中用户名输入框过滤规则.inputFilter([a-zA-Z0-9\u4e00-\u9fa5]*)规则说明仅允许输入大写字母、小写字母、数字、中文其他字符如特殊符号#$%将被自动过滤扩展用法可添加第二个回调参数监听被过滤的非法字符如.inputFilter(reg, (invalid) console.log(非法字符, invalid))便于问题排查和用户提示。交互增强功能1. 密码显隐切换针对InputType.Password密码类型通过showPasswordIcon和onSecurityStateChange实现密码显隐交互提升密码输入的便捷性链式属性/事件传入值/回调参数功能作用showPasswordIcon布尔值true显示密码显隐切换图标小眼睛用户点击可切换密码显示/隐藏状态onSecurityStateChangeisShow布尔值密码显隐状态变化时触发isShowtrue表示密码显示isShowfalse表示密码隐藏可用于日志记录或自定义交互2. 下划线模式替代传统边框样式通过showUnderline和underlineColor实现下划线输入样式适配简约UI设计风格支持多状态颜色定制链式属性传入值功能作用showUnderline布尔值true开启下划线模式隐藏默认边框仅显示底部下划线underlineColor多状态颜色对象定制下划线的normal正常、typing输入中、error错误状态颜色示例中输入中为主题色#007DFF错误为红色#FF3300适用场景手机号、验证码、搜索框等简约输入场景提升界面简洁度。3. 右侧清除按钮cancelButton通过cancelButton属性为输入框添加右侧一键清除按钮用户点击可快速清空输入内容提升输入交互效率属性配置如下.cancelButton({ style: CancelButtonStyle.CONSTANT })CancelButtonStyle.CONSTANT清除按钮始终显示适配搜索框、高频输入场景扩展样式官方还支持CancelButtonStyle.AUTO按钮仅在输入框有内容时显示避免界面冗余。4. 回车提交与键盘类型通过enterKeyType和onSubmit组合实现回车键盘定制和回车事件监听适配表单提交、搜索等场景提升键盘交互体验链式属性/事件传入值/回调参数功能作用enterKeyTypeEnterKeyType枚举定制键盘回车按钮的文字样式示例中使用EnterKeyType.Done完成还支持Search搜索、Next下一个、Send发送等onSubmittypeEnterKeyType点击键盘回车按钮时触发回调参数为当前回车按钮类型可用于实现表单提交、搜索执行等逻辑全量事件监听TextInput提供丰富的事件回调覆盖内容变化、剪贴板操作、密码状态、回车提交等全场景满足各类自定义交互需求核心事件说明如下1. 内容变化事件onChange.onChange((value) { this.inputText value; this.showError value.length 2 ? 用户名至少2个字符 : ; })触发时机输入框内容发生任何变化时键盘输入、粘贴、剪切、清空等回调参数value为当前输入框的完整文本内容核心作用实现输入内容与响应式变量的双向绑定并可在回调中实现实时输入校验如示例中的用户名长度校验联动错误提示。2. 剪贴板操作事件覆盖复制、剪切、粘贴三大剪贴板操作可监听操作的文本内容实现自定义剪贴板逻辑示例中手机号输入框添加监听.onCopy((v) console.log(复制, v)) // 复制选中文本时触发 .onCut((v) console.log(剪切, v)) // 剪切选中文本时触发 .onPaste((v) console.log(粘贴, v)) // 向输入框粘贴文本时触发回调参数v为当前操作的文本内容适用场景剪贴板内容校验如粘贴手机号时校验是否为11位、日志记录、自定义粘贴格式处理等。3. 密码状态事件onSecurityStateChange仅对InputType.Password类型生效密码显隐状态变化时触发详情见4.1 密码显隐切换。4. 回车提交事件onSubmit点击键盘回车按钮时触发详情见4.4 回车提交与键盘类型。组件运行效果初始加载页面以白色为背景4个输入框按纵向排列间距均匀均显示浅灰色占位符普通输入框下方无错误提示普通输入框输入字母/数字/中文可正常显示输入特殊符号被过滤计数器实时更新输入字符数2时显示红色错误提示≥2时提示消失点击回车触发提交日志密码输入框输入内容默认显示为●点击右侧小眼睛可切换为明文/密文切换时控制台打印状态最大输入16位字符手机号输入框唤起数字键盘仅允许输入数字底部下划线在输入时变为蓝色计数器显示当前/11支持复制/剪切/粘贴操作控制台打印对应日志清除按钮输入框输入内容后右侧清除按钮始终显示点击按钮可一键清空输入框内容操作便捷整体交互所有输入框点击后显示蓝色光标样式统一适配不同设备屏幕无布局错乱和功能报错。总结双向绑定核心必须使用State/Link等响应式装饰器定义输入绑定变量普通变量无法实现输入内容与组件的联动更新输入类型与键盘匹配使用InputType.PhoneNumber/InputType.Number时会自动唤起数字键盘无需额外配置提升用户体验正则输入过滤编写inputFilter正则表达式时需考虑实际业务场景合理设置允许的字符范围避免过度过滤导致正常输入受影响计数器阈值配置showCounter的thresholdPercentage建议设置为70%-80%提前提醒用户字数即将超限避免突然禁止输入样式统一原则项目中所有输入框建议统一基础样式宽高、圆角、背景、内边距仅根据场景调整输入类型、过滤规则等保证界面一致性清除按钮样式选择高频输入场景如搜索框使用CONSTANT始终显示普通表单场景使用AUTO自动显示避免界面冗余密码输入安全密码输入框建议设置maxLength并配合密码强度校验避免弱密码提升账号安全性事件监听按需使用无需监听所有事件根据业务场景选择必要的事件如表单场景重点监听onChange和onSubmit减少性能消耗。如果这篇文章对你有帮助欢迎点赞、收藏、关注你的支持是持续创作的动力