验证码输入框这个组件看起来简单真动手写起来坑不少。我最近在一个 Flutter 项目里需要做一个验证码输入控件本来想着半小时搞定结果前前后后改了三版才达到自己满意的状态。第一版用六个独立的 TextField 拼焦点跳转各种错乱第二版改成单个 TextField 加隐藏输入光标和选中态又不好控制第三版才找到比较优雅的方案。这篇文章就把整个思路演进、核心实现、踩过的坑和最终方案完整分享出来适合有一定 Flutter 基础、正在做表单类交互的开发者参考。1. 为什么验证码输入框值得单独造一个轮子1.1 系统 TextField 直接用的三个硬伤很多人第一反应是直接用TextField加maxLength: 6能跑但体验很差。第一个硬伤是视觉呈现系统输入框是一个连续的文本行而验证码场景用户期望看到的是六个独立的方格每个方格放一个数字这种分格的视觉暗示能显著降低用户的认知负担让用户一眼就知道我要填六位。第二个硬伤是焦点管理。如果用六个独立 TextField用户输入第一位后需要手动把焦点移到下一个删除时又要回退到上一个。这个逻辑听起来简单但实际写起来边界情况极多用户从中间某位开始输入怎么办粘贴六位验证码怎么办快速连续删除怎么办我第一版就是栽在这里测试的时候发现快速输入会丢字符因为焦点切换有延迟。第三个硬伤是输入法兼容性。不同平台的软键盘行为不一致有些输入法会在输入数字时弹出候选词栏遮挡住输入框有些输入法对keyboardType的响应不准确。这些细节不处理用户在实际使用中就会觉得这个输入框怪怪的但又说不上哪里怪。1.2 一个优雅的验证码组件应该满足什么我给自己定了几个标准。视觉上六个等宽方格间距均匀有明确的当前焦点指示输入过的格子有内容态未输入的有占位态。交互上点击任意格子都能聚焦到正确位置输入自动前进删除自动后退支持整段粘贴自动分配。状态上要能区分默认态、聚焦态、错误态、禁用态错误态要有视觉反馈比如边框变红加轻微抖动。还有一个容易被忽略的点光标闪烁。如果用单个隐藏 TextField 承载输入那六个方格里的当前输入位就需要自己画一个闪烁光标。这个光标要和系统光标一样有节奏感不能太快也不能太慢我用的是 500ms 一个周期和系统默认比较接近。这里有个经验不要试图去完全模拟系统 TextField 的所有行为验证码场景的输入是高度受限的只有数字、固定长度把范围收窄反而更容易做到精致。1.3 技术选型单 TextField 隐藏方案 vs 多 TextField 方案我把两种主流方案做了个对比这也是我最终选择单 TextField 方案的原因对比维度多 TextField 方案单 TextField 隐藏方案焦点管理需要手动控制六个焦点节点复杂只有一个焦点天然简单粘贴支持需要拦截粘贴事件手动分配系统自动处理拿到完整字符串光标控制每个格子独立光标难统一自己绘制光标完全可控输入法兼容每个格子都要处理问题翻倍只处理一个风险集中删除逻辑需要判断当前格是否为空再回退监听文本变化统一处理性能六个 TextField 重建开销大一个 TextField开销小单 TextField 方案的核心思路是用一个透明的、几乎不可见的 TextField 来接收所有输入然后在它上面覆盖一层自绘的方格 UI。TextField 的文本变化通过监听器同步到方格上方格只负责展示。这样输入逻辑完全交给系统展示逻辑完全自己控制职责清晰。2. 核心实现从透明输入层到方格展示层2.1 整体结构拆解整个组件的结构可以理解为三层叠加。最底层是一个Stack第一层放六个方格组成的Row第二层放一个透明的TextField覆盖在上面。TextField 的cursorColor设为透明decoration去掉所有边框字体颜色也设为透明这样用户看不到它但点击它的时候能唤起键盘。关键点在于 TextField 的尺寸要覆盖整个方格区域这样用户点击任意方格实际上都是点击到了 TextField。然后通过TextEditingController监听文本变化把文本按字符拆分分别渲染到六个方格中。Stack( children: [ // 展示层六个方格 Row( mainAxisAlignment: MainAxisAlignment.spaceBetween, children: List.generate(6, (index) _buildCell(index)), ), // 输入层透明 TextField Positioned.fill( child: TextField( controller: _controller, focusNode: _focusNode, keyboardType: TextInputType.number, inputFormatters: [ FilteringTextInputFormatter.digitsOnly, LengthLimitingTextInputFormatter(6), ], cursorColor: Colors.transparent, style: const TextStyle(color: Colors.transparent), decoration: const InputDecoration( border: InputBorder.none, counterText: , ), showCursor: false, ), ), ], )这段代码是整个组件的骨架。FilteringTextInputFormatter.digitsOnly保证只能输入数字LengthLimitingTextInputFormatter(6)限制最大长度。showCursor: false关掉系统光标因为我们要自己画。2.2 方格的状态渲染逻辑每个方格需要根据当前状态决定显示什么。我定义了四种状态已填充该位置有字符、当前聚焦光标所在位置、空占位还没输入到的位置、错误态验证失败时。Widget _buildCell(int index) { final text index _controller.text.length ? _controller.text[index] : ; final isFocused _focusNode.hasFocus index _controller.text.length.clamp(0, 5); final isError _hasError; return AnimatedContainer( duration: const Duration(milliseconds: 200), width: 48, height: 56, decoration: BoxDecoration( color: isError ? const Color(0xFFFFF0F0) : const Color(0xFFF7F8FA), borderRadius: BorderRadius.circular(10), border: Border.all( color: isError ? const Color(0xFFFF4D4F) : isFocused ? const Color(0xFF3B82F6) : const Color(0xFFE5E6EB), width: isFocused || isError ? 2 : 1, ), ), child: Center( child: text.isNotEmpty ? Text( text, style: const TextStyle( fontSize: 24, fontWeight: FontWeight.w600, color: Color(0xFF1D2129), ), ) : isFocused ? _BlinkingCursor() : const SizedBox.shrink(), ), ); }这里有个细节值得说index _controller.text.length.clamp(0, 5)用来判断哪个格子是当前位。当输入了 3 个字符时第 4 个格子index 为 3是当前位显示闪烁光标。当输入满 6 个字符时clamp 到 5最后一个格子显示光标表示已满但仍在聚焦。AnimatedContainer让状态切换有过渡动画边框颜色和背景色的变化不会太突兀。这个 200ms 的时长是我试出来的太快感觉不到太慢显得拖沓。2.3 闪烁光标的实现光标闪烁用AnimationController配合FadeTransition实现比用Timer更优雅因为动画控制器能自动处理生命周期页面销毁时不会泄漏。class _BlinkingCursor extends StatefulWidget { const _BlinkingCursor(); override State_BlinkingCursor createState() _BlinkingCursorState(); } class _BlinkingCursorState extends State_BlinkingCursor with SingleTickerProviderStateMixin { late AnimationController _animController; override void initState() { super.initState(); _animController AnimationController( vsync: this, duration: const Duration(milliseconds: 500), )..repeat(reverse: true); } override void dispose() { _animController.dispose(); super.dispose(); } override Widget build(BuildContext context) { return FadeTransition( opacity: Tween(begin: 1.0, end: 0.0).animate( CurvedAnimation(parent: _animController, curve: Curves.easeInOut), ), child: Container( width: 2, height: 24, decoration: BoxDecoration( color: const Color(0xFF3B82F6), borderRadius: BorderRadius.circular(1), ), ), ); } }repeat(reverse: true)让动画来回播放形成闪烁效果。500ms 一个来回和系统光标节奏基本一致。用Curves.easeInOut让透明度变化更柔和不会像开关一样生硬。注意光标组件要独立成 StatefulWidget不要放在主组件的 build 里直接创建 AnimationController否则每次重建都会新建控制器导致内存泄漏和动画异常。3. 那些让我返工的交互细节3.1 点击任意格子聚焦到正确位置用户点击第三个格子时期望光标跳到第三个位置而不是简单地聚焦到末尾。这个需求在单 TextField 方案里需要额外处理因为 TextField 本身不知道用户点的是哪个格子。我的做法是在每个格子上包一层GestureDetector点击时根据 index 设置TextSelectionGestureDetector( onTap: () { final targetOffset index.clamp(0, _controller.text.length); _controller.selection TextSelection.collapsed( offset: targetOffset, ); _focusNode.requestFocus(); }, child: _buildCell(index), )这里index.clamp(0, _controller.text.length)是关键。如果用户点击第 5 个格子但只输入了 2 个字符光标应该落在第 2 位末尾而不是第 5 位因为中间不能有空洞。验证码输入必须是连续的不允许跳位输入。3.2 删除时的回退逻辑删除逻辑我踩了个坑。最初我监听文本变化发现长度减少就认为用户删除了但这样无法区分删除当前位和选中一段删除。后来改成监听TextEditingController的 selection 变化配合文本变化来判断。实际上更简单的做法是不区分统一按文本长度减少处理。因为验证码场景用户几乎不会做区间选择删除都是单字符删除。当文本从 4 位变成 3 位时光标自然落在第 3 位index 为 3方格展示层会自动更新不需要额外逻辑。但有一个边界情况要处理长按删除键连续删除。有些输入法长按删除会快速连续触发如果每次触发都重建整个组件会有性能问题。我的处理是把文本变化监听做成防抖或者直接用ValueListenableBuilder只重建方格层避免整个组件树重建。3.3 粘贴六位验证码的自动分配这是单 TextField 方案最大的优势。用户从短信里复制六位验证码长按输入框粘贴系统会把整个字符串塞进 TextFieldLengthLimitingTextInputFormatter(6)自动截断到六位方格层监听到文本变化后自动渲染六位数字。整个过程不需要写任何额外代码。但有个细节要注意粘贴后光标位置。默认情况下粘贴后光标会在文本末尾也就是第 6 位。如果用户想修改中间某位需要手动点击。这个行为是符合预期的不用特殊处理。我实测下来iOS 和 Android 的粘贴行为基本一致唯一区别是 iOS 粘贴时可能会弹出允许粘贴的系统提示这是系统行为组件层面无法干预。3.4 输入完成后的自动提交六位输满后自动触发验证这个交互能省掉用户点确认按钮的一步。实现方式是在文本监听里判断长度_controller.addListener(() { if (_controller.text.length 6 !_isSubmitting) { _isSubmitting true; _onCompleted(_controller.text); } if (_controller.text.length 6) { _isSubmitting false; } setState(() {}); });_isSubmitting这个标志位很重要。如果不加用户输满六位后如果又删了一位再补上会重复触发提交。加上标志位后只有从不满六位变成满六位时才触发一次。4. 错误态处理与视觉反馈4.1 验证失败时的抖动动画验证码输错时除了边框变红加一个轻微的左右抖动能让用户更直观地感知到出错了。抖动用AnimationController配合Transform.translate实现void _shake() { _shakeController.forward(from: 0); } // build 中 AnimatedBuilder( animation: _shakeController, builder: (context, child) { final offset sin(_shakeController.value * pi * 4) * 8; return Transform.translate( offset: Offset(offset, 0), child: child, ); }, child: _buildInputArea(), )sin(value * pi * 4)产生两个完整周期的正弦波乘以 8 得到最大 8 像素的位移。forward(from: 0)每次从零开始保证连续触发时动画能重新播放。抖动时长我设的是 400ms太快看不清太慢显得拖沓。4.2 错误态的自动清除时机错误态不能一直保留否则用户重新输入时还看到红色边框会很困惑。我的处理是用户重新输入第一个字符时自动清除错误态。_controller.addListener(() { if (_hasError _controller.text.isNotEmpty) { setState(() { _hasError false; }); } // ... 其他逻辑 });这个时机比点击输入框就清除更合理因为用户可能只是点了一下又没输入这时候清除错误态会让用户以为错误已经解决了。4.3 禁用态与加载态提交过程中组件应该进入禁用态防止用户重复修改。禁用态下 TextField 的enabled设为 false方格背景变灰文字颜色变浅。加载态则在组件下方显示一个小的进度指示器或者把方格区域整体降低透明度。TextField( enabled: !widget.disabled !_isSubmitting, // ... )这里有个小细节enabled: false的 TextField 在部分 Android 机型上会丢失焦点导致键盘收起。如果希望提交过程中键盘保持展开就不能用enabled而是用readOnly: true配合拦截输入。我一般用readOnly体验更平滑。5. 组件封装与对外接口设计5.1 应该暴露哪些参数一个可复用的组件对外接口要克制。我最终暴露了这几个参数参数名类型默认值说明lengthint6验证码位数onCompletedValueChangedString必填输满后的回调onChangedValueChangedString?null每次变化的回调disabledboolfalse是否禁用hasErrorboolfalse外部控制的错误态autoFocusboolfalse是否自动聚焦cellWidthdouble48单个格子宽度cellHeightdouble56单个格子高度spacingdouble12格子间距hasError设计成外部传入而不是内部管理是因为错误态通常由验证接口返回组件自己不知道对错。外部改变这个值时组件内部监听并触发抖动动画。override void didUpdateWidget(covariant CodeInputWidget oldWidget) { super.didUpdateWidget(oldWidget); if (widget.hasError !oldWidget.hasError) { _shake(); } }didUpdateWidget里对比新旧值只在从无错误变成有错误时触发抖动避免重复触发。5.2 如何暴露清空和聚焦方法外部有时候需要主动清空输入比如切换验证方式时或者主动聚焦比如页面加载后自动弹键盘。这需要通过GlobalKey暴露 State 的方法class CodeInputWidgetState extends StateCodeInputWidget { void clear() { _controller.clear(); setState(() { _hasError false; }); } void focus() { _focusNode.requestFocus(); } }外部这样使用final _codeKey GlobalKeyCodeInputWidgetState(); // 清空 _codeKey.currentState?.clear(); // 聚焦 _codeKey.currentState?.focus();注意GlobalKey会增加组件树的查找开销不要滥用。如果只是需要清空也可以考虑通过 controller 参数从外部传入TextEditingController让外部直接控制。两种方式各有取舍看项目习惯。5.3 主题适配的处理组件内的颜色我一开始写死了后来发现项目要支持深色模式又返工改成从Theme读取。但验证码组件的颜色和系统主题的对应关系不是一一对应的比如聚焦边框色在浅色模式下是蓝色深色模式下可能需要更亮的蓝色。我的做法是定义一个轻量的配置类允许外部传入颜色同时提供基于Theme的默认值class CodeInputTheme { final Color? backgroundColor; final Color? borderColor; final Color? focusedBorderColor; final Color? errorBorderColor; final Color? textColor; final Color? cursorColor; const CodeInputTheme({ this.backgroundColor, this.borderColor, this.focusedBorderColor, this.errorBorderColor, this.textColor, this.cursorColor, }); }组件内部用widget.theme?.backgroundColor ?? _defaultBackground(context)这样的方式取值既支持自定义又有合理的默认值。这个模式在 Flutter 组件开发里很常见值得掌握。6. 实测中遇到的几个坑6.1 输入法候选栏遮挡问题在部分 Android 机型上数字键盘上方会有一行候选词栏如果验证码组件位置靠下候选栏会遮挡住组件。这个问题在组件层面无法完全解决但可以通过MediaQuery.viewInsetsOf(context).bottom获取键盘高度在键盘弹出时把组件往上推。Padding( padding: EdgeInsets.only( bottom: MediaQuery.viewInsetsOf(context).bottom 0 ? 20 : 0, ), child: CodeInputWidget(...), )更彻底的做法是把组件放在SingleChildScrollView里配合resizeToAvoidBottomInset: true让系统自动处理。但这样会引入滚动对于简单的验证码页面可能过度设计。我的建议是先用 Padding 方案实测不够再上滚动。6.2 快速输入丢字符这个问题我在第一版多 TextField 方案里遇到过快速连续输入时偶尔会丢字符。原因是焦点切换是异步的用户输入速度超过焦点切换速度时字符会落到错误的格子里。单 TextField 方案天然没有这个问题因为所有输入都进同一个 TextField不存在焦点切换。这也是我最终选择单 TextField 方案的重要原因之一。6.3 页面返回后键盘不收起用户输入验证码后按返回键有时候键盘不收起停留在页面上。这是因为FocusNode没有正确释放。解决方法是在dispose里调用_focusNode.unfocus()override void dispose() { _focusNode.unfocus(); _focusNode.dispose(); _controller.dispose(); _shakeController.dispose(); super.dispose(); }顺序很重要先unfocus再dispose反过来会报错。这个坑我踩过一次报错信息不直观排查了好一会儿。6.4 自动填充的兼容性iOS 支持短信验证码自动填充会在键盘上方显示验证码建议。要启用这个功能需要设置autofillHintsTextField( autofillHints: const [AutofillHints.oneTimeCode], // ... )设置后iOS 收到短信时会自动在键盘上方显示验证码用户点击即可填充。Android 的支持情况取决于具体机型和系统版本不是所有设备都支持。这个功能对用户体验提升很大建议都加上。实测发现autofillHints在部分 Android 机型上会导致键盘类型异常如果发现数字键盘变成了普通键盘可以尝试去掉这个配置或者用Platform.isIOS做条件判断。7. 性能优化与边界情况7.1 避免不必要的重建文本监听里调用setState会导致整个组件重建包括六个方格。虽然六个方格重建开销不大但在快速输入时还是能感觉到轻微卡顿。优化方式是用ValueListenableBuilder只重建方格层ValueListenableBuilderTextEditingValue( valueListenable: _controller, builder: (context, value, child) { return Row( children: List.generate( widget.length, (index) _buildCell(index, value.text), ), ); }, )这样 TextField 本身不会重建只有方格层跟着文本变化重建。实测下来快速输入时的流畅度有明显提升。7.2 长按删除的连续触发长按删除键时系统会以一定频率连续触发删除。如果每次触发都走完整的setState流程会有性能压力。我的处理是在监听里加一个简单的节流DateTime? _lastDeleteTime; _controller.addListener(() { final now DateTime.now(); if (_controller.text.length _lastLength) { if (_lastDeleteTime ! null now.difference(_lastDeleteTime!).inMilliseconds 50) { return; } _lastDeleteTime now; } _lastLength _controller.text.length; setState(() {}); });50ms 的节流窗口既能保证删除响应及时又能避免过于频繁的重建。这个值是我试出来的太小起不到节流效果太大用户会感觉删除有延迟。7.3 位数可配置时的布局适配组件支持配置位数后格子宽度和间距需要动态计算。如果固定格子宽度位数多的时候会超出屏幕。我的做法是用LayoutBuilder获取可用宽度然后计算格子宽度LayoutBuilder( builder: (context, constraints) { final totalSpacing widget.spacing * (widget.length - 1); final cellWidth (constraints.maxWidth - totalSpacing) / widget.length; return Row( children: List.generate( widget.length, (index) SizedBox(width: cellWidth, child: _buildCell(index)), ), ); }, )这样无论 4 位还是 6 位都能自适应屏幕宽度。但要注意格子宽度不能太小否则数字显示不下。我加了个最小宽度限制低于这个值就改用固定宽度加横向滚动。7.4 无障碍支持验证码组件对屏幕阅读器用户不太友好因为视觉上的六个格子对读屏软件来说是一团乱麻。我的处理是给整个组件加一个Semantics包裹提供统一的语义描述Semantics( label: 验证码输入框已输入${_controller.text.length}位共${widget.length}位, textField: true, child: Stack(...), )这样读屏软件会把整个组件当作一个输入框来朗读而不是六个独立的元素。虽然不如原生输入框完美但比不做处理好很多。8. 完整代码结构与使用示例8.1 文件组织我把组件拆成了三个文件职责清晰code_input_widget.dart主组件包含输入层和方格层blinking_cursor.dart闪烁光标组件code_input_theme.dart主题配置类这样拆分的好处是光标组件可以独立测试和复用主题配置也可以被其他组件引用。如果项目里组件不多也可以合并成一个文件但超过 300 行后建议拆分。8.2 基本使用CodeInputWidget( length: 6, autoFocus: true, hasError: _hasError, onCompleted: (code) async { final success await _verifyCode(code); if (!success) { setState(() { _hasError true; }); } }, )onCompleted是异步的验证失败后通过setState更新hasError组件监听到变化后自动触发抖动动画。整个流程很顺畅。8.3 自定义样式CodeInputWidget( length: 4, theme: const CodeInputTheme( backgroundColor: Color(0xFFF0F5FF), focusedBorderColor: Color(0xFF2F54EB), cursorColor: Color(0xFF2F54EB), ), onCompleted: (code) {}, )通过theme参数可以完全自定义配色不传则使用基于系统主题的默认值。这个设计让组件既能开箱即用又能深度定制。8.4 在表单中的集成如果验证码组件是表单的一部分需要和Form配合使用。我的做法是给组件包一层FormFieldFormFieldString( validator: (value) { if (_controller.text.length 6) { return 请输入完整的验证码; } return null; }, builder: (state) { return Column( crossAxisAlignment: CrossAxisAlignment.start, children: [ CodeInputWidget( onChanged: (value) state.didChange(value), onCompleted: (code) {}, ), if (state.hasError) Padding( padding: const EdgeInsets.only(top: 8), child: Text( state.errorText ?? , style: const TextStyle( color: Color(0xFFFF4D4F), fontSize: 12, ), ), ), ], ); }, )这样验证码组件就能融入表单的校验体系和其他字段一起统一校验、统一提交。9. 写在最后的一些个人体会这个组件我从第一版到最终版大概花了两天时间其中大部分时间不是在写代码而是在测试各种边界情况。验证码输入框看起来是个小东西但它涉及焦点管理、输入法兼容、动画、无障碍、性能优化等多个方面是个很好的 Flutter 综合练习。如果让我给正在做类似组件的朋友一个建议那就是先想清楚输入层和展示层怎么分离。我第一版失败的根本原因就是把输入和展示混在一起了六个 TextField 既负责输入又负责展示导致逻辑纠缠不清。单 TextField 方案的精髓就在于把这两层彻底分开输入交给系统展示自己控制各司其职。另外不要低估测试的工作量。我在真机上测试了 iOS 和 Android 各两台设备发现了至少三个模拟器上没出现的问题比如候选栏遮挡、自动填充兼容性、键盘收起时机。这些细节不测真机是发现不了的但恰恰是这些细节决定了组件的最终品质。最后分享一个小技巧如果项目里多个页面都要用验证码输入建议把组件发布到项目的内部组件库而不是每个页面复制一份。我见过太多项目里同一个组件有七八个版本改一个 bug 要改七八个地方。组件化的收益在第二个使用场景出现时就开始体现了。