ArkTS 文本输入组件（TextInput）详解

鸿蒙第四期开发者活动

--- HarmonyOS ArkTS 常用基础组件开发指南

TextInput 是 ArkTS 提供的原生输入框组件，用于让用户输入文本。它不仅能展示可编辑的文字，还能配合键盘事件、边框样式、占位提示、状态控制等做完整的表单交互。(developer.huawei.com)

一、TextInput 到底是什么

TextInput 是一个可交互的输入框组件 ，类似于网页的 <input> 或移动端的输入框，它既支持单行文本，也支持多行文本。

你可以用它做：

登录页的账号/密码输入
评论/留言输入框
搜索框
表单项
多行笔记/反馈内容

它既可以单独放，也可以嵌在 Form/Row/Flex 等容器里搭配其他 UI。

二、TextInput 最常见写法（一步到位）

这是一个最基础、最常见的单行输入框写法：

scss 复制代码

 @State private username: string = '';
 
 TextInput()
   .text(this.username)                        // 双向或单向绑定
   .placeholder('请输入用户名')                 // 占位提示
   .placeholderColor(0xFF999999)                // 占位文字颜色
   .fontSize(16)                                // 输入文字大小
   .fontColor(0xFF333333)                       // 输入文字颜色
   .onTextChange((evt) => this.username = evt)   // 输入实时同步

这段代码想表达的是：

这个输入框显示当前 username
用户每输入一个字符，就把它存到 @State username 里
输入框还带提示文字（placeholder）

这种写法是"输入框 + 状态联动"的标准姿势。

三、关键属性解释（实战角度）

下面列了一些你在项目里真会用到的属性，按照"为什么要用"和"怎么配合写"来说明。

1) `.text(value)` --- 绑定值

这是输入框的核心数据源。在 ArkTS 里你可以把它绑定到一个 @State 变量，这样 UI 会自动随着状态变化重新渲染。

scss 复制代码

 TextInput().text(this.feedbackText)

在表单里，这通常配合提交按钮去收集用户输入内容。

2) `.placeholder(text)` --- 占位提示

占位提示是 UX 必须的提示性文字，它不是输入内容，而是用户还没输入时显示的提示。

arduino 复制代码

 .placeholder('请输入评论内容')

搭配浅灰色会更符合用户预期：

scss 复制代码

 .placeholderColor(0xFF999999)

3) `.fontSize(...)` / `.fontColor(...)`

输入文字和提示文字的样式：

scss 复制代码

 .fontSize(16)
 .fontColor(0xFF000000)

建议：输入文字大小遵循设计规范，不要太大也不要太小；placeholder 不要用纯黑，避免误以为已输入。

4) `.secure(true)` --- 密码输入模式

密码输入框最常用的就是这个属性：

scss 复制代码

 TextInput().secure(true)

开启后用户输入内容会被屏蔽（• 这种视觉效果），非常适合密码/敏感字符输入。

5) `.keyboardType(...)` --- 键盘类型控制

键盘类型对 UX 很重要，尤其是输入数字/邮箱/电话时：

常见取值：

KeyboardType.Number → 数字键盘
KeyboardType.Email → 邮箱键盘（带 @ 键）
KeyboardType.Default → 常规键盘

scss 复制代码

 .keyboardType(KeyboardType.Email)

比如手机号/验证码输入框就应该用数字键盘，用户敲起来更快。

6) `.maxLength(n)` --- 最大输入长度

这是做规则限制最常用的属性：

scss 复制代码

 TextInput().maxLength(11)

如果需要限制手机长度、验证码长度、身份证号等，这个属性非常清晰。

四、事件回调（实时感知用户输入）

让输入框"有反应"才有意义。以下是你最会用到的几种事件监听：

1) `.onTextChange(evt => ...)`

最常用的输入监听，用户每敲一个字符就触发：

arduino 复制代码

 .onTextChange((text) => {
   this.memo = text;
 })

用它可以做到：

✔ 实时保存草稿 ✔ 实时校验字符是否合法 ✔ 限制非法字符（数字/字母以外过滤）

2) `.onSubmit(() => ...)`

当用户敲 Enter/完成按钮时触发，比如表单提交、搜索确认：

kotlin 复制代码

 .onSubmit(() => {
   this.doSearch(this.searchText)
 })

这是表单交互里最常用的"确定动作回调"。

🛠 五、TextInput 常见布局场景（实用示例）

下面是结合常见 UI 场景写的 TextInput 组合写法。

1. 登录页的输入区域

scss 复制代码

 Column({ space: 12 }) {
   TextInput()
     .text(this.username)
     .placeholder('请输入用户名')
     .keyboardType(KeyboardType.Default)
     .fontSize(16)
     .fontColor(0xFF000000)
 
   TextInput()
     .text(this.password)
     .placeholder('请输入密码')
     .secure(true)
     .fontSize(16)
     .fontColor(0xFF000000)
 }
 .padding(16)

这个组合写法几乎满足所有登录页需求：一行账号一行密码，两种 keyboard/secure 模式。

2. 评论输入框（带实时字数统计）

scss 复制代码

 Column({ space: 6 }) {
   TextInput()
     .text(this.comment)
     .placeholder('写下你的评论...')
     .maxLength(200)
     .onTextChange((txt) => {
       this.comment = txt
       this.remain = 200 - txt.length
     })
 
   Text(`${this.remain} 字`)
     .fontSize(12)
     .fontColor(0xFF888888)
     .textAlign(TextAlign.End)
 }

实时统计字数的需求在社交/评论功能里非常常见，这种写法几乎可以直接套用。

3. 带边框的表单输入

单纯 TextInput 默认没有边框，如果你想做"表单项带边框"，一般配合 Box/Rect 组合：

scss 复制代码

 Stack({ alignContent: Alignment.CenterStart }) {
   Rect()
     .width('100%')
     .height(44)
     .strokeWidth(1)
     .color(0xFFCCCCCC)
     .radius(8)
 
   TextInput()
     .text(this.email)
     .placeholder('请输入邮箱')
     .fontSize(15)
     .padding({ left: 12 })
 }

注意：

Rect 负责边框，
TextInput 负责文本、事件与输入逻辑
两者叠在一起视觉才成一个完整输入框

这种写法在表单页、设置页、完善资料页特别常见。

六、容易踩的坑与正确写法

下面是一些初学者或项目里常犯的坑，先讲清楚：

坑 1：TextInput 直接在 Row 里不居中

如果你写：

scss 复制代码

 Row() {
   TextInput()
   Text('单位')
 }

你会发现"输入框文字"和旁边文字对不齐。正确写法是给 TextInput 一个明确高度或用 alignItems 控制对齐：

scss 复制代码

 Row({ alignItems: ItemAlign.Center }) {
   TextInput().height(44)
   Text('单位')
 }

坑 2：没有用 keyboardType 导致输入体验差

如果你要输入手机号、不加 .keyboardType(KeyboardType.Number) 用户键盘还是字母键盘，这种体验很糟糕。一定要配合类型写。

坑 3：忘了 onTextChange 绑定，结果 UI 不更新

很多人把输入状态写成回调但没连 @State，就出现了"输入完 UI 不动"的 bug。记住：输入的值要存到 @State 才能渲染更新。

七、实战建议与样式规范（像人写的）

统一字体规范：输入框文字统一大小/颜色，不要在不同页乱设
placeholder 提示：一定要有提示，不然空状态用户不知道要填什么
边框/背景统一：用 Rect/Stack 组合 TextInput 形成视觉统一风格
最大长度 + 字数提示：评论/描述类输入加上更友好
收起键盘：在 onSubmit 里处理收起键盘的逻辑（SDK 操作或状态控制）

🏁 八、总结

功能	用法
显示输入内容	`.text(...)`
占位提示	`.placeholder(...)`
密码隐藏	`.secure(true)`
键盘类型	`.keyboardType(...)`
最大长度	`.maxLength(...)`
输入监听	`.onTextChange(...)`
提交事件	`.onSubmit(...)`

ArkTS 文本输入组件（TextInput）详解