企业官网建设流程全解析

最近在做登录模块时，有个细节反复被问到：HarmonyOS 里实现输入框，到底是用 TextField 还是 TextInput？这个问题看起来小，却拦住不少从其他平台转过来的开发者。原因很简单，Android 里习惯叫 EditText，iOS 里是 UITextField，Flutter 里是 TextField，而到了 HarmonyOS 的 ArkUI 声明式开发环境中，单行输入框组件叫 TextInput。标题里的 TextField，在目前主流工程里对应到的实际组件就是 TextInput。

这篇内容是我把写输入框这几年攒下的经验整理了一遍，不按文档顺序讲，而是按一个实际项目从零搭建时会遇到的问题顺序展开，争取你看完能直接套用。无论是刚接触 ArkUI 的新手，还是从 Android、iOS、Flutter 转过来了老手，都会遇到“组件名对不上”“状态更新不上”“键盘把页面顶飞”这些事。下面一个个拆开说。

1. TextField 去哪了：先解决命名混乱

1.1 不同技术栈对输入框的称呼

跨平台开发最影响效率的不是语法，而是“名词对照”。同样是输入框，每个框架叫法都不同：

刚开始从其他平台切到 HarmonyOS 时，最容易做的事就是在文档里全局搜索“TextField”，结果搜不到，然后开始怀疑自己是不是找错了文档。其实没错，只是这一套 UI 框架用了自己的命名。记住一个快捷键级别的结论：想在 ArkUI 里写单行输入框，找 TextInput；想写多行输入框，找 TextArea。

1.2 TextInput 和 TextArea 的实际分工

TextInput 负责单行输入，比如用户名、手机号、验证码、搜索词；TextArea 负责多行文本，比如备注、自我介绍、聊天消息。两者的构造参数非常像，核心都是placeholder占位符和text当前值。

TextInput({ placeholder: '请输入用户名', text: this.username })

这一行代码就能在页面上放出一个可输入的输入框。但真正放到项目里，光靠构造参数是不够的，后面会看到text参数只是初始值，用户输入的内容并不会自动同步回当前页面的状态变量，必须配合事件回调。

1.3 为什么有些人嘴里说的“TextField”和文档对不上

老教程或论坛里偶尔还能看到textfield的写法，这是因为早年的类 Web 页面范式和后来的声明式范式之间确实存在过不同命名习惯。如果你打开一个工程，看到页面是一个@Entry @Component struct修饰的组件，那就是 ArkTS 声明式工程，输入框统一用 TextInput 和 TextArea。如果看到的是类似网页标签的写法，那是另一套旧的 UI 范式。

要判断当前工程属于哪一套，不用记复杂知识，打开一个页面文件看结构就行。声明式页面有明显的build() { ... }方法，组件通过链式调用来设置属性。新旧两套的 API 并不互通，千万不要把别的工程里的 TextField 代码直接抄进你的 ArkUI 页面，否则第一行就报错。

2. 第一行代码：跑起来并让状态真正有效

2.1 新建页面放一个输入框

先给一个最小可运行示例，把输入框摆在页面上：

@Entry @Component struct InputDemoPage { build() { Column({ space: 16 }) { TextInput({ placeholder: '请输入内容' }) .width('100%') .height(44) .backgroundColor('#F5F5F5') .borderRadius(8) Text('这是一个输入框示例') } .padding(16) .width('100%') .height('100%') } }

这段代码能在页面顶部渲染一个浅灰色圆角输入框。width('100%')让输入框占满整行，height(44)是移动端比较常见的单行输入框高度。这里只展示了最简单的属性链，真正到了项目里，还要处理输入值、校验、键盘行为，下面逐步加。

2.2 text 与 onChange：受控状态的入场

很多新手第一次写输入框时，会在构造参数里给text赋一个状态变量，然后发现不管怎么输入，界面上的文字都没有变化，或者输入框根本无法正常更新。问题通常出在少写了一个onChange。

@State inputValue: string = '' build() { Column({ space: 8 }) { TextInput({ placeholder: '请输入内容', text: this.inputValue }) .onChange((value: string) => { this.inputValue = value }) Text('当前输入：' + this.inputValue) } .padding(16) .width('100%') }

text传入的更像是一个“受控值”。用户在输入框里打字时，组件内部会更新显示，但如果没有onChange把最新内容写回@State变量，页面状态始终停留在初始值。这和你用遥控器调温度很像：空调面板显示新温度，但遥控器记录的还是旧温度，下次操作就会乱套。

onChange回调会把当前完整文本传出来，收到后同步给状态变量。这样页面其他地方要展示、校验、提交，都能拿到最新值。

2.3 默认值、清空按钮与“值去哪了”的排查思路

给输入框设置默认值很简单，在构造参数的text里直接传初始字符串，或者让@State变量初始化为某个值。需要特别留意的是“清空”场景。如果产品设计里要求输入框旁边出现一个清除按钮，最简单的做法是使用组件自带的清除能力：

TextInput({ placeholder: '搜索', text: this.keyword }) .showCancelButton(true) .onChange((value: string) => { this.keyword = value })

点击清除按钮后，输入框内容会清空，onChange会回调一个空字符串，状态变量随之更新。这是典型的“组件内部行为通过回调反馈到状态”的例子。

如果你在项目里发现某个输入框内容变了，但提交时数据还是空的，排查顺序很固定：先看@State变量有没有声明，再看有没有写onChange，最后看onChange里到底有没有把参数值赋回去。这三步能覆盖绝大多数“值丢了”的情况。

3. 输入类型、长度限制与校验落地

3.1 type 属性决定的不只是键盘

type()属性控制输入框的类型，它会同时影响系统弹出的键盘布局和输入内容的表现形式。最常用的几种类型：

代码层面只是加一行属性：

TextInput({ placeholder: '请输入验证码', text: this.code }) .type(InputType.Number) .maxLength(6)

这里有个容易踩的认知偏差：Number类型通常弹出的是纯数字键盘，适合验证码、订单号这类纯数字场景，但不一定支持小数点和负号。如果做金额输入，想要“数字 + 小数点”，单靠InputType.Number可能不够，更稳妥的做法是用InputType.Normal，在onChange里过滤非法字符。具体用哪种，要以你当前 SDK 的枚举行为为准，写完一定要在真机上按一下小数点。

3.2 maxLength 不是一把万能锁

maxLength能限制用户输入的字符长度，但它不是一个严格的业务校验工具。

首先，用户可以通过粘贴超长文本进入输入框，不同系统版本对粘贴超长时的处理不太一致。其次，在使用中文、日文等组合输入法时，选词阶段的拼音串和最终上屏的汉字会经历多次变化，过程中onChange拿到的内容可能暂时超出长度。所以，maxLength适合做体验层的软限制，真正提交数据前还要再做一次长度判断。

.onChange((value: string) => { if (value.length > 11) { value = value.substring(0, 11) } this.phone = value })

这段代码是在回调里手动截断，用来补足maxLength在某些场景下不够严格的短板。业务上如果要求“超过长度立刻提示用户”，就不能只靠截断，而是要在回调里判断长度后更新一个错误提示状态。

3.3 过滤、格式化与失焦校验

输入框的验证逻辑建议拆成两层：输入过程中的格式化和输入结束后的校验。格式化放onChange，比如只允许数字、自动过滤空格；校验放onBlur，比如手机号位数是否完整、密码长度是否满足要求。

@State phone: string = '' @State phoneError: string = '' build() { Column({ space: 8 }) { TextInput({ placeholder: '请输入手机号', text: this.phone }) .type(InputType.PhoneNumber) .maxLength(11) .onChange((value: string) => { this.phone = value.replace(/\D/g, '') }) .onBlur(() => { if (!/^1[3-9]\d{9}$/.test(this.phone)) { this.phoneError = '手机号格式不正确' } else { this.phoneError = '' } }) if (this.phoneError) { Text(this.phoneError) .fontSize(12) .fontColor('#E84026') .margin({ top: 4 }) } } .padding(16) .width('100%') }

replace(/\D/g, '')的作用是把所有非数字字符去掉，避免用户在手机号输入框中误输入字母和符号。onBlur是焦点离开时触发的事件，这时候做完整校验用户体验最好，因为用户已经完成输入，不会出现“打一个字就报一次错”的烦躁体验。

3.4 密码输入框与登录表单的组合写法

登录页几乎必然有手机号和密码两个输入框。密码框需要设置成掩码模式，同时经常要支持“眼睛”图标切换明文和密文。

@State password: string = '' @State showPassword: boolean = false TextInput({ placeholder: '请输入密码', text: this.password }) .type(this.showPassword ? InputType.Normal : InputType.Password) .maxLength(20) .onChange((value: string) => { this.password = value })

通过一个布尔状态来控制type()的切换：showPassword为true时，用Normal类型明文显示；为false时，用Password类型掩码显示。这样做功能上是通的，但要注意，切换类型时有可能会让软键盘收起再弹出，在部分机型上体验会有点跳。如果对流畅度要求很高，可以进一步研究组件是否支持不收起键盘的显隐方案，不同 API 版本表现不一样，最好真机验证。

4. 焦点、回车键与软键盘布局：交互层的细节

4.1 自动聚焦与手动聚焦

页面打开时希望某个输入框自动获得焦点，可以用defaultFocus(true)：

TextInput({ placeholder: '请输入验证码' }) .defaultFocus(true)

一个页面里通常只设置一个默认焦点，如果多个输入框都设置了，实际生效的可能是第一个。

想通过按钮点击把焦点移到某个输入框，可以使用id配合焦点请求：

TextInput({ placeholder: '请输入验证码' }) .id('codeInput') Button('聚焦到验证码') .onClick(() => { focusControl.requestFocus('codeInput') })

这里的关键是输入框的id必须和请求时传入的字符串一致。部分 SDK 版本中请求焦点可能改由页面上下文中的焦点控制器发起，如果你在当前版本里直接调用全局函数不生效，优先查一下当前版本的焦点管理入口。焦点涉及键盘弹出和回收，属于和系统软键盘强相关的行为，真机上测才准。

4.2 回车键行为：从“默认换行”到“按钮可点”

移动端软键盘右下角通常会有一个操作按钮，默认可能是“换行”“完成”“搜索”等。ArkUI 输入框可以通过enterKeyType设置按钮文案和语义，配合onSubmit完成动作：

TextInput({ placeholder: '搜索商品' }) .enterKeyType(EnterKeyType.Search) .onSubmit(() => { this.doSearch() })

将右下角按钮设置成“搜索”后，用户点击该按钮会触发onSubmit，这是比监听onChange更合理的搜索发起时机。登录场景可以设置成EnterKeyType.Done，在onSubmit里调用登录接口；多输入框表单可以设置成EnterKeyType.Next，让用户从上一个输入框跳到下一个。这个变量很小，但对输入体验的提升非常明显。

4.3 键盘遮挡与滚动避让

输入框被软键盘挡住是移动端最经典的布局问题之一。凡是输入框位于页面下方，键盘弹起后在部分设备上就会遮挡输入区域。最常见的处理思路是用Scroll把整个表单包起来，并保证输入框所在区域可以通过滚动进入可视范围。

Scroll() { Column({ space: 16 }) { TextInput({ placeholder: '用户名' }) TextInput({ placeholder: '密码' }) Button('登录') } .width('100%') .padding({ bottom: 120 }) } .width('100%') .height('100%')

给底部预留 120 左右的高度，是为了防止键盘弹出时最后一个按钮被完全盖住。不同输入法键盘高度不一样，这个值不能照抄，要在真机上反复调。电脑模拟器上看起来正常的布局，到手机上可能就出问题，键盘避让必须实测。

5. 把输入框改成产品设计稿想要的样子

5.1 字号、颜色、光标和占位符

输入框的默认样式很朴素，项目里一般要统一调整字体颜色、占位符颜色、光标颜色等：

TextInput({ placeholder: '请输入昵称', text: this.nickname }) .fontSize(14) .fontColor('#1A1A1A') .placeholderColor('#B0B3B8') .caretColor('#2B6ACF') .textAlign(Align.Start)

fontColor控制输入文字颜色，placeholderColor控制占位符颜色，caretColor控制光标颜色。这些值应该和设计稿对齐，不要自己临时拍脑袋选颜色。特别注意深色模式下，默认占位符和输入文字颜色可能和浅色模式不同，如果设计中只有一套浅色样式，记得在深色模式下再看一眼。

5.2 背景、边框、圆角和无边框风格

市面上常见的输入框有两种形态：填充背景的圆角框，以及完全无边框的底部线框。填充背景的写法很简单：

TextInput({ placeholder: '搜索商品' }) .backgroundColor('#F2F3F5') .borderRadius(20) .height(36) .padding({ left: 12, right: 12 })

这种风格常用于搜索框，浅灰色背景加胶囊圆角，视觉上很干净。需要边框线时可以用通用边框属性：

.border({ width: 1, color: '#D9D9D9', radius: 6 })

需要注意，如果同时使用borderRadius通用属性和border中的radius参数，不同 API 版本可能存在优先级不一致的情况，建议统一由一处控制圆角，避免出现显示异常。无边框风格则更简单，不设置边框和背景色，只依赖字体颜色和占位符颜色完成视觉表达。

5.3 密码可见性切换与系统内置图标

密码框默认会按系统规则显示掩码，部分版本还自带一个“显示密码”的小图标。如果产品有自己的交互设计，希望用自定义按钮控制明文/密文，最好关掉系统内置图标：

TextInput({ placeholder: '密码', text: this.password }) .type(InputType.Password) .showPasswordIcon(false)

关闭系统图标可以避免出现两个切换入口，对交互一致性很重要。是否支持showPasswordIcon以及默认值是什么，不同版本有差别，接入时先查当前 SDK 的组件属性说明，再决定是自己写切换按钮还是用内置能力。

5.4 封装一个输入组件之前，先想清楚这几件事

当项目里多个页面需要相同风格的输入框时，很多人会想封一个通用组件。我的建议是：先别急着抽象。如果只是两三个页面，直接在页面里写 TextInput 反而更清晰。真正适合封装的场景有几个共性：校验规则统一、视觉样式统一、交互行为统一，比如都是“带错误提示 + 前置图标 + 清空按钮”的登录输入框。

封装时要特别注意状态穿透问题。输入框自身维护视觉状态，但真正的数据要交给父页面持有。一旦状态层级过深，排查问题会很痛苦。如果决定封装，尽量把“只负责 UI 展示和事件上报”这种单向逻辑做到底，把校验和业务判断留在页面层。

6. 我在实际项目里踩过的输入框的坑

6.1 中文输入法下 onChange 的“假截止”

在中文输入法下，用户输入拼音时onChange可能会触发多次，而且拿到的不一定是最终上屏的汉字。曾经有同事在onChange里直接做“只允许输入中文”的过滤，结果用户打拼音“zhang”时，字母被过滤掉，汉字根本选不出来。

正确的做法是区分时机。需要实时过滤的场景，尽量交给输入类型和常用过滤规则处理；一旦涉及语言文本的合法性判断，放到onBlur或onSubmit里做。搜索场景如果要根据输入内容实时请求，也建议加防抖，避免拼音输入时请求频繁触发：

private searchTimer: number = -1 doSearchByInput() { clearTimeout(this.searchTimer) this.searchTimer = setTimeout(() => { this.doSearch() }, 300) }

这里只是给了思路，具体防抖实现要看项目里用的是哪种方式。重点是别在中文输入没结束时就急着发请求。

6.2 多行 TextArea 的“高度不自动变大”

用 TextArea 做备注输入时，默认高度是固定的，输入内容超过可视区域后会在组件内部滚动，而不是自动撑高。这个行为和很多人预期的“聊天气泡输入框会跟着文字变高”不一样。

如果产品需求是高度自适应，需要在onChange里根据内容长度或行数动态调整高度，同时设置最小高度和最大高度，外层再用 Scroll 兜底。这个功能并不复杂，但属于很容易被忽略的细节，一定要在真机上用长文本测一遍。

6.3 系统自动填充建议条导致的布局跳动

在登录注册页面，系统经常会在输入框上方弹出“短信验证码”“保存的密码”等建议条。这些系统级 UI 在某些设备上会盖住输入框，在另一些设备上会把页面内容顶上去，布局表现很不稳定。做登录页时，不要只关掉开发者工具里的模拟键盘就完事，最好把系统自动填充能力打开再测一轮。

如果测试后发现布局被顶得很难看，通常需要给底部容器留足安全边距，并减少最后一个输入框和页面底部的距离。这部分没有一套通用配置能适配所有机型，建议先保证页面可滚动，再根据真机表现调整留白。

6.4 几条收尾经验

输入框的代码量不大，但它是和系统软键盘、输入法、焦点机制耦合最深的组件，看起来简单，细节极多。我自己的使用习惯可以总结成几条，供你参考：

• 所有输入框都采用受控模式，值必须经过onChange回流到状态变量，后续加校验、格式化、埋点都会方便很多。
• onChange只做输入清洗和实时反馈，完整校验放在onBlur和onSubmit。
• 键盘行为和焦点行为一律真机验证，模拟器不能替代。
• 升级 SDK 之后，检查一下输入框相关属性是否有废弃或参数变化，这类变更出现频率不低。

如果你正在从零搭一个登录页或搜索页，我希望这些内容能帮你少翻几次文档、少踩几个坑。先记住最关键的一条就够了：在 HarmonyOS 的 ArkUI 里写输入框，找 TextInput，它就是你记忆中的那个 TextField。