1. 为什么要在 Flutter 里自己造一个数字键盘
移动端开发做久了，总会碰到系统键盘不听话的场景。尤其是涉及金额输入、密码输入、验证码输入这类业务，系统键盘弹出来那一瞬间，布局被顶飞、光标乱跳、输入框被遮挡，用户体验直接掉一个档次。更别提有些定制化需求，比如键盘上要带“清空”“完成”“小数点禁用”这类业务按钮，系统键盘根本没法满足。
我最近接手的一个项目就遇到了这个问题。页面底部有一个固定悬浮的输入区域，点击后需要弹出一个纯数字键盘，要求键盘高度可控、按键布局自定义、并且不能把整个页面顶上去。最开始尝试了TextField配合keyboardType: TextInputType.number，结果在部分机型上系统键盘依然会带出字母切换键，而且键盘高度完全不可控。后来又试了SystemChannels.textInput去拦截，代码复杂度飙升，维护成本极高。
最终我选择了Overlay这个方案。Overlay 是 Flutter 框架自带的一个层叠布局机制，它允许你把一个 Widget 插入到当前页面的最上层，独立于原有的 Widget 树。用它来做自定义键盘，好处非常明显：键盘的显示和隐藏完全由自己控制，不依赖系统输入法；键盘可以做成任意布局；而且因为它是插入到 Overlay 中的，不会影响原有页面的布局结构，不会出现“页面被顶上去”的尴尬情况。
这篇文章我会把整个实现过程拆开讲清楚，包括 Overlay 的核心原理、键盘的布局设计、输入框与键盘的联动逻辑、光标与文本插入的处理、以及我在实际开发中踩过的那些坑。如果你也在做 Flutter 的定制输入场景，这套方案可以直接抄作业。
2. Overlay 机制的核心原理与选型考量
2.1 Overlay 到底是什么，为什么它适合做键盘
Overlay 在 Flutter 里其实是一个Stack的变体。每个Navigator内部都会维护一个 Overlay，路由跳转本质上就是往 Overlay 里插入和移除OverlayEntry。你可以把它理解成一张“悬浮在页面之上的透明画布”，任何插入到这张画布上的 Widget 都会显示在当前页面内容的上方。
关键点在于：Overlay 里的 Widget 不参与原有页面的布局计算。也就是说，你把键盘插入 Overlay 后，页面本身的Column、ListView不会因为键盘的出现而重新布局。这一点和系统键盘的行为完全不同——系统键盘弹出时，Scaffold的resizeToAvoidBottomInset会触发页面重新布局，导致内容被压缩或顶起。
用 Overlay 做键盘，本质上就是自己管理一个悬浮层。显示键盘就是Overlay.of(context).insert(entry)，隐藏就是entry.remove()。整个过程干净利落，没有多余的副作用。
2.2 为什么不用 BottomSheet 或 Dialog
你可能会问，用showModalBottomSheet不也能弹出一个底部面板吗？确实可以，但有几个致命问题。
第一，BottomSheet默认带有模态遮罩，会阻挡页面上其他区域的点击。而数字键盘通常需要用户能同时看到输入框和键盘，模态遮罩会破坏这个交互。
第二，BottomSheet的动画和高度控制虽然可以自定义，但它的生命周期和路由绑定，关闭时需要Navigator.pop，在复杂的页面栈里容易出问题。比如用户快速切换页面时，BottomSheet可能还来不及关闭就跟着路由一起销毁，导致状态异常。
第三，Dialog就更不合适了，它是居中弹窗，和键盘的底部悬浮定位完全不符。
Overlay 的优势就在于它是“无状态”的——你插入一个OverlayEntry，它就存在；你调用remove()，它就消失。不涉及路由栈，不涉及模态管理，完全由开发者掌控。
2.3 整体方案设计思路
我的整体设计分为三个部分：
- 键盘 Widget：负责渲染数字按键、小数点、删除键、完成键等，处理点击事件。
- Overlay 管理器：负责键盘的插入、移除、动画控制，以及键盘高度的计算。
- 输入控制器：负责接收键盘传来的按键事件，更新输入框的文本和光标位置。
这三者之间通过回调函数通信，耦合度低，方便单独测试和替换。输入控制器我封装了一个CustomInputController，内部持有一个TextEditingController和一个FocusNode，键盘按键触发时直接操作TextEditingController的text和selection属性。
提示：不要试图用
FocusNode去唤起系统键盘，因为我们的目标是完全屏蔽系统键盘。在输入框的onTap里直接调用FocusScope.of(context).unfocus()，然后显示自定义键盘。
3. 键盘布局设计与核心细节解析
3.1 按键布局的网格化设计
数字键盘的布局看起来简单，但要做得规整、适配不同屏幕宽度，还是需要一点技巧。我采用的是经典的 4 列 4 行布局：
| 列1 | 列2 | 列3 | 列4 |
|---|---|---|---|
| 1 | 2 | 3 | 删除 |
| 4 | 5 | 6 | 清空 |
| 7 | 8 | 9 | 完成 |
| . | 0 | 00 | 完成（跨行） |
实际实现时，我用GridView或者Table都可以，但更推荐用Column+Row手动拼，因为按键的宽高比、间距、圆角这些细节用GridView反而不好控制。每个按键封装成一个KeyboardButtonWidget，接收label、onTap、flex等参数。
按键的高度我一般设置为键盘总高度的1/4减去间距。键盘总高度建议设为屏幕高度的 40% 左右，或者固定 280dp。这个值可以根据业务需求调整，但不要低于 240dp，否则按键太小，误触率会很高。
3.2 按键的视觉反馈与防误触
数字键盘的按键点击频率很高，如果没有任何视觉反馈，用户会感觉“没按到”。我在KeyboardButton里用了GestureDetector的onTapDown和onTapUp来切换背景色，模拟按压效果。注意不要用InkWell，因为InkWell的水波纹动画在快速点击时会有延迟感，数字键盘需要的是“即按即反馈”。
防误触方面，我做了两件事。第一，按键之间保留至少 1dp 的间距，避免相邻按键的点击区域重叠。第二，在onTap回调里加了一个 200ms 的节流，防止用户手抖连点导致重复输入。这个节流不是必须的，但在金额输入场景下非常有用，避免用户不小心输入了“1111”而不是“111”。
3.3 删除键的长按连续删除
删除键如果只能点一次删一个字符，用户输入长数字时会很痛苦。我给它加了长按连续删除的功能。实现方式是：在onTapDown时启动一个Timer.periodic，每隔 100ms 触发一次删除，onTapUp或onTapCancel时取消 Timer。同时，第一次点击时立即删除一个字符，然后延迟 500ms 再启动连续删除，这样短按和长按的体验都很自然。
Timer? _deleteTimer; void _onDeleteTapDown() { _deleteOnce(); _deleteTimer = Timer(const Duration(milliseconds: 500), () { _deleteTimer = Timer.periodic(const Duration(milliseconds: 100), (_) { _deleteOnce(); }); }); } void _onDeleteTapUp() { _deleteTimer?.cancel(); _deleteTimer = null; }注意：
Timer一定要在 Widget 的dispose里取消，否则会导致内存泄漏，页面销毁后 Timer 还在跑，操作已经失效的TextEditingController会直接抛异常。
3.4 小数点与“00”键的处理逻辑
小数点键不是任何时候都能点的。如果当前输入已经包含小数点，再点就应该忽略。如果输入为空，点小数点应该自动补一个“0.”。这些逻辑需要在输入控制器里做判断。
“00”键也是类似，如果当前输入为空，点“00”应该变成“0”，而不是“00”。如果小数点后已经有两位，再点“00”应该被拦截。这些细节看起来小，但直接影响用户对键盘“好不好用”的判断。
我在CustomInputController里写了一个_canInputDot()和_canInputDoubleZero()方法，每次按键前先校验，不满足条件就直接 return，不做任何操作。
4. 完整实操流程与核心环节实现
4.1 初始化 Overlay 与键盘入口
首先，你需要在页面的build方法里拿到OverlayState。通常是在MaterialApp的builder里或者页面的BuildContext里通过Overlay.of(context)获取。但要注意，Overlay.of(context)必须在Overlay已经存在的上下文中调用，否则会返回 null。
我的做法是在页面的initState里延迟一帧获取：
OverlayState? _overlayState; @override void didChangeDependencies() { super.didChangeDependencies(); _overlayState = Overlay.of(context); }然后定义一个OverlayEntry：
OverlayEntry? _keyboardEntry; void _showKeyboard() { if (_keyboardEntry != null) return; _keyboardEntry = OverlayEntry( builder: (context) => Positioned( left: 0, right: 0, bottom: 0, child: CustomNumberKeyboard( controller: _inputController, onDone: _hideKeyboard, ), ), ); _overlayState?.insert(_keyboardEntry!); } void _hideKeyboard() { _keyboardEntry?.remove(); _keyboardEntry = null; }这里用Positioned把键盘固定在底部，left: 0, right: 0让它横向撑满，bottom: 0贴底。如果你需要键盘上方有一个半透明遮罩，可以在OverlayEntry的 builder 里再包一层GestureDetector，点击遮罩时关闭键盘。
4.2 输入框与键盘的联动
输入框我用的是TextField，但做了几处改造。第一，readOnly: true，禁止系统键盘弹出。第二，showCursor: true，保留光标显示。第三，在onTap里调用_showKeyboard()。
TextField( controller: _textController, readOnly: true, showCursor: true, onTap: () { FocusScope.of(context).unfocus(); _showKeyboard(); }, decoration: InputDecoration( hintText: '请输入金额', border: OutlineInputBorder(), ), )这里有一个关键点：readOnly: true虽然禁止了系统键盘，但TextField仍然可以获取焦点，光标仍然会显示。如果你不希望光标显示，可以把showCursor设为 false，但那样用户就不知道当前输入位置了，体验反而不好。
4.3 文本插入与光标位置管理
键盘按键触发时，不能简单地_textController.text += '1'，因为这样光标会跳到末尾。正确的做法是操作TextEditingController的selection属性。
void insertText(String text) { final value = _textController.value; final selection = value.selection; final start = selection.start; final end = selection.end; final newText = value.text.replaceRange(start, end, text); final newOffset = start + text.length; _textController.value = value.copyWith( text: newText, selection: TextSelection.collapsed(offset: newOffset), composing: TextRange.empty, ); }删除逻辑类似，但要注意当光标在末尾时删除最后一个字符，当光标在中间时删除光标前一个字符。如果选中了一段文本，删除应该直接删掉选中部分。
void deleteText() { final value = _textController.value; final selection = value.selection; final start = selection.start; final end = selection.end; if (start == end) { if (start == 0) return; final newText = value.text.replaceRange(start - 1, start, ''); _textController.value = value.copyWith( text: newText, selection: TextSelection.collapsed(offset: start - 1), ); } else { final newText = value.text.replaceRange(start, end, ''); _textController.value = value.copyWith( text: newText, selection: TextSelection.collapsed(offset: start), ); } }提示：
composing: TextRange.empty这行很重要。如果不设置，在某些输入法框架下可能会残留 composing 区域，导致文本显示异常。
4.4 键盘动画与显示隐藏过渡
直接插入和移除OverlayEntry是没有动画的，键盘会“啪”一下出现，体验很生硬。我用了AnimatedPositioned或者SlideTransition来做过渡。
最简单的方式是在OverlayEntry的 builder 里包一个TweenAnimationBuilder：
OverlayEntry( builder: (context) => TweenAnimationBuilder<double>( tween: Tween(begin: 1.0, end: 0.0), duration: const Duration(milliseconds: 250), curve: Curves.easeOut, builder: (context, value, child) { return Transform.translate( offset: Offset(0, value * 300), child: child, ); }, child: CustomNumberKeyboard(...), ), )隐藏的时候，先播放反向动画，动画结束后再调用remove()。这里需要用一个AnimationController来管理，稍微复杂一点，但效果值得。
4.5 键盘高度与安全区域适配
不同手机的底部安全区域不一样，尤其是带手势条的机型。键盘的底部需要加上MediaQuery.of(context).padding.bottom，否则按键会被手势条遮挡。
Padding( padding: EdgeInsets.only( bottom: MediaQuery.of(context).padding.bottom, ), child: keyboardContent, )键盘的总高度我建议用MediaQuery.of(context).size.height * 0.4加上安全区域高度。这样在大屏手机上键盘不会显得太小，在小屏手机上也不会占满整个屏幕。
5. 常见问题与排查技巧实录
5.1 键盘弹出后页面被顶上去
这个问题通常是因为Scaffold的resizeToAvoidBottomInset默认为 true。虽然我们用的是 Overlay，理论上不会触发页面重新布局，但如果你在OverlayEntry里用了MediaQuery的viewInsets，或者页面本身有ListView监听了键盘高度，就可能出现这个问题。
解决办法：把Scaffold的resizeToAvoidBottomInset设为 false，并且在OverlayEntry里不要使用MediaQuery.of(context).viewInsets.bottom。
5.2 键盘显示后点击其他区域无法关闭
这是因为OverlayEntry默认不拦截外部点击。如果你希望点击键盘外部区域关闭键盘，需要在OverlayEntry的 builder 里加一个全屏的GestureDetector，放在键盘下方。
OverlayEntry( builder: (context) => Stack( children: [ Positioned.fill( child: GestureDetector( onTap: _hideKeyboard, behavior: HitTestBehavior.translucent, child: Container(color: Colors.transparent), ), ), Positioned( left: 0, right: 0, bottom: 0, child: CustomNumberKeyboard(...), ), ], ), )注意behavior: HitTestBehavior.translucent，这样透明区域也能响应点击。
5.3 快速切换页面时键盘残留
如果用户在键盘显示的状态下快速返回上一页，OverlayEntry可能来不及移除，导致键盘残留在新页面上。解决办法是在页面的dispose里强制移除：
@override void dispose() { _keyboardEntry?.remove(); _keyboardEntry = null; _textController.dispose(); super.dispose(); }同时，在_showKeyboard里加一个判断，如果_keyboardEntry已经存在，先移除再重新插入，避免重复插入。
5.4 常见问题速查表
| 问题现象 | 可能原因 | 解决办法 |
|---|---|---|
| 键盘弹出后页面被顶起 | resizeToAvoidBottomInset为 true | 设为 false |
| 点击键盘外部无法关闭 | OverlayEntry 没有全屏点击层 | 加 GestureDetector |
| 快速切页键盘残留 | dispose 未移除 Entry | dispose 里强制 remove |
| 删除键长按无响应 | Timer 未启动或提前取消 | 检查 onTapDown/onTapUp |
| 小数点可以重复输入 | 未做校验 | 加 _canInputDot 判断 |
| 光标跳到末尾 | 直接操作 text 属性 | 用 selection 控制 |
| 键盘底部被遮挡 | 未加安全区域 padding | 加 MediaQuery padding.bottom |
| 按键点击无反馈 | 用了 InkWell 或无水波纹 | 用 GestureDetector 手动切换背景色 |
5.5 实操心得与避坑建议
第一，不要在 OverlayEntry 里使用 StatefulWidget 的 setState 来更新键盘状态。因为 OverlayEntry 的 builder 是独立的，setState 不会触发键盘重建。如果需要动态更新键盘（比如切换按键禁用状态），应该用ValueNotifier或者ChangeNotifier来驱动。
第二，键盘的显示和隐藏要加防抖。用户快速点击输入框时，可能会连续触发_showKeyboard，导致插入多个 OverlayEntry。我在_showKeyboard开头加了if (_keyboardEntry != null) return;，确保同一时间只有一个键盘实例。
第三，测试时一定要在真机上跑。模拟器的键盘高度和安全区域和真机有差异，尤其是 iPhone 带手势条的机型，底部安全区域在模拟器上可能显示为 0，但真机上是 34dp。这个差异会导致键盘在真机上被遮挡。
第四，金额输入场景建议限制小数位数。我在insertText里加了一个校验，如果当前文本已经包含小数点且小数部分达到两位，再输入数字就直接忽略。这个逻辑虽然简单，但能避免很多脏数据。
第五，键盘的圆角和阴影不要做得太重。数字键盘是高频操作组件，视觉上应该轻量、干净。我用的是顶部圆角 16dp，阴影BoxShadow的 blurRadius 设为 8，颜色用Colors.black12，这样既有层次感又不抢眼。
6. 性能优化与扩展思路
6.1 减少 OverlayEntry 重建
OverlayEntry的 builder 在每次markNeedsBuild时都会重新执行。如果你的键盘 Widget 比较复杂，频繁重建会影响性能。我的做法是把键盘内容抽成一个独立的StatefulWidget，在OverlayEntry的 builder 里只创建一次，后续通过ValueListenableBuilder来更新按键状态。
OverlayEntry( builder: (context) => ValueListenableBuilder<KeyboardState>( valueListenable: _keyboardState, builder: (context, state, child) { return CustomNumberKeyboard( state: state, onKeyTap: _handleKeyTap, ); }, ), )这样键盘的静态部分不会重建，只有状态变化的部分会更新。
6.2 支持多种键盘模式
这套方案不仅可以做数字键盘，稍加改造就能支持身份证键盘（带 X）、车牌键盘（带省份简称）、甚至自定义符号键盘。核心思路是把按键布局数据化，用一个List<List<KeyModel>>来描述键盘布局，KeyModel包含label、value、type等字段。渲染时遍历这个二维数组，根据type决定按键的样式和行为。
class KeyModel { final String label; final String value; final KeyType type; const KeyModel(this.label, this.value, this.type); } enum KeyType { number, dot, delete, clear, done, doubleZero }这样切换键盘模式只需要换一份布局数据，代码复用率极高。
6.3 与表单校验的联动
在实际业务中，键盘输入的内容往往需要实时校验。比如金额不能超过限额、不能以小数点开头、不能有多个小数点等。我在CustomInputController里暴露了一个onChanged回调，每次文本变化时触发，外部可以传入校验函数，校验不通过时把错误信息显示在输入框下方。
_inputController.onChanged = (text) { final error = validateAmount(text); setState(() { _errorText = error; }); };这样键盘只负责输入，校验逻辑完全解耦，方便单独维护和测试。
6.4 无障碍适配
数字键盘的无障碍支持经常被忽略。我建议给每个按键加上Semantics标签，这样读屏软件可以正确朗读按键内容。
Semantics( label: '数字键 $value', button: true, child: KeyboardButton(...), )对于删除键，标签设为“删除”，完成键设为“完成”。这个改动很小，但对视障用户来说体验提升巨大。
7. 我个人在实际操作中的几点体会
这套 Overlay 自定义数字键盘的方案，我从第一个版本到现在稳定运行，前后迭代了大概四五个版本。最开始只考虑了功能实现，后来慢慢补上了动画、防抖、安全区域适配、无障碍支持这些细节。回头来看，最核心的经验就是：不要试图去改造系统键盘，而是完全绕开它。系统键盘的行为在不同平台、不同版本、不同机型上差异太大，你永远不知道下一个坑在哪里。用 Overlay 自己画一个键盘，虽然前期投入多一点，但后期的可控性和稳定性是完全值得的。
另外，输入控制器的文本插入和光标管理是整套方案里最容易出 bug 的地方。我建议你在写这部分逻辑时，一定要把TextEditingController的value当成一个不可变对象来操作，每次修改都通过copyWith生成新的 value，而不是直接改text属性。这样可以避免很多光标跳动和文本错乱的问题。
最后再分享一个小技巧：如果你需要在键盘上显示一个“完成”按钮，并且希望点击后收起键盘同时触发提交动作，可以在onDone回调里先调用_hideKeyboard()，然后延迟一帧再执行提交逻辑。因为键盘移除有一个动画过程，如果立即提交，页面可能会在键盘还没完全消失时就跳转，视觉上会很突兀。延迟 250ms 左右，等键盘动画结束再提交，体验会顺滑很多。
