目录
一、引言：解锁 ArkUI TextInput 的神奇力量
二、ArkUI TextInput 基础大揭秘
（一）创建与基本展示
（二）占位提示文本设置
三、多样样式打造个性输入框
（一）尺寸定制
（二）文本样式雕琢
（三）边框与圆角设计
（四）禁用状态呈现
四、输入内容获取与灵活控制
（一）实时获取输入
（二）光标位置掌控
五、高级特性提升用户体验
（一）输入类型精准设定
（二）最大输入长度限制
（三）输入法回车键类型切换
（四）文本复制粘贴控制
（五）内容过滤与清洗
六、实战案例：让理论落地生根
七、总结与展望：TextInput 的无限可能
一、引言：解锁 ArkUI TextInput 的神奇力量
在日常使用手机应用时，你是否留意过那些看似普通却又无比重要的文本输入框？无论是登录账号时输入用户名和密码，还是在搜索框中查找感兴趣的内容，又或是在评论区分享自己的观点，这些操作都离不开文本输入功能。而在鸿蒙应用开发中，ArkUI 的 TextInput 组件就扮演着这样关键的角色，它是连接用户与应用程序的桥梁，负责收集用户的各种输入信息 。
想象一下，如果没有一个高效、易用的文本输入组件，我们在使用应用时将会面临怎样的困扰？可能无法准确地登录账号，搜索结果总是不尽人意，也难以畅快地表达自己的想法。因此，深入了解和掌握 ArkUI TextInput 组件的使用方法，对于开发者来说至关重要。它不仅能提升应用的交互体验，还能让应用更加贴近用户的需求。接下来，就让我们一起揭开 ArkUI TextInput 的神秘面纱，探索它的各种特性和用法。
二、ArkUI TextInput 基础大揭秘
（一）创建与基本展示
在 ArkUI 中创建 TextInput 组件十分简单，其基本语法如下：
TextInput()
仅仅这样，就可以在界面上生成一个普通的输入框 。不过，这样的输入框略显单调，通常我们会为其添加一些属性来增强用户体验。比如，设置占位提示文本，让用户清楚知道该输入框的用途 。如下示例：
TextInput({
placeholder: '请输入内容'
})
上述代码运行后，会在界面上显示一个带有 “请输入内容” 提示的输入框。当用户点击输入框准备输入时，提示文本会自动消失。 这样，用户就能直观地了解输入框的功能，大大提升了交互的友好性。
（二）占位提示文本设置
placeholder 属性在 TextInput 组件中起着至关重要的作用，它用于设置当输入框内容为空时显示的提示文本，引导用户进行正确输入 。除了设置提示文本内容，我们还可以对提示文本的样式进行调整。
通过 placeholderColor 属性可以设置提示文本的颜色，让其在界面中更加醒目或与整体风格相匹配。示例代码如下：
TextInput({
placeholder: '请输入搜索关键词'
})
.placeholderColor(Color.Gray)
上述代码将提示文本颜色设置为灰色，在浅色背景的界面中，灰色的提示文本既能清晰显示，又不会过于突兀，与整体界面风格协调统一。
而 placeholderFont 属性则可以设置提示文本的字体样式，包括字体大小、粗细、风格等 。例如：
TextInput({
placeholder: '请输入用户名'
})
.placeholderFont({
size: 16,
weight: FontWeight.Bold,
style: FontStyle.Normal
})
这段代码将提示文本的字体大小设置为 16px，字体粗细为加粗，字体风格为正常。通过这些设置，我们可以根据应用的设计需求，灵活调整提示文本的样式，使其更好地融入整个界面布局，为用户提供更优质的视觉体验。
三、多样样式打造个性输入框
（一）尺寸定制
在实际应用开发中，输入框的尺寸需要根据界面布局和用户交互需求进行灵活调整。通过 width 和 height 属性，我们可以轻松控制 TextInput 输入框的宽度和高度。例如，在一个登录界面中，为了使用户名和密码输入框与整体界面风格协调统一，并且在视觉上更加舒适，可以将宽度设置为屏幕宽度的 80%，高度设置为 60vp（vp 是鸿蒙系统中的虚拟像素单位，能更好地适配不同屏幕尺寸） 。示例代码如下：
TextInput({
placeholder: '用户名'
})
.width('80%')
.height(60)
这样设置后，输入框会占据屏幕宽度的 80%，高度为 60vp，无论在手机、平板等不同设备上，都能保持合适的显示比例和大小，为用户提供一致的交互体验。 又比如在一个搜索框中，可能希望它更加细长，以突出搜索功能的简洁性，这时可以将宽度设置得较大，如 300vp，高度设置为相对较小的值，如 40vp ：
TextInput({
placeholder: '搜索内容'
})
.width(300)
.height(40)
通过合理设置尺寸，我们可以让输入框在界面中恰到好处地展示，提升用户操作的便捷性。
（二）文本样式雕琢
fontColor 和 fontSize 属性对于优化输入框内文本的显示效果起着关键作用。fontColor 用于设置文本的颜色，fontSize 则用于设置文本的大小 。在一个以白色为主色调的阅读应用评论输入框中，为了让用户输入的文本更加醒目，与背景形成鲜明对比，可以将文本颜色设置为黑色 ，字体大小设置为 18px 。示例代码如下：
TextInput({
placeholder: '发表你的评论'
})
.fontColor(Color.Black)
.fontSize(18)
这样，用户输入的黑色文本在白色背景上清晰可见，18px 的字体大小也符合大多数用户的阅读习惯，不会过小导致难以辨认，也不会过大影响界面美观。如果是一个儿童教育类应用的输入框，为了吸引儿童用户的注意力，可能会将文本颜色设置为鲜艳的颜色，如红色，字体大小设置得稍大一些，如 20px ：
TextInput({
placeholder: '小朋友，快来输入答案吧'
})
.fontColor(Color.Red)
.fontSize(20)
通过这些文本样式的设置，我们可以根据应用的目标用户群体和整体风格，让输入框内的文本更加美观、易读，增强用户对输入内容的已关注度。
（三）边框与圆角设计
border 属性可以设置输入框的边框宽度和颜色，borderRadius 属性则用于创建圆角效果，这两个属性能够显著提升输入框的视觉吸引力。在一个商务风格的应用中，为了体现专业和稳重，可以为输入框设置一个窄边框，颜色为深灰色 ，并添加适当的圆角 。示例代码如下：
TextInput({
placeholder: '请输入重要信息'
})
.border({
width: 1,
color: Color.DarkGray
})
.borderRadius(8)
这样，1px 宽的深灰色边框既简洁又不失稳重感，8px 的圆角使输入框看起来更加柔和，不会过于生硬，与商务应用的整体风格相得益彰。而在一个社交类应用中，为了营造活泼、友好的氛围，可以将边框颜色设置为明亮的蓝色 ，边框宽度稍宽一些，如 2px ，同时加大圆角半径，如 12px ：
TextInput({
placeholder: '分享你的生活点滴'
})
.border({
width: 2,
color: Color.Blue
})
.borderRadius(12)
这种设计让输入框更加醒目，蓝色边框和较大的圆角给用户一种轻松愉快的感觉，鼓励用户积极分享内容，符合社交应用的特点。
（四）禁用状态呈现
enabled 属性可以将输入框设置为禁用状态，在这种状态下，用户无法在输入框中输入文本。当应用中存在一些只读信息展示场景时，就可以使用禁用状态的输入框 。例如，在一个订单详情页面中，订单编号、下单时间等信息是固定不变的，不需要用户修改，这时就可以将对应的输入框设置为禁用状态 。示例代码如下：
TextInput({
placeholder: '订单编号',
text: '20231010001'
})
.enabled(false)
上述代码将显示一个带有订单编号的输入框，但用户无法对其进行编辑。这样的设计不仅能清晰展示信息，还能避免用户误操作，提升了应用的交互体验和信息展示的准确性 。在一些设置页面中，某些高级设置选项可能需要特定权限才能修改，对于没有权限的用户，也可以将相关输入框设置为禁用状态，提示用户该选项不可用 ，让用户界面更加清晰明了，减少用户的困惑。
四、输入内容获取与灵活控制
（一）实时获取输入
在实际应用中，实时获取用户在 TextInput 输入框中的输入内容是非常常见的需求 。通过 @State 装饰器和 onChange 事件监听器，我们可以轻松实现这一功能。首先，使用 @State 装饰器定义一个状态变量，用于存储输入框中的文本内容 。例如：
@Entry
@Component
struct InputPage {
@State inputText: string = '';
build() {
Column() {
TextInput({
placeholder: '请输入内容',
text: this.inputText
})
.onChange((value: string) => {
this.inputText = value;
})
Text('您输入的内容是：' + this.inputText)
}
.width('100%')
}
}
在上述代码中，@State 装饰器定义了一个名为 inputText 的状态变量，初始值为空字符串 。TextInput 组件的 text 属性绑定了这个状态变量，这样输入框的初始文本就会显示为状态变量的值 。当用户在输入框中输入内容时，onChange 事件会被触发，其回调函数中的 value 参数就是当前输入框中的最新内容 ，我们将其赋值给 inputText 状态变量，从而实现了输入内容的实时更新 。同时，通过 Text 组件展示了用户输入的内容，随着输入框内容的变化，Text 组件显示的内容也会实时改变，让用户能够直观地看到自己输入的内容，增强了交互的实时反馈性。
（二）光标位置掌控
在一些特定的交互场景中，我们需要精确控制光标的位置，以提供更好的用户体验 。这时，就可以使用 TextInputController 来实现这一功能 。首先，导入 TextInputController 模块，并创建一个 TextInputController 实例 。例如：
import { TextInputController } from '@ohos/arkui';
@Entry
@Component
struct CursorPage {
controller: TextInputController = new TextInputController();
build() {
Column() {
TextInput({
placeholder: '请输入内容',
controller: this.controller
})
Button('将光标移到文本末尾')
.onClick(() => {
const textLength = this.controller.getText().length;
this.controller.caretPosition(textLength);
})
}
.width('100%')
}
}
在上述代码中，我们创建了一个 TextInputController 实例 controller，并将其传递给 TextInput 组件的 controller 属性，这样就建立了控制器与输入框的关联 。当用户点击 “将光标移到文本末尾” 按钮时，onClick 事件的回调函数会被执行 。在回调函数中，首先通过 controller.getText () 方法获取输入框中的当前文本内容，并计算其长度 ，然后使用 controller.caretPosition () 方法将光标位置设置为文本的末尾，实现了光标的动态控制 。此外，还可以通过 caretColor 属性来改变光标的颜色，使光标在界面中更加醒目或与整体风格相匹配 。例如：
TextInput({
placeholder: '请输入内容',
controller: this.controller
})
.caretColor(Color.Red)
上述代码将光标的颜色设置为红色，在一些需要突出显示光标的场景中，这种设置可以吸引用户的注意力，提升用户操作的便捷性和准确性 。
五、高级特性提升用户体验
（一）输入类型精准设定
TextInput 组件的 type 属性支持多种输入类型，通过设置 type 属性，我们可以根据不同的输入需求，让输入法提供更贴合的输入方式，提高用户输入的准确性和效率 。
其中，InputType.Password 用于密码输入模式，在用户输入密码时，输入的字符会以特定的掩码（如星号 “*” 或圆点 “・”）显示，有效保护用户密码的安全 。比如在各类应用的登录界面，当用户输入密码时，就会使用这种模式，防止他人窥探密码内容 。示例代码如下：
TextInput({
placeholder: '请输入密码'
})
.type(InputType.Password)
InputType.Email 用于 e-mail 地址输入模式，在用户输入时，输入法可能会自动提供与邮箱输入相关的联想和便捷输入方式 。例如，在注册账号时，需要填写邮箱地址，使用该模式，用户在输入 “@” 符号时，输入法可能会自动联想常见的邮箱后缀，如 “qq.com”“gmail.com” 等 ，方便用户快速输入完整的邮箱地址 。代码示例如下：
TextInput({
placeholder: '请输入邮箱地址'
})
.type(InputType.Email)
InputType.Number 用于纯数字输入模式，在需要用户输入数字的场景中，如年龄、数量、金额等，使用该模式可以避免用户误输入其他字符 。比如在电商应用中，用户输入购买商品的数量时，就可以使用这种输入类型，确保输入的内容都是有效的数字 。示例代码如下：
TextInput({
placeholder: '请输入购买数量'
})
.type(InputType.Number)
InputType.PhoneNumber 用于电话号码输入模式，在输入电话号码时，输入法可能会提供数字键盘和一些与电话号码相关的便捷输入功能 。比如在填写联系方式时，用户可以更方便地输入电话号码，并且输入法可能会自动对号码进行格式化，使其符合常见的电话号码格式 。代码示例如下：
TextInput({
placeholder: '请输入手机号码'
})
.type(InputType.PhoneNumber)
通过合理选择输入类型，我们可以为用户提供更加智能化、人性化的输入体验，让应用程序的交互更加流畅和高效 。
（二）最大输入长度限制
maxLength 属性用于设置用户在 TextInput 输入框中最多能输入的字符数，在很多场景中都有着重要的应用 。比如在设置密码时，为了保证密码的安全性和合理性，通常会限制密码的长度 。一般来说，密码长度可能设置为 8 – 16 位之间，这时就可以使用 maxLength 属性来实现这一限制 。示例代码如下：
TextInput({
placeholder: '请设置密码'
})
.maxLength(16)
上述代码将密码输入框的最大输入长度设置为 16 位，当用户输入的字符数达到 16 位时，就无法再继续输入，这样可以避免用户设置过长或过短的密码，提高密码的安全性 。
在短信发送场景中，由于短信字数有限制，也可以使用 maxLength 属性来限制用户输入的短信内容长度 。例如，常见的短信字数限制为 70 个字（包括标点符号），可以这样设置：
TextInput({
placeholder: '请输入短信内容'
})
.maxLength(70)
通过设置 maxLength 属性，不仅可以满足业务需求，还能避免因用户输入过多内容而导致的各种问题，如数据存储溢出、网络传输错误等，提升应用程序的稳定性和可靠性 。
（三）输入法回车键类型切换
enterKeyType 属性可以设置输入法回车键的类型，通过设置不同的值，可以更改虚拟键盘右下角按钮的标题类型 。例如，当设置 enterKeyType 为 EnterKeyType.Search 时，虚拟键盘右下角的按钮会显示为 “搜索” ，这种设置在搜索框中非常实用 。当用户在搜索框中输入完关键词后，点击 “搜索” 按钮，就可以直接触发搜索操作 。示例代码如下：
TextInput({
placeholder: '请输入搜索内容'
})
.enterKeyType(EnterKeyType.Search)
同时，配合 onSubmit 事件，我们可以监听用户点击输入法回车键的操作，并根据回车键的类型执行相应的逻辑 。例如：
TextInput({
placeholder: '请输入内容'
})
.enterKeyType(EnterKeyType.Send)
.onSubmit((enterKey) => {
if (enterKey === EnterKeyType.Send) {
// 执行发送操作的逻辑代码
console.log('用户点击了发送按钮');
}
})
上述代码中，当用户在输入框中输入内容后，点击显示为 “发送” 的回车键时，onSubmit 事件的回调函数会被触发，在回调函数中，通过判断 enterKey 的值，我们可以得知用户点击的是哪种类型的回车键，从而执行相应的操作 。这种设置可以让用户在输入完成后，直接通过点击回车键来完成下一步操作，无需再寻找其他按钮，大大提高了交互效率 。
（四）文本复制粘贴控制
在移动设备上，用户通常可以通过触摸手势呼叫出交互菜单，从而进行复制、粘贴等操作 。TextInput 组件的 copyOption 属性可以设置文本是否可复制粘贴 。当设置 copyOption 为 None 时，文本框中的文字不能复制或剪切，仅支持粘贴操作 。例如，在一些需要用户手动输入重要信息，且不希望用户通过复制粘贴方式输入的场景中，就可以使用这种设置 。示例代码如下：
TextInput({
placeholder: '请手动输入重要信息'
})
.copyOption(CopyOption.None)
此外，TextInput 组件还提供了 onCopy、onCut、onPaste 等回调方法，用于监听用户的复制、剪切、粘贴操作 。例如，当用户进行复制操作时，onCopy 回调方法会被触发，我们可以在回调函数中获取用户复制的文本内容 。示例代码如下：
TextInput({
placeholder: '请输入内容'
})
.onCopy((value) => {
console.log('用户复制的文本内容是：' + value);
})
上述代码中，当用户在输入框中选中内容并点击复制时，onCopy 回调函数会打印出用户复制的文本内容 。通过这些回调方法，我们可以根据用户的操作执行一些自定义的逻辑，如记录用户的操作行为、对粘贴的内容进行格式校验等，进一步增强应用程序的交互性和功能性 。
（五）内容过滤与清洗
inputFilter 属性可以用于检查和清洗用户输入的内容，确保输入符合特定的格式或规则 。例如，在填写电话号码的输入框中，我们希望用户只能输入数字和特定的分隔符（如 “-”“ ” 等），不允许出现字母或汉字 。这时，可以使用 inputFilter 属性来实现这一需求 。示例代码如下：
TextInput({
placeholder: '请输入电话号码'
})
.inputFilter((input) => {
const validChars = /^[0 - 9-s]+$/;
return validChars.test(input)? input : '';
})
在上述代码中，inputFilter 属性接收一个回调函数，该函数会在用户每次输入内容时被调用 。回调函数中的 input 参数表示用户当前输入的内容，我们通过正则表达式 /^[0 – 9-s]+$/ 来检查输入内容是否只包含数字、“-” 和空格 。如果输入内容符合规则，则返回输入内容；否则，返回空字符串，即过滤掉不符合规则的输入 。这样，用户在输入电话号码时，就只能输入有效的字符，保证了输入内容的准确性和规范性 。在一些需要过滤敏感词的场景中，也可以使用类似的方法，通过正则表达式或敏感词库来检查和替换用户输入的内容，维护应用程序的健康环境 。
六、实战案例：让理论落地生根
为了更直观地展示 ArkUI TextInput 组件在实际开发中的应用，我们来构建一个用户注册页面。这个页面包含用户名、密码、确认密码、邮箱和手机号码等输入框，通过综合运用前面介绍的各种属性和方法，实现一个功能完善、用户体验良好的注册界面 。
首先，创建一个新的组件，定义页面的基本布局和样式 ：
@Entry
@Component
struct RegisterPage {
@State username: string = '';
@State password: string = '';
@State confirmPassword: string = '';
@State email: string = '';
@State phone: string = '';
build() {
Column() {
Text('用户注册')
.fontSize(24)
.fontWeight(FontWeight.Bold)
.margin({ top: 30 })
TextInput({
placeholder: '请输入用户名',
text: this.username
})
.width('80%')
.height(50)
.margin({ top: 20 })
.border({ width: 1, color: Color.Gray })
.borderRadius(8)
.onChange((value: string) => {
this.username = value;
})
TextInput({
placeholder: '请输入密码',
text: this.password
})
.width('80%')
.height(50)
.margin({ top: 20 })
.border({ width: 1, color: Color.Gray })
.borderRadius(8)
.type(InputType.Password)
.onChange((value: string) => {
this.password = value;
})
TextInput({
placeholder: '请确认密码',
text: this.confirmPassword
})
.width('80%')
.height(50)
.margin({ top: 20 })
.border({ width: 1, color: Color.Gray })
.borderRadius(8)
.type(InputType.Password)
.onChange((value: string) => {
this.confirmPassword = value;
})
TextInput({
placeholder: '请输入邮箱地址',
text: this.email
})
.width('80%')
.height(50)
.margin({ top: 20 })
.border({ width: 1, color: Color.Gray })
.borderRadius(8)
.type(InputType.Email)
.onChange((value: string) => {
this.email = value;
})
TextInput({
placeholder: '请输入手机号码',
text: this.phone
})
.width('80%')
.height(50)
.margin({ top: 20 })
.border({ width: 1, color: Color.Gray })
.borderRadius(8)
.type(InputType.PhoneNumber)
.onChange((value: string) => {
this.phone = value;
})
Button('注册')
.width('80%')
.height(50)
.backgroundColor(Color.Blue)
.fontColor(Color.White)
.borderRadius(8)
.margin({ top: 30 })
.onClick(() => {
// 在这里添加注册逻辑，如验证输入内容、调用后端接口等
if (this.password!== this.confirmPassword) {
console.log('两次输入的密码不一致');
return;
}
// 其他验证逻辑和注册接口调用代码
console.log('注册成功，用户名：' + this.username + '，邮箱：' + this.email + '，手机号码：' + this.phone);
})
}
.width('100%')
.alignItems(HorizontalAlign.Center)
}
}
在上述代码中：
首先使用 @State 装饰器定义了五个状态变量，分别用于存储用户名、密码、确认密码、邮箱和手机号码 。
每个 TextInput 组件都设置了 placeholder 属性，用于显示提示文本 ，width 和 height 属性控制输入框的尺寸 ，margin 属性设置外边距 ，border 和 borderRadius 属性设置边框样式 。
根据输入内容的类型，分别设置了 type 属性，如密码输入框使用 InputType.Password，邮箱输入框使用 InputType.Email，手机号码输入框使用 InputType.PhoneNumber ，确保输入法提供合适的输入方式 。
通过 onChange 事件监听器，实时获取用户输入的内容，并更新相应的状态变量 。
最后，Button 组件用于触发注册操作，在 onClick 事件的回调函数中，添加了简单的密码一致性验证逻辑，当两次输入的密码不一致时，给出提示；如果验证通过，可以进一步添加调用后端注册接口等逻辑代码 。
通过这个实战案例，我们可以看到如何将 ArkUI TextInput 组件的各种属性和方法有机结合，打造出一个实用的用户注册页面 。在实际开发中，还可以根据具体需求，进一步完善和优化这个页面，如添加输入框的校验提示、密码强度检测等功能，为用户提供更优质的注册体验 。
七、总结与展望：TextInput 的无限可能
ArkUI TextInput 组件作为鸿蒙应用开发中与用户交互的重要桥梁，凭借其丰富的属性和强大的功能，为开发者打造优质输入体验提供了坚实的基础 。从基础的创建与展示，到多样样式的定制，再到输入内容的获取与高级特性的运用，每一个环节都蕴含着提升应用交互性和用户满意度的潜力 。
在实际项目开发中，希望大家能够充分发挥想象力和创造力，将 TextInput 组件的特性与应用场景紧密结合 。无论是社交类应用中用户的聊天输入、电商类应用中的搜索与订单信息输入，还是工具类应用中的参数设置输入，都可以通过巧妙运用 TextInput 组件，让用户的输入过程更加流畅、高效 。
随着鸿蒙系统的不断发展和完善，我们有理由期待 ArkUI TextInput 组件在未来会有更多的优化和创新 。也许会引入更智能的输入预测和联想功能，进一步提高用户输入速度；也许会在无障碍输入方面有更大的突破，让更多特殊群体能够方便地使用应用 。让我们共同期待，在未来的鸿蒙应用开发中，TextInput 组件能够绽放出更加耀眼的光芒，为用户带来更多惊喜 。如果你在使用 ArkUI TextInput 组件的过程中有任何心得或问题，欢迎在评论区留言分享，让我们一起交流进步 ！
暂无评论内容