1. 项目概述1.1 为什么需要「单格单字符」输入框做鸿蒙应用开发时手机号、验证码这类输入场景是最常见的需求之一。但很多新手甚至有一定经验的开发者第一反应都是直接用TextInput配合maxLength限制长度再套一层样式就完事。这种方案在功能上没毛病可在实际用户体验上和主流App里那种“一格一字带下划线”的输入框差距很大。原因很简单手机号输入时用户希望知道自己输到第几位了验证码输入时用户期望是“一格一字”的视觉反馈每个数字独立占位底部带下划线输完自动跳到下一格。原生TextInput做不到这种体验因为它是“一段连续文本”而不是“N个独立字符格子”。所以需要我们自己用ArkUI的组件组合去实现。这个项目就是我在鸿蒙应用里实现该交互的完整记录。最终效果是屏幕上横向排列N个格子每个格子底部有一条下划线用户输入时字符逐个填充到格子中并且光标自动“跳格”支持删除键回退。整个实现不依赖第三方库全部用ArkUI声明式语法完成核心代码量控制在200行以内。1.2 方案适用范围如果你正在做以下类型的页面这个方案可以直接复用手机号/邮箱/身份证等固定位数信息输入短信/语音验证码输入4位、6位最常用密码“单格圆点”输入稍改渲染逻辑即可任何需要“逐字符反馈”的输入场景适合的读者刚接触鸿蒙ArkUI的初级开发者、想优化表单输入体验的中级开发者、以及需要在项目中快速落地该组件的工程师。1.3 关键技术点一览在动手写代码前先明确这个方案需要解决的几个核心问题布局问题如何把N个格子横向等分排列且自适应不同屏幕宽度。输入焦点问题如何保证“点击任意格子”都能唤起输入法且输入框始终处于激活状态。字符映射问题如何把输入框里的连续字符串拆分成单个字符并填充到对应格子中。交互细节删除时如何回退、超过位数时如何限制、格式校验如何处理。下面逐个拆解。2. 整体设计与思路拆解2.1 核心设计思想隐藏输入框 渲染格子这个功能最巧妙的点在于用户看到的格子不是真正的输入框真正的输入框被隐藏了。我用了一个几乎不可见的TextInput覆盖在整个格子区域上方用户点击时实际点中的是这个透明的TextInput输入法正常弹出字符正常接收。与此同时通过onChange回调实时读取输入框内容把每个字符拆出来填充到下方渲染的N个格子中。为什么不用N个独立的TextInput说实话我也试过那是第一个踩坑版本每个格子单独一个输入框onFocus事件里手动把焦点切到下一个。但实测下来问题很多比如焦点切换时机难以控制字符还没输入就被切走体验很差。软键盘弹出时多个输入框的focus状态难以管理。删除键在跨输入框回退时行为不一致有的输入法直接不触发事件。所以后来参考了一些成熟方案改成“单个隐藏输入框 状态驱动渲染”的思路所有问题迎刃而解。这也是ArkUI声明式开发的核心优势UI是状态的下游产物只要状态正确UI自动正确。2.2 为什么选择 Column Row Divider 组合具体到格子渲染ArkUI里能用来做“下划线”的组件不少比如Divider、Border甚至Canvas。我最终选择的是每个格子用Column包一个Text底部用Divider绘制下划线。选择这个组合的理由Column天然支持纵向排列上面显示字符下面显示线结构清晰。Divider是独立的线条组件可以单独控制颜色、粗细、间距选中态和默认态切换时只需要改strokeWidth和color不用动外层布局。如果用Border虽然也能画底部线但边框属于组件自身想单独改某一边的粗细、颜色还得自己写Border的EdgeWidths和EdgeColors代码量反而更多。从状态管理的角度看每个格子只需要两个状态char该格子的字符和isActive当前是否处于输入焦点位置。这两个状态直接映射到UI字符为空时格子显示占位符比如一个浅色短横字符非空时显示数字或密码圆点isActive为真时下划线高亮加粗否则保持灰色细线。2.3 状态数据结构设计既然是ArkUI声明式开发第一步就是定义状态。我定义的数据结构如下State inputValue: string // 隐藏输入框的真实值 State codeArray: string[] [] // 每个格子的字符初始为空字符串数组 State activeIndex: number 0 // 当前高亮的格子下标同时也是“光标位置”inputValue是隐藏输入框的绑定值一切输入都经过它codeArray长度等于格子总数初始全部是空字符串activeIndex表示当前输入焦点对应的格子位置控制下划线的高亮显示。他们三者之间的关系是这样的用户输入字符 →inputValue变化 →onChange触发 → 更新codeArray→ 格子渲染变化用户删除字符 →inputValue变化 →onChange触发 →codeArray同步减少一个字符 → 格子回退这里有个非常有用的细节activeIndex不需要单独维护“当前是第几格”因为它永远等于codeArray中最后一个非空字符的下标加1。换句话说只要统计codeArray里非空元素的数量就知道光标停在哪。我后续的代码就是基于这个逻辑。3. 核心细节解析与实操要点3.1 两套视觉状态默认态与激活态每一个格子都有两套视觉状态。默认态是灰色下划线、字符灰色激活态是主题色下划线加粗字符变黑。这种视觉反馈让用户知道自己正在输入哪个位置对验证码这类短输入尤其重要。实现时我给Column绑定了一个状态判断Button() // 伪代码思路实际不是按钮 Column({ space: 4 }) { Text(this.getCharText(index)) .fontSize(28) .fontWeight(FontWeight.Medium) .fontColor(this.activeIndex index ? #1A1A1A : #999999) Divider() .strokeWidth(this.activeIndex index ? 3 : 1.5) .color(this.activeIndex index ? #007AFF : #D0D0D0) }这里有个细节fontColor和strokeWidth的变化如果太突兀会显得很生硬但验证码输入框本身就是“瞬间切换”的交互节奏不需要动画。如果你想要平滑过渡可以给这两个属性加.animation()我在某些项目里试过0.15秒的缓动效果最好时间长了反而拖沓。3.2 隐藏输入框的三个关键设置隐藏输入框是整个方案的灵魂但隐藏不等于“消失”。它必须满足三个条件尺寸要能覆盖整个格子区域这样点击任意格子都能聚焦到它。透明度要低到看不见但不能设置visibility: Hidden否则组件不参与布局也无法聚焦。文本颜色要设成透明否则输入内容会露馅。我的实现如下TextInput({ text: this.inputValue, placeholder: }) .type(InputType.NUMBER) // 数字键盘 .borderRadius(0) .backgroundColor(Color.Transparent) .caretColor(Color.Transparent) // 光标也隐藏 .fontColor(Color.Transparent) // 文本透明 .opacity(0.01) // 整个组件接近不可见 .focusable(true) .defaultFocus(true) // 页面加载后自动聚焦直接弹出键盘 .width(100%) .height(100%) .position({ x: 0, y: 0 }) // 绝对定位覆盖格子区域实践经验提醒几点.opacity(0.01)比.opacity(0)稳妥。某些鸿蒙版本上opacity为0的组件会被判定为不可交互区域点击无法聚焦。保留0.01的可见度可以避免这个坑。.caretColor(Color.Transparent)一定要设置否则你能看到一个光标在闪非常奇怪。defaultFocus(true)要慎用。如果页面还有别的输入需求一进来就弹键盘可能不是用户预期但对验证码页来说弹键盘恰恰是减少用户操作的关键一步。别忘了给TextInput设置.onSubmit事件。用户输完最后一位后自动触发“下一步”或“校验”逻辑体验闭环。3.3 字符填充规则长度限制与非法字符过滤输入框虽然是InputType.NUMBER但为了防止极端情况比如某些输入法允许粘贴字母必须在onChange里做二次过滤。.onChange((value: string) { // 1. 只保留数字字符 const filtered value.replace(/[^0-9]/g, ); // 2. 截取前 codeLen 位 const limited filtered.substring(0, this.codeLen); // 3. 同步回填到隐藏输入框防止非法字符短暂显示 this.inputValue limited; // 4. 更新格子数组 this.codeArray []; for (let i 0; i this.codeLen; i) { this.codeArray.push(limited.charAt(i) || ); } // 5. 更新激活位置光标停在最后一个非空字符之后 this.activeIndex limited.length; if (this.codeLen 0 limited.length this.codeLen) { // 输完了可以自动触发下一步 } })这个处理逻辑把所有状态更新集中到了一处简洁且可控。这里有一个容易踩的坑不能直接用this.inputValue.length来计算激活下标。因为长度和内容不等于有效位数一旦用户粘贴了非法字符length会大于有效数字个数导致activeIndex越界。我上面用了limited.length它一定是合法且截断后的长度不会出问题。还有一个细节光标位置与activeIndex不完全等价。如果用户把光标移到中间插入字符这种实现方式是“尾部追加”逻辑不支持中间插入。对于手机号/验证码场景这完全没问题行为反而更符合预期用户点击第3格实际焦点还是落在隐藏输入框上新增字符总是append到末尾。过度设计成“支持中间插入”反而会导致格子错乱。4. 实操过程与核心环节实现4.1 第一步定义组件参数与属性我封装成了一个自定义组件CodeInputView对外暴露两个参数格子数量和完整输入回调。Component export struct CodeInputView { // 格子数量默认为6 Prop codeLength: number 6; // 输入完成回调 onCompleted: (code: string) void () {}; State inputValue: string ; State codeArray: string[] []; State activeIndex: number 0; aboutToAppear(): void { this.codeArray new Array(this.codeLength).fill(); } }这里要注意Prop和State的配合。codeLength由父组件传入只在初始化时生效后续如果动态改变格子数量需要额外处理比如用Watch监听变化重置codeArray但大多数场景下格子数量是固定的Prop足够。4.2 第二步完整页面结构与网格布局页面的主体结构分三层最外层是一个Stack容器用于叠加隐藏输入框和格子层。第二层是Row横向排列N个格子。第三层是每个格子的Column字符 Text 下划线 Divider。build() { Stack({ alignContent: Alignment.Center }) { // 格子渲染层 Row({ space: 12 }) { ForEach(this.codeArray, (char: string, index: number) { Column({ space: 6 }) { Text(char ? char : ) .fontSize(30) .fontWeight(FontWeight.Bold) .fontColor(this.activeIndex index ? #1A1A1A : #BBBBBB) .height(40) Divider() .strokeWidth(this.activeIndex index ? 3 : 1.5) .color(this.activeIndex index ? #007AFF : #D8D8D8) } .width(this.getCellWidth()) .onClick(() { // 点击格子时确保隐藏输入框获得焦点 this.$inputController.setText(this.inputValue); }) }, (item: string, index: number) ${index}-${item}) } .width(100%) .padding({ left: 20, right: 20 }) // 隐藏输入层 TextInput({ text: this.inputValue, controller: this.$inputController }) // ... 上述透明设置 .position({ x: 0, y: 0 }) .width(100%) .height(56) } .width(100%) .height(70) }getCellWidth()这个方法值得说一下。如果格子数量是4/6等偶数且屏幕宽度固定可以简单做除法但更好的做法是根据屏幕宽度动态计算减去Row内边距和格子间距的总和private getCellWidth(): string { const screenWidth this.getScreenWidth(); // 通过 px2vp 或 window 获取 const spacingTotal (this.codeLength - 1) * 12; const paddingTotal 40; return ${(screenWidth - spacingTotal - paddingTotal) / this.codeLength}vp; }实操中我推荐把间距固定为12vp屏幕宽度用display.getDefaultDisplaySync().width获取。鸿蒙的vp单位在不同设备上能自适应但px不行务必用vp。4.3 第三步处理删除回退与光标移动用户按删除键时系统会先删除inputValue的最后一个字符然后触发onChange我们上面的事件处理逻辑已经涵盖了回退limited.length变小codeArray最后一项变成空activeIndex自动回退。但onChange有一个坑部分输入法在连续快速删除时不会每个动作都触发onChange而是间隔触发导致UI更新不够及时。我的解决办法是额外监听onKeyEvent中的删除键事件主动同步一次状态.onKeyEvent((event: KeyEvent) { if (event.type KeyType.Down event.keyCode 2055) { // 删除键 this.$inputController.setText(this.inputValue.substring(0, this.inputValue.length - 1)); } })重点说明2055是通用删除键的keyCode不同设备/输入法可能会有差异所以这个只能作为兜底方案。主力还得是onChange它在绝大多数情况下都是可靠且及时的。4.4 第四步完整输入完成判断与自动提交当codeArray中填满所有格子时通常要自动触发后续动作。我在onChange里做了判断输满后直接调用onCompletedif (limited.length this.codeLength) { this.onCompleted(limited); }但如果用户删除后再重新输入还是会走到这个判断。如果需要“只触发一次”可以在组件里加一个State submitted: boolean false首次提交后置为真重置时再恢复。还有一个容易被忽略的细节输入完成时隐藏键盘。用inputController.stopEditing()即可。否则用户输满后键盘还占着半屏后面弹出的确认弹窗会被顶上去体验很差。if (limited.length this.codeLength) { this.$inputController.stopEditing(); this.onCompleted(limited); }4.5 第五步整段代码合并与页面调用把上述代码整理成一个完整的自定义组件后在页面中调用CodeInputView({ codeLength: 6, onCompleted: (code: string) { // 发起验证码校验请求 } })到这里核心功能已经全部实现格子渲染、输入填充、删除回退、自动提交。我在多个项目里跑过这套逻辑稳定性和流畅度都没问题。5. 常见问题与排查技巧实录5.1 点击格子无法唤起键盘现象页面加载后可以自动弹键盘但手动点击某个格子没反应。排查步骤确认隐藏TextInput是否覆盖在格子区域上方。用opacity(1)临时显示它看它的实际位置和大小对不对。确认position或者Stack的alignContent设置是否正确通常是Stack里子组件的层级问题。检查TextInput是否被if条件错误地移除了。解决方案把TextInput的宽高设成与格子区域相同或者直接width(100%).height(56)配合Stack的默认对齐方式基本能解决。另外点击格子时用this.$inputController.setText(this.inputValue)强制刷新输入框内容也能唤起输入法。5.2 输入法每次都显示字母键盘现象.type(InputType.NUMBER)也设置了但弹出的还是全键盘。原因分析鸿蒙部分版本对InputType.NUMBER的支持不彻底或者输入法App自身设定优先。这种通常出现在第三方输入法上系统自带输入法一般没问题。解决方案再加一行.enableKeyboardOnFocus(true)如果还不行就换用InputType.PHONE_NUMBER它在大多数输入法下会稳定弹出数字键盘。实测中PHONE_NUMBER比NUMBER兼容性更好因为后者有时被输入法当作“小数输入”处理会出现小数点键位。5.3 高亮下划线显示错误现象输入到第3位但第2格的下划线高亮了。排查思路这是activeIndex计算错误。回顾逻辑activeIndex limited.length如果limited被截断或过滤后长度不对光标位置就会偏。在代码里打印一下limited.length和codeArray两相对比就知道哪里出问题了。常见原因codeArray初始化长度与实际codeLength不一致比如父组件传入codeLength6但子组件aboutToAppear里用new Array(4)初始化导致下标错位。解决方案强制在aboutToAppear里用this.codeLength初始化codeArray并在onChange里也一样用this.codeLength截断两处保持一致。5.4 单格单字符模式下粘贴不生效现象用户通过输入法粘贴一串验证码结果只有第一位显示了。原因分析部分输入法的粘贴行为会逐字符触发onChange而且每次触发时传入的是“增量”而非“全量”我们基于全量字符串的覆盖逻辑就会被后面的增量覆盖掉。解决方案在onChange里不要直接用传入的value而是读取this.inputController.getTextContent()拿输入框的真实全量内容或者把传入值和当前状态做合并const finalValue value.length this.inputValue.length ? value : this.inputValue;这个方法不是100%可靠但能解决多数场景。更稳的做法是在onPaste事件里拦截并手动赋值。我在一个金融类App项目里遇到过粘贴不生效的问题最后就是用onPaste拦截解析剪贴板内容后直接this.inputValue parsedCode效果最好。5.5 页面回退后输入框状态残留现象从验证码页退到上一个页面再回来输入框还是上次的输入内容。原因分析页面没有被销毁State数据还保留着。解决方案在页面onPageHide或aboutToDisappear里清空状态。如果是用Navigation管理的多页面可以在onHidden回调里执行this.inputValue ; this.codeArray new Array(this.codeLength).fill(); this.activeIndex 0;这一步看着简单但很多测试同学会专门去验证“退出重进”后的状态问题建议从一开始就加上。6. 性能优化与扩展方向6.1 减少不必要的组件重绘ArkUI的ForEach在列表渲染时如果item的key不唯一或频繁变化会导致整个ForEach重建。我在生成key时用了${index}-${item}这样即使字符变化只要下标不变key就稳定组件不会重建只会更新Text内容。这一点在格子数量少时看不出差别但如果未来做成“动态长度”输入比如短信验证码可能是6位也可能是8位或者格子数量很多时就会明显影响流畅度。实测在低端设备上不写key和写key的渲染耗时差距能有3倍。6.2 密码模式扩展把Text的内容从纯数字改成圆点如●只需要一个三元判断Text(char ? ● : )并且把fontSize调小一点因为圆点视觉上比数字大。密码输入时通常不想看到真实的字符这个扩展基本零成本。6.3 支持倒计时与自动校验联动验证码输入框通常伴随“获取验证码”按钮倒计时。组件可以对外暴露一个方法供父组件调用重置public resetCodeInput(): void { this.inputValue ; this.codeArray new Array(this.codeLength).fill(); this.activeIndex 0; }配合State的响应式机制父组件修改codeLength时子组件也能通过Watch自动重置Watch(onCodeLengthChange) Prop codeLength: number 6; onCodeLengthChange() { this.codeArray new Array(this.codeLength).fill(); this.inputValue ; this.activeIndex 0; }6.4 深色模式适配目前色值是写死的浅色主题色。鸿蒙的深色模式适配很简单用Resource颜色替代硬编码色值在resources/base/element/color.json和resources/dark/element/color.json里分别定义同一名称的颜色在代码里引用$r(app.color.input_line_default)即可。下划线的默认色和高亮色、字符颜色各定义一对适配工作量很小。7. 实操心得与踩坑总结整个组件从第一版到现在踩过最大的坑有两个值得单独拿出来说。第一个是输入法“增量回调”问题。第一版我天真地以为onChange每次都会给我完整的字符串直到某台测试机上反复出现字符错位才发现部分输入法粘贴时是分段回调的。后来改成以输入框控制器读到的真实内容为准同时在过滤正则上做了兜底才算彻底稳定。第二个是透明输入框的opacity设置。之前踩过一次opacity(0)后组件完全无法交互的坑查了半天文档才定位到是鸿蒙对“完全透明组件”的点击穿透处理。所以现在用0.01这个数值既满足视觉隐藏又保留交互能力。要说这套方案的取舍我认为它把“输入体验”和“视觉表现”做了很好的解耦。真正的输入逻辑只有一个隐藏输入框承载不用管焦点分发和跨组件事件天然没有竞态问题而视觉部分完全交给状态驱动改样式时只需动Text和Divider不用碰输入逻辑。如果你是在做一个对输入体验有要求的鸿蒙应用或者想给自己的组件库加一个验证码输入组件这套方案可以直接照搬。后续还可以往振动反馈、音频提示、错误状态抖动这些方向扩展本质上都是给同一个状态模型加效果扩展性很好。
