1. 需求分析与方案选型
1.1 先弄清楚“纯数字键盘”到底在解决什么问题
涉及Qt数字键盘的场景，我猜大多数人和我一样，第一反应是：“这不就是个带数字按钮的面板嘛，QPushButton加上网格布局，半小时搞定。”但真正在项目里把这个需求做扎实，远没有想象中简单。
我在某工业设备项目里做过一版软键盘，最初需求就一句话：“界面上需要输入数字，加个小键盘。”结果一装上就遇到了现实打击：用户用的是触摸屏，没有实体键盘，系统弹不出系统软键盘；退一步，就算能弹出来，系统键盘是大而全的全键盘布局，用户要找数字得眯着眼才能点到；再退一步，客户明确要求只能输入数字和小数点，字母、符号一个都不能出现，因为这是给产线工人用的，目标极其纯粹——输入净含量、批次号、设备参数。
三次退让之后，需求变得清晰了：我们需要一个纯数字、纯触摸友好的、能嵌入现有Qt界面、并且能和任意输入框对接的虚拟键盘组件。
纯数字虚拟键盘看似简单，它背后其实隐藏着几个真实痛点：
- 输入框焦点切换后，键盘要有联动，不能弹在屏幕中间挡住输入区；
- 按键的按压反馈必须明显，不然触摸屏用户不知道自己点没点到；
- 按回车、关闭键后，信号要能正确传给业务层；
- 键盘的尺寸策略：固定大小会显得呆，自适应又容易错位。
也就是说，这不是“画几个按钮”的问题，而是一个交互组件的设计问题。
1.2 方案选型：为什么用 Widgets 而不是 QML
Qt 实现数字键盘有两种主流路线：QWidget 和 QML。
QML 做数字键盘在动画和触摸体验上手感更好，特别是 iOS、Android 风格的回弹特效，QML 可以用 PropertyAnimation 轻松实现。但我的项目是基于 Widgets 的，理由有两条：
第一，项目里的主界面、业务逻辑全部基于 Widgets，为了一个小键盘引入一个 QML 引擎，维护成本会翻倍。第二，Widgets 版本可以通过QDialog或自定义QWidget直接嵌入布局，也可以作为独立窗口弹出，形态灵活度足够。
最终我采用的是：自定义一个继承自 QWidget 的键盘面板类，通过信号槽与输入框联动。
选 Widgets 还有一个隐藏好处：可以方便地集成到现有的 QSS 样式表体系中。QML 要用 Style 组件，而 QSS 对所有老的 Qt 项目几乎是零成本适配，客户要求换肤时只需改样式表。
2. 架构设计：让键盘成为可复用的独立组件
2.1 顶层设计原则
我的设计原则是三个：
- 解耦：键盘完全不关心哪个输入框正在使用，只负责发信号；
- 钩子：外部通过信号连接建立键盘与输入框的关系，而不是内部直接改输入框对象；
- 皮肤化：键盘外观完全走 QSS，代码里零硬编码颜色。
这里要重点说为什么要在键盘和输入框之间做一个“控制层”。如果直接把键盘的按键动作连接到特定 QLineEdit，那么每换一个输入框就要改键盘代码，多输入框界面直接爆炸。正确做法是：
输入框A -> 注册到键盘管理器 -> 获取当前活跃输入框 键盘按键 -> 发送字符信号 -> 管理器决定将字符写入哪个输入框这种模式下，键盘本身就是“发送广播”，谁需要谁去对接。我项目里就是这样做的，三个输入框共用一个小键盘，没有写一行多余的关联代码。
2.2 键盘的按键布局设计
数字键盘布局看起来只有 4 行 x 4 列（常用纯数字含小数点），但布局里边还是有讲究的。
我建议的按键划分：
- 第一行：7 8 9 退格
- 第二行：4 5 6 清空
- 第三行：1 2 3 回车
- 第四行：0 +/- 小数点 或 隐藏按钮（根据业务需求）
这里有个不能省的设计：退格键必须放在单独的一列，功能和数字键物理隔离。因为触摸屏上误触退格是极常见的操作失误，把退格放在最右上角可以减少误触概率，同时又符合用户“右上角是修正位”的直觉。
清空键要不要？必须有。产线操作员一天输几百个参数，错了要用退格一个一个删太煎熬。加一个一键清空，对效率的提升出乎意料。
小数点键严格来说只有需要输入小数的场景才显示。我做了个属性开关：setFloatEnabled (bool)，开启则显示小数点按钮，关闭则自动隐藏，同时把第四行变成 0 和回车两个大按键，布局更舒适。
2.3 键盘与输入框的联动机制
联动机制是整个组件能否真正方便复用的灵魂。
我实现过两种模式：
模式一：内嵌模式。键盘作为普通 widget 放进主界面的某个固定区域，通常适用于输入区固定、没有滚动条的“控制面板”型界面。键盘和输入框之间的通信方式是：
connect(m_keyboard, &VirtualKeypad::keyPressed, this, &MainWindow::onKeyPressed);模式二：弹出模式。键盘以独立顶层窗口出现，点击任意输入框时自动弹到输入框下方。这个模式更接近真实场景，因为大多数界面不会预留键盘区域。
模式二的核心在于“跟随输入框”：
void MainWindow::onLineEditClicked() { QLineEdit* edit = qobject_cast<QLineEdit*>(sender()); if (!edit) return; m_activeEdit = edit; QPoint globalPos = edit->mapToGlobal(QPoint(0, edit->height())); m_keyboard->move(globalPos); m_keyboard->show(); }这里有个必须注意的坑：如果界面是多屏或者窗口可直接拖动，直接用mapToGlobal拿到的坐标可能不对。稳妥的做法是在 showEvent 时重新计算位置，或者用QApplication::desktop()的可用区域做边界约束，防止键盘弹出屏幕外。
我最终用的是“弹出模式加边界校正”，因为项目里某些工控机上界面可能嵌在异形分辨率下，普通move会把键盘顶到屏幕外面。
3. 核心实现：UI 布局、样式定制与信号逻辑
3.1 布局搭建：用 QGridLayout 还是 QFormLayout？
搭建布局时选择 QGridLayout 是明确的。QGridLayout 可以精确控制行、列、跨距，非常适合键盘这类规则网格界面。
我在实际项目里是这样搭骨架的：
VirtualKeypad::VirtualKeypad(QWidget* parent) : QWidget(parent) { m_pGridLayout = new QGridLayout(this); m_pGridLayout->setSpacing(6); m_pGridLayout->setContentsMargins(8, 8, 8, 8); // 数字按键数组 for (int i = 1; i <= 9; ++i) { QPushButton* btn = new QPushButton(QString::number(i), this); btn->setObjectName(QStringLiteral("keyNum%1").arg(i)); connect(btn, &QPushButton::clicked, this, [this, i]() { emit keyPressed(QString::number(i)); }); m_numButtons.append(btn); } m_btnDot = new QPushButton(tr("."), this); m_btnClear = new QPushButton(tr("C"), this); m_btnBackspace = new QPushButton(tr("⌫"), this); m_btnEnter = new QPushButton(tr("确定"), this); // 使用 QGridLayout 添加控件，行、列 // 第一行：7 8 9 ⌫ m_pGridLayout->addWidget(m_numButtons[6], 0, 0); m_pGridLayout->addWidget(m_numButtons[7], 0, 1); m_pGridLayout->addWidget(m_numButtons[8], 0, 2); m_pGridLayout->addWidget(m_btnBackspace, 0, 3); // 第二行：4 5 6 C m_pGridLayout->addWidget(m_numButtons[3], 1, 0); m_pGridLayout->addWidget(m_numButtons[4], 1, 1); m_pGridLayout->addWidget(m_numButtons[5], 1, 2); m_pGridLayout->addWidget(m_btnClear, 1, 3); // 第三行：1 2 3 回车 m_pGridLayout->addWidget(m_numButtons[0], 2, 0); m_pGridLayout->addWidget(m_numButtons[1], 2, 1); m_pGridLayout->addWidget(m_numButtons[2], 2, 2); m_pGridLayout->addWidget(m_btnEnter, 2, 3); // 第四行：0 . 空格 回车扩展 m_btnDot->setText("."); m_pGridLayout->addWidget(m_btnZero, 3, 0); m_pGridLayout->addWidget(m_btnDot, 3, 1); // 回车按钮占两格（第三行 + 第四行的第 3 列） m_pGridLayout->addWidget(m_btnEnter, 2, 3, 2, 1); }这是纯数字键盘最经典的布局。第三行和第四行的回车按钮按行跨两格；如果允许小数，第四行就是 0、点、加减号按钮。不允许小数时，点按钮可以直接替换成空或做成平铺的大 0 按钮，视觉上会更均匀。
布局阶段最容易犯的错误是盲目使用 addWidget 从头排到尾，数字顺序排完后按键位置和用户习惯不匹配。正确顺序是先从业务规则确认按键映射（7 8 9 / 4 5 6 / 1 2 3 / 0），再按行布局。
3.2 信号捕获与字符逻辑
键盘组件只做一件事：发字符。但字符不是盲发，必须做合法性过滤，否则下层的输入框要做一堆判断。
我的做法是把过滤逻辑放在键盘的信号发射处：
void VirtualKeypad::onKeyClicked(int digit) { QString text = m_inputLimit >= 0 ? currentText() : QString(); emit digitPressed(digit); } void VirtualKeypad::setInputLimit(InputLimit limit) { m_inputLimit = limit; }具体来说，键盘内部维护一个currentText，这个字符串是键盘输入后的结果。用退格、清空时同步更新。键盘决策好了，外层输入框就不必再做大量二次验证。
在逻辑层还要考虑：
- 小数点不能重复输入。用户要输入“1.25”，如果中间误点了两次点，纯数字组件必须自动忽略第二个点。
- 如果数字前导零。输入“007”是否允许？业务上大多数设备号不希望出现前导零，但某些行业（比如称重）必须保留。做成配置项。
- 负数输入。正负号键只在允许负数时显示，且必须放在最前面才能生效，不能允许“123-”这种情况出现。
为了适配这些规则，我给VirtualKeypad加了一个结果字符串的校验方法：
bool VirtualKeypad::validateInput(const QString& text) const { if (text.isEmpty()) return true; // 检查小数位数目 if (m_decimalPlaces >= 0) { int dotPos = text.indexOf(QLatin1Char('.')); if (dotPos >= 0 && text.length() - dotPos - 1 > m_decimalPlaces) return false; } // 检查是否合法数字 bool ok = false; text.toDouble(&ok); return ok; }这样就把校验职责完全收在键盘组件内部，外层输入框只需要无条件接收字符即可。
3.3 外观定制：用 QSS 调出工业级手感
外观对数字键盘的影响很大——不是玄学，是真实可感知的：按键尺寸、间距、按压反馈是否清晰，直接影响触摸屏上的输入准确率與疲劳度。
我会用一套完整 QSS 来做皮肤化处理，下面是实际项目里的样式表格，可以直接抄走再改：
| 控件类型 | 主要 QSS 属性 | 说明 |
|---|---|---|
| 普通数字按键 | background-color: #3c3f41;color: #ffffff;font-size: 20px; | 深灰底白字，工业屏上不刺眼 |
| 退格键 | background-color: #ac7b2f; | 黄色系，醒目但不抢眼 |
| 清空键 | background-color: #a13b3b; | 红色暗示“危险操作”，容易区分 |
| 回车键 | background-color: #3b7d4e; | 绿色，表示确认 |
| 按下状态 | :pressed { background-color: #6f9e6f; } | 按下变色，触摸反馈必备 |
QSS 示例：
QPushButton#keyNum, QPushButton#keyDot { border: none; border-radius: 6px; background-color: #4b4e52; color: #f0f0f0; font-size: 20pt; font-weight: bold; } QPushButton#keyNum:pressed { background-color: #6b6f75; } QPushButton#keyBackspace { border-radius: 6px; background-color: #b0730e; color: white; font-size: 14pt; } QPushButton#keyClear { border-radius: 6px; background-color: #b92b27; color: white; font-size: 14pt; } QPushButton#keyEnter { border-radius: 6px; background-color: #287b4b; color: white; font-size: 14pt; }我在实际项目里踩过的一个坑：老式工控机分辨率 1024x768，如果 QSS 里用 20pt，字会非常大；但如果用 20px，在不同缩放比例下又可能莫名其妙地缩小。Qt 的 font-size 在设置时会对应不同 DPI，推荐做法是先固定键盘整体大小，再用比例设置字号，或者在 setStyleSheet 后手动测一次控件宽度，确保按钮能容纳文字。
我最后统一用像素字号配合固定尺寸的键盘，效果完全可控：
setFixedSize(320, 420);如果产品需要适配多分辨率，更推荐在基类里根据QScreen::availableGeometry动态计算合适尺寸，避免写死。
4. 键盘与输入框的交互闭环
4.1 当前焦点管理：谁在接收键盘输入？
键盘组件必须知道“当前该往哪个输入框输出”，否则就是无头苍蝇。
我的实现采用QPointer保存当前活跃的 QLineEdit，因为QPointer会自动处理窗口对象销毁的情况，避免野指针：
void VirtualKeypad::registerLineEdit(QLineEdit* edit) { if (!edit) return; connect(edit, &QLineEdit::editingFinished, this, [this, edit]() { if (m_currentEdit == edit) m_currentEdit = nullptr; }); } void VirtualKeypad::setTargetLineEdit(QLineEdit* edit) { m_currentEdit = edit; }当一个新建的输入框成为当前接收输入的对象时，键盘的显示位置也需要跟着调整。
比较实用的做法是全局只维护一个键盘实例，谁调用谁注册：
connect(ui->lineEdit_mass, &QLineEdit::clicked, this, [this, edit = ui->lineEdit_mass]() { m_keypad->setTargetLineEdit(edit); m_keypad->raise(); });这里有几个容易忽略的细节：
QLineEdit本身没有clicked信号，需要子类重写mousePressEvent或采用事件过滤器，否则接不上。- 多条输入框同时存在时，务必在失去焦点时清空键盘的目标引用，否则之后用户已经切到另一窗口，老键盘还在往旧输入框里输出。
- 要支持多个输入框、多个页面共用同一键盘时，建议再做一层管理类，维护当前焦点，而不是每个页面都去直接操作键盘。
4.2 文本操作：退格、清空、确定如何反馈业务层
退格键的逻辑需要结合光标位置处理。简单项目里可以不考虑光标位置，直接在尾部删除。但在稍微复杂的需求中，比如用户插入了文本，或者修改了中间部分，简单尾部删除就会导致错乱。
我的方案是：统一采用尾部编辑模型，仅支持键盘输入框。
这种模型下实现退格非常简单：
void VirtualKeypad::onBackspaceClicked() { if (!m_currentEdit) return; QString text = m_currentEdit->text(); text.chop(1); m_currentEdit->setText(text); }清空键类似，置空即可。但回车键要特别注意：它不只是“填入字符”，而是代表一次完整输入结束，业务层通常需要执行确定、保存、跳转焦点等动作。所以我的键盘组件额外定义了enterPressed信号，与keyPressed分开：
connect(m_btnEnter, &QPushButton::clicked, this, [this]() { emit enterPressed(m_currentText); });这样业务层就可以同时获得“输入完成”的动作通知和完整文本，而不是靠猜按键顺序去拼文本。
防止输入框接受来自实体键盘的干扰也是值得做的：如果系统里存在物理键盘，用户按字母可能“绕开”数字键盘直接侵入输入框，导致数字键盘里显示的数字和文本框里的实际内容不一致。稳妥做法是设置输入框只读setReadOnly(true)，然后在数字键盘事件里完成文本的写入与删除。这样既防了实体键盘干扰，又保证了虚拟输入和真实显示永远同步。
5. 常见问题与排查技巧实录
5.1 故障现象：键盘弹出来后挡住了输入框
这是最常被问到的问题。实际上有三种方案，按推荐级别排序：
- 方案一：键盘用
Qt::WindowStaysOnTopHint置顶，并且位置在输入框附近，不遮挡输入位置； - 方案二：键盘放屏幕底部，避开输入区域；
- 方案三：键盘弹出后，自动把输入框滚动到可视区。
我项目里用的是方案一。设置窗口置顶还不够，有些嵌入式 Linux 环境 window manager 行为怪，单纯置顶不可靠。可靠的是：
setWindowFlags(Qt::Dialog | Qt::WindowStaysOnTopHint | Qt::FramelessWindowHint);如果你的程序是触摸屏全屏应用（常见工控场景），窗口建议同时打上Qt::WindowDoesNotAcceptFocus，这样点击输入框时焦点不会跑掉，键盘不会因为焦点切换自动隐藏。
5.2 按键“按了两次”或“按一下触发两遍”
原因几乎都是信号重复连接。QPushButton 的 clicked 信号反复连接是常见陷阱：比如构造时连了一次，初始化时又连了一次，导致 emit 一次触发两个槽。
排查方法：在最外层MainWindow里加个调试计数器，验证点击一次数字内部的keyPressed是否触发一次：
connect(m_keypad, &VirtualKeypad::keyPressed, this, [this](const QString& c){ qDebug() << "key pressed:" << c << m_count++; });如果确实是重复连接，把所有连接集中到一个初始化函数里，避免散落各处重连。
5.3 软键盘按下时输入框没有任何反应
这种问题通常是键盘找不到当前输入框，m_currentEdit为空或者已失效。最常见的原因是忘了在输入框受到点击之前注册。
推荐调试手段：在输入框的focusInEvent里输出当前目标指针：
void DebugLineEdit::focusInEvent(QFocusEvent* event) { qDebug() << "Focus in: " << objectName(); QLineEdit::focusInEvent(event); }另一个隐蔽的原因是智能指针问题：如果m_currentEdit用的是普通指针，输入框在某个时机被delete了，调用时就会崩溃或没有任何效果。用QPointer可以从根上规避。
5.4 如何支持键盘隐藏与输入框失焦
隐藏逻辑建议与焦点事件强绑定，输入框 focusOut 后延迟隐藏。原因是用户点键盘上的“确定”时输入框会先失去焦点，此时立刻隐藏会导致回车键没来得及触发。经验值是延迟 150~200ms 再隐藏，既不会闪断，也能保证最后一个输入事件完成。
connect(edit, &QLineEdit::editingFinished, this, [this]() { QTimer::singleShot(200, this, [this]() { if (!hasFocus()) hide(); }); });5.5 高 DPI 缩放下键盘错位
Qt 5.6 之后默认启用高 DPI 缩放。若键盘使用固定像素宽高，在某些缩放下会出现字体溢出按钮、按钮比例失调的问题。
最稳妥的措施：把键盘设计为可缩放布局，并重写resizeEvent动态调整字号：
void VirtualKeypad::resizeEvent(QResizeEvent* event) { QWidget::resizeEvent(event); int w = width() / 4; int h = height() / 4; foreach (QPushButton* btn, m_numButtons) btn->setFixedSize(w - 8, h - 8); m_btnEnter->setFixedSize(w * 2 - 8, h - 8); }这种方案比固定 setFixedSize 更适合跨分辨率、跨缩放场景，同时代码量也没有明显增加。
6. 封装成库：让键盘一次接入，到处复用
6.1 对外暴露的最小 API
如果希望键盘组件能够在团队内复用，必须设计干净、窄小的 API 接口。我做的最小接口集合如下：
| 接口 | 作用 |
|---|---|
setTargetLineEdit(QLineEdit*) | 绑定输入框 |
setFloatEnabled(bool) | 是否支持小数点 |
setNegativeEnabled(bool) | 是否支持负号 |
setDecimalPlaces(int) | 限制小数位数 |
setMaxLength(int) | 限制最大长度 |
setButtonText(int, const QString&) | 自定义按钮文案 |
applyStyleSheet(const QString&) | 内置皮肤切换 |
提供的外部暴露方法越少，封装越稳定。数字键盘的业务变化通常就这些，覆盖了 90% 的输入需求。
6.2 扩展思路：变成通用 HMI 输入组件
这个纯数字键盘其实还可以扩展成：
- 带字母的混合键盘；
- 带常用符号的键盘（负号、百分号）；
- 带两位小数专用简洁计算键盘；
- 用作密码键盘（切换显示/隐藏输入内容）。
我在实际项目里就做过一版带小数点和正负号的键盘，被直接复用到了三个不同设备上。
6.3 项目复盘：成本与收益
如果用最粗暴的QDialog + 26个按钮方式做，代码量在一两百行；但如果要做成组件化、可扩展、适配触摸屏、兼容多种输入规则，整体代码会到五百行左右。多出来的核心成本全在：校验逻辑 + 焦点管理 + 外观皮肤化。
但值得。因为一旦做完，后续接入新界面只需要三行代码：
m_keypad->setTargetLineEdit(ui->lineEdit_value); m_keypad->popup();硬件平台换了、屏幕分辨率改了、QSS皮肤要换色，都不用动业务逻辑。
在实际项目里，这套键盘在产线上跑了几个月，用户反馈最多的就是“按键大、好戳、不误触”。我自己回看整个开发过程，最想提醒后来人的一条经验是：接到这种“小需求”别急着开写，先把输入规则整理清楚，再决定键盘布局和校验逻辑，后面会省掉大量返工。
键盘在 Qt 里的实现门道不算多，真正的坑全藏在交互细节里。希望这篇记录能帮你少走一点弯路，造一个能让用户闭着眼戳数字也不出错的虚拟键盘。
