1. 验证码组件到底难在哪验证码输入框这个控件看起来简单到不值一提——不就是几个格子用户挨个填数字嘛。但真正在项目里手写过一遍的人都知道这玩意儿细节多到令人发指。我前前后后在三个 App 里实现过验证码输入组件每次都能踩出新坑光标位置乱跳、粘贴一整串验证码只进去一位、删除时焦点不回溯、键盘弹起把输入框顶飞、暗黑模式下边框颜色对不上……这些问题单独拎出来都不算大但凑在一起就足以让一个看似优雅的界面变得处处别扭。这篇文章要聊的就是怎么从零撸一个真正拿得出手的 Flutter 验证码 Widget。所谓“优雅”我的定义很具体代码结构清晰、交互逻辑自洽、视觉表现统一、边界情况全覆盖。它得能处理粘贴、能自动聚焦、能适配不同位数、能在各种屏幕和主题下正常显示还得让调用方用起来足够简单——最好一行代码就能塞进页面里。适合谁来读如果你已经写过一些 Flutter 页面对TextField、FocusNode、TextEditingController这些基础控件不陌生但每次做验证码都要临时拼凑、复制粘贴一堆散装代码那这篇内容就是写给你的。我会把设计思路、核心实现、踩坑记录全部摊开讲最后给出一个可以直接拿去用的完整方案。全程不依赖任何第三方验证码库纯 Flutter 原生能力实现这样你对每一行代码都有掌控感。2. 整体设计思路与方案选型2.1 为什么不用现成的第三方库Flutter 生态里确实有一些验证码输入相关的包但我在实际项目里很少直接用。原因有三第一这类包往往为了通用性做了大量抽象代码量不小一旦出现样式或交互不符合设计稿的情况改起来比从头写还费劲第二验证码组件的需求差异很大——有的要四位纯数字有的要六位带字母有的要分隔线样式有的要方块样式第三方库很难全部覆盖第三也是最关键的验证码组件本身逻辑并不复杂核心就是“多个输入框 焦点管理 文本同步”自己写一遍反而更可控。当然如果你的项目对开发速度要求极高且设计稿刚好和某个库的默认样式一致用现成的也没问题。但如果你想真正理解这个组件背后的运作机制或者需要深度定制自己撸是更好的选择。2.2 两种主流实现路线的取舍实现验证码输入业界主要有两条路线路线一多个独立 TextField 并排。每个格子是一个独立的TextField用户输入一位后自动跳到下一个删除时自动退回上一个。这种方案视觉上最直观每个格子的状态聚焦、已填、为空可以独立控制样式灵活度最高。但缺点也很明显焦点管理复杂粘贴处理麻烦键盘上的“完成”按钮行为不好统一。路线二单个隐藏 TextField 自定义绘制。放一个透明的、几乎不可见的TextField来接收所有输入然后用Stack在上面叠一层自定义的格子视图根据TextEditingController的内容来渲染每个格子的显示状态。这种方案的好处是输入逻辑完全交给一个TextField处理粘贴、删除、光标移动全部天然支持焦点管理也简单得多。缺点是需要自己处理“视觉上的光标”和“当前聚焦格子”的同步。我最终选择的是路线二。理由很直接路线一的那些坑尤其是粘贴和删除在路线二里几乎不存在因为所有文本操作都发生在同一个TextField上Flutter 原生的文本处理逻辑会帮你搞定一切。你只需要专注于“怎么把文本内容映射成好看的格子”这一件事。2.3 核心架构拆解整个组件的架构可以分成三层输入层一个透明的TextField负责接收键盘输入、处理粘贴、管理TextEditingController和FocusNode。逻辑层监听TextEditingController的变化处理长度限制、自动提交、焦点状态同步等逻辑。展示层根据当前文本内容和焦点状态渲染出一排格子每个格子显示对应的字符或占位符并高亮当前聚焦的格子。这三层之间通过ValueNotifier和ListenableBuilder进行通信避免不必要的setState重建。下面我会逐层展开讲。3. 核心细节解析与实操要点3.1 透明输入框的正确打开方式透明输入框是整个组件的基石它的配置直接决定了后续交互的顺畅程度。很多人第一次写的时候会犯一个错误把TextField的opacity设为 0 或者用Visibility隐藏起来。这样做的问题是隐藏后的TextField无法获得焦点键盘根本弹不出来。正确的做法是让TextField可见但“看不见”——具体来说把它放在Stack的最底层设置cursorColor: Colors.transparent、decoration: InputDecoration.collapsed(hintText: )然后用一个SizedBox把它撑到和格子区域一样大。这样它既能接收点击和焦点又不会在视觉上干扰格子。还有一个关键配置是keyboardType。验证码通常是数字所以设成TextInputType.number是合理的。但如果你的验证码包含字母就要用TextInputType.text。另外inputFormatters里加上FilteringTextInputFormatter.digitsOnly可以过滤掉非数字输入避免用户粘贴进来一堆乱七八糟的字符。TextField( controller: _controller, focusNode: _focusNode, keyboardType: TextInputType.number, inputFormatters: [ FilteringTextInputFormatter.digitsOnly, LengthLimitingTextInputFormatter(widget.length), ], cursorColor: Colors.transparent, showCursor: false, decoration: const InputDecoration.collapsed(hintText: ), style: const TextStyle(color: Colors.transparent, fontSize: 1), onChanged: _onTextChanged, )注意style里把文字颜色也设成透明、字号设成 1这样即使有文字渲染出来也几乎不可见。showCursor: false关掉原生光标因为我们会自己画一个“聚焦格子”的高亮效果来替代。3.2 焦点管理与自动跳转逻辑焦点管理是验证码组件最容易出问题的地方。在路线二里因为只有一个TextField所以焦点管理其实简化了很多——你只需要关心“整个组件是否聚焦”这一个状态。但视觉上用户期望看到的是“当前正在输入第几个格子”所以我们需要根据文本长度来计算出当前聚焦的格子索引。逻辑很简单当前聚焦格子索引 当前文本长度但不能超过总长度减一。比如四位验证码用户已经输入了两位那当前聚焦的就是第三个格子索引 2。如果已经输满了就聚焦最后一个格子。int get _currentFocusIndex { final textLength _controller.text.length; if (textLength widget.length) return widget.length - 1; return textLength; }当用户点击格子区域时我们需要把焦点请求转发给底层的TextField。这可以通过GestureDetector包裹整个格子区域在onTap里调用_focusNode.requestFocus()来实现。这样无论用户点哪个格子焦点都会落到隐藏的TextField上光标自然定位到文本末尾。注意不要在onTap里手动去设置TextSelection的位置因为TextField在获得焦点时会自动把光标放到文本末尾手动干预反而容易出问题。3.3 文本变化监听与自动提交TextEditingController的addListener是驱动整个组件更新的核心。每次文本变化时我们需要做三件事第一触发界面重建更新格子的显示内容第二检查是否已经输满如果输满了就触发onCompleted回调第三如果配置了自动提交可以在输满后自动收起键盘。void _onTextChanged(String value) { _notifier.value value; if (value.length widget.length) { _focusNode.unfocus(); widget.onCompleted?.call(value); } }这里用了一个ValueNotifierString来驱动界面更新而不是直接setState。这样做的好处是更新范围更精确——只有依赖这个notifier的ListenableBuilder会重建隐藏的TextField本身不会因为setState而重新构建避免了潜在的性能问题和焦点丢失。实操心得如果你在setState里重建了整个TextField有时候会导致焦点丢失或者键盘收起。用ValueNotifierListenableBuilder可以完美避开这个问题。3.4 格子视图的渲染策略格子视图的渲染需要处理三种状态已填充、当前聚焦、未聚焦且为空。这三种状态对应不同的边框颜色、背景色和文字样式。我通常会把格子抽成一个独立的_CodeCell组件接收char字符、isFocused是否聚焦、isFilled是否已填三个参数。class _CodeCell extends StatelessWidget { final String char; final bool isFocused; final bool isFilled; const _CodeCell({ required this.char, required this.isFocused, required this.isFilled, }); override Widget build(BuildContext context) { final theme Theme.of(context); final borderColor isFocused ? theme.colorScheme.primary : theme.dividerColor; return AnimatedContainer( duration: const Duration(milliseconds: 150), width: 48, height: 56, decoration: BoxDecoration( color: isFilled ? theme.colorScheme.primaryContainer.withOpacity(0.3) : Colors.transparent, border: Border.all( color: borderColor, width: isFocused ? 2 : 1, ), borderRadius: BorderRadius.circular(8), ), alignment: Alignment.center, child: Text( char, style: theme.textTheme.headlineSmall?.copyWith( fontWeight: FontWeight.w600, ), ), ); } }这里用了AnimatedContainer来做边框和背景色的过渡动画聚焦切换时会有 150 毫秒的平滑过渡视觉上比硬切换舒服很多。格子之间的间距用Row的spacing属性或者SizedBox来控制一般 8 到 12 像素比较合适。注意格子的宽高比要协调。我一般用 48x56 或者 44x52宽度略小于高度看起来更修长。如果设计稿有明确要求按设计稿来就行。4. 完整实操过程与核心环节实现4.1 组件参数设计与对外接口一个好的组件对外接口应该简洁明了。我设计的参数列表如下参数名类型必填说明lengthint是验证码位数默认 4onCompletedValueChangedString否输满后的回调onChangedValueChangedString否每次文本变化的回调autoFocusbool否是否自动聚焦默认 falseenabledbool否是否可输入默认 truecellWidthdouble否格子宽度默认 48cellHeightdouble否格子高度默认 56spacingdouble否格子间距默认 12这些参数覆盖了绝大多数使用场景。如果你需要更细粒度的样式控制可以再加一个cellBuilder回调让调用方自己决定每个格子长什么样。不过大多数情况下默认样式已经够用了。4.2 完整代码实现下面是完整的组件代码我把它放在一个文件里方便你直接复制使用import package:flutter/material.dart; import package:flutter/services.dart; class VerificationCodeInput extends StatefulWidget { final int length; final ValueChangedString? onCompleted; final ValueChangedString? onChanged; final bool autoFocus; final bool enabled; final double cellWidth; final double cellHeight; final double spacing; const VerificationCodeInput({ super.key, this.length 4, this.onCompleted, this.onChanged, this.autoFocus false, this.enabled true, this.cellWidth 48, this.cellHeight 56, this.spacing 12, }); override StateVerificationCodeInput createState() _VerificationCodeInputState(); } class _VerificationCodeInputState extends StateVerificationCodeInput { late final TextEditingController _controller; late final FocusNode _focusNode; final ValueNotifierString _notifier ValueNotifier(); override void initState() { super.initState(); _controller TextEditingController(); _focusNode FocusNode(); _controller.addListener(_onTextChanged); if (widget.autoFocus) { WidgetsBinding.instance.addPostFrameCallback((_) { _focusNode.requestFocus(); }); } } override void dispose() { _controller.removeListener(_onTextChanged); _controller.dispose(); _focusNode.dispose(); _notifier.dispose(); super.dispose(); } void _onTextChanged() { final text _controller.text; _notifier.value text; widget.onChanged?.call(text); if (text.length widget.length) { _focusNode.unfocus(); widget.onCompleted?.call(text); } } int get _currentFocusIndex { final textLength _controller.text.length; if (textLength widget.length) return widget.length - 1; return textLength; } override Widget build(BuildContext context) { return GestureDetector( onTap: () { if (widget.enabled) _focusNode.requestFocus(); }, child: Stack( alignment: Alignment.center, children: [ Opacity( opacity: 0, child: SizedBox( width: widget.cellWidth * widget.length widget.spacing * (widget.length - 1), height: widget.cellHeight, child: TextField( controller: _controller, focusNode: _focusNode, enabled: widget.enabled, keyboardType: TextInputType.number, inputFormatters: [ FilteringTextInputFormatter.digitsOnly, LengthLimitingTextInputFormatter(widget.length), ], showCursor: false, decoration: const InputDecoration.collapsed(hintText: ), ), ), ), ListenableBuilder( listenable: _notifier, builder: (context, _) { final text _notifier.value; return Row( mainAxisSize: MainAxisSize.min, children: List.generate(widget.length, (index) { final char index text.length ? text[index] : ; final isFocused _focusNode.hasFocus index _currentFocusIndex; final isFilled index text.length; return Padding( padding: EdgeInsets.only( right: index widget.length - 1 ? widget.spacing : 0, ), child: _CodeCell( char: char, isFocused: isFocused, isFilled: isFilled, width: widget.cellWidth, height: widget.cellHeight, ), ); }), ); }, ), ], ), ); } } class _CodeCell extends StatelessWidget { final String char; final bool isFocused; final bool isFilled; final double width; final double height; const _CodeCell({ required this.char, required this.isFocused, required this.isFilled, required this.width, required this.height, }); override Widget build(BuildContext context) { final theme Theme.of(context); final borderColor isFocused ? theme.colorScheme.primary : theme.dividerColor; return AnimatedContainer( duration: const Duration(milliseconds: 150), width: width, height: height, decoration: BoxDecoration( color: isFilled ? theme.colorScheme.primaryContainer.withOpacity(0.3) : Colors.transparent, border: Border.all( color: borderColor, width: isFocused ? 2 : 1, ), borderRadius: BorderRadius.circular(8), ), alignment: Alignment.center, child: Text( char, style: theme.textTheme.headlineSmall?.copyWith( fontWeight: FontWeight.w600, ), ), ); } }4.3 关键参数的计算与选择格子的宽度和间距不是随便定的。假设你的屏幕宽度是 375 逻辑像素iPhone SE 的宽度四位验证码左右各留 24 像素边距那么可用宽度是 375 - 48 327 像素。四个格子加三个间距如果间距是 12那么每个格子的宽度就是 (327 - 36) / 4 ≈ 72.75。这个宽度其实偏大了视觉上会显得格子很胖。我一般会把格子宽度控制在 44 到 52 之间这样看起来比较精致。如果屏幕宽度不够可以适当减小间距或者格子宽度。更好的做法是用LayoutBuilder根据可用宽度动态计算格子宽度LayoutBuilder( builder: (context, constraints) { final totalSpacing widget.spacing * (widget.length - 1); final availableWidth constraints.maxWidth - totalSpacing; final cellWidth (availableWidth / widget.length).clamp(36.0, 56.0); // 用 cellWidth 渲染格子 }, )这样无论屏幕多宽多窄格子都能保持一个合理的尺寸范围。clamp方法确保格子不会太小小于 36 就看不清了也不会太大大于 56 就显得笨重。4.4 暗黑模式与主题适配主题适配这块我踩过的坑主要集中在对颜色的硬编码上。早期版本我直接写死了Colors.grey和Colors.blue结果暗黑模式下格子边框几乎看不见。后来改成从Theme.of(context)里取颜色问题就解决了。具体来说边框颜色用theme.dividerColor聚焦时的边框用theme.colorScheme.primary已填充格子的背景用theme.colorScheme.primaryContainer.withOpacity(0.3)文字颜色用theme.textTheme.headlineSmall自带的颜色。这样无论应用切换到什么主题组件都能自动适配。实操心得withOpacity在新版 Flutter 里已经被标记为废弃推荐用withValues(alpha: 0.3)替代。如果你的项目 Flutter 版本较新记得改一下。5. 常见问题与排查技巧实录5.1 粘贴验证码只进去一位怎么办这是路线一多个独立 TextField的经典问题但在路线二里几乎不会出现。如果你用的是路线二还是遇到这个问题检查一下inputFormatters里是不是加了LengthLimitingTextInputFormatter(1)之类的限制。另外确保TextField的maxLines是 1且没有设置maxLength属性用inputFormatters来控制长度不要用maxLength因为maxLength会显示计数器。5.2 键盘弹起后输入框被遮挡这个问题跟验证码组件本身关系不大但经常一起出现。解决方案是在页面层面用SingleChildScrollView包裹内容或者在Scaffold里设置resizeToAvoidBottomInset: true默认就是 true。如果输入框在页面底部可以考虑用AnimatedPadding根据MediaQuery.viewInsets.bottom来动态调整底部间距。5.3 删除时焦点不回溯在路线二里删除操作由TextField原生处理焦点索引是根据文本长度自动计算的所以不存在“焦点不回溯”的问题。如果你发现删除后高亮格子没有跟着变检查一下_notifier是否在_onTextChanged里正确更新了。有时候TextEditingController的text在删除时会触发两次通知一次是文本变化一次是 selection 变化确保你的逻辑能正确处理重复通知。5.4 自动聚焦不生效autoFocus参数如果直接在TextField上设autofocus: true有时候会因为页面还没完全渲染而失效。更可靠的做法是在initState里用WidgetsBinding.instance.addPostFrameCallback延迟一帧再请求焦点。上面代码里就是这么处理的。5.5 常见问题速查表问题现象可能原因解决方案键盘弹不出来TextField 被隐藏或 opacity 为 0用 Opacity 包裹但保持可见性不要用 Visibility粘贴只进一位inputFormatters 限制了长度去掉 LengthLimitingTextInputFormatter(1)格子高亮不更新notifier 未触发或监听未生效检查 ListenableBuilder 的 listenable 是否正确暗黑模式看不清颜色硬编码改用 Theme.of(context) 取色输入满后键盘不收未调用 unfocus在 onCompleted 前调用 _focusNode.unfocus()格子宽度不一致未用 LayoutBuilder 动态计算用 LayoutBuilder clamp 控制宽度范围5.6 独家避坑技巧第一个技巧不要在build方法里创建TextEditingController和FocusNode。我见过不少新手把这两个对象写在build里结果每次重建都会创建新对象导致焦点丢失、文本清空。它们必须放在State的成员变量里在initState中初始化在dispose中释放。第二个技巧ValueNotifier的初始值要和controller.text保持一致。如果你在外部通过controller.text 1234预设了值记得同步更新notifier.value否则界面显示会和实际文本不一致。第三个技巧测试时一定要试粘贴。在模拟器里长按输入框选择“粘贴”看看能不能正确填入。很多验证码组件的 bug 都是在粘贴场景下暴露出来的。第四个技巧考虑无障碍访问。给TextField加上semanticsLabel让屏幕阅读器能正确朗读。虽然验证码组件本身对无障碍支持有限但至少不要让屏幕阅读器读出“文本框 文本框 文本框 文本框”这种混乱信息。6. 扩展方向与个人体会这个组件目前已经能满足绝大多数场景但如果你想做得更极致还有几个方向可以扩展。比如加上错误状态——当验证码校验失败时格子边框变红并抖动一下给用户明确的反馈。实现方式是在组件里加一个hasError参数然后在_CodeCell里根据这个参数切换边框颜色抖动动画可以用AnimationController配合Transform.translate来做。另一个方向是支持自定义格子样式。现在的格子是统一的圆角矩形但有些设计稿可能要求下划线样式、圆形样式、或者带阴影的卡片样式。可以加一个cellBuilder回调把格子的渲染完全交给调用方组件只负责提供char、isFocused、isFilled这三个状态。还有一个实用扩展是倒计时重发。虽然这不属于输入框本身的功能但验证码场景下经常需要“60 秒后重新获取”的按钮。可以把这个逻辑封装成一个独立的CountdownButton组件和验证码输入框配合使用。我个人在实际操作中的体会是验证码组件虽然小但它是检验一个开发者对 Flutter 文本输入体系理解程度的试金石。TextEditingController、FocusNode、ValueNotifier、ListenableBuilder这几个东西的配合方式在这个组件里体现得淋漓尽致。把这一套吃透了再去做搜索框、聊天输入框、表单输入这些更复杂的场景思路会清晰很多。最后分享一个小技巧如果你在开发过程中发现格子高亮总是慢半拍可以试试把AnimatedContainer的duration调短一点比如 100 毫秒。150 毫秒在大多数情况下没问题但在低端设备上可能会感觉到轻微延迟。这个值可以根据实际测试来微调没有绝对的标准。