简介这是一份基于Qt框架开发的虚拟小键盘实现面向需要在无物理键盘场景下为自定义控件提供输入支持的Qt开发者。项目通过传递自定义myspinbox控件指针使无边框键盘组件可灵活嵌入现有界面解决数字或字符输入与交互集成问题。压缩包仅3个文件包含keyboard.cpp核心逻辑与事件处理、keyboard.h类接口声明和keyboard.uiQt Designer可视化布局总大小约2KB结构紧凑便于直接阅读学习。目前已吸引265人学习下载。借助该资源可掌握Qt自定义控件派生如QSpinBox扩展、键盘事件响应、.ui文件编译流程以及嵌入式键盘的模块化设计思路适合有一定C基础、希望提升Qt界面交互能力的开发者快速参考。 做Qt开发这些年凡是跟触屏一体机、工控面板沾边的项目基本逃不开“虚拟小键盘”这个东西。最近给一个设备调试界面做了一个基于Qt的虚拟小键盘组件源码封装成一个qt虚拟小键盘.zip传给现场时顺便把整个实现思路和踩坑过程都整理了一遍。这套东西不仅解决了我手里的问题也把Qt里布局、事件发送、焦点管理、QSS定制、打包发布这些知识点串了起来。我先把项目背景交代清楚然后按“选型 - 核心实现 - 美化 - 集成发布 - 问题排查”这条线走一遍。内容按Qt 5.15.2 Qt Widgets环境写的Qt 6下绝大部分代码可以直接沿用。如果你正在做类似的触屏输入方案或者单纯想加深对Qt事件系统的理解这篇应该能帮你省不少时间。1. 项目背景与整体方案选型1.1 为什么需要自己写一个虚拟小键盘接到需求时现场是一台无外接键盘的触屏一体机界面是纯Qt Widgets写的但客户要求弹出一个浮在界面上的数字字母小键盘风格必须和主界面一致而且“只能显示我需要的按键”。我第一反应是直接用系统自带软键盘测试完就放弃了原因很直接系统软键盘是独立进程外观完全不可控圆角、配色、按键大小都改不动。系统软键盘默认会带出任务栏、输入法状态栏等一堆东西在调试设备上非常碍眼。焦点管理很不可控软键盘弹出时主窗体会频繁失焦用户体验很差。客户只想要数字、小数点、退格、回车这几个键系统键盘塞了一堆用不上的键操作面积也被压缩了。如果你也有类似需求用QSpinBox、QLineEdit的InputMask去限制输入内容是可以的但它解决不了“界面上需要有一个可见的、可点击的键盘面板”这个需求。所以最靠谱的思路就是自己写一个虚拟键盘控件嵌入到Qt应用里点哪个输入框就给它喂哪个输入框。1.2 技术路线QWidget搭配QSS而不是QML在立项时我评估过两条路线第一条是QML Qt Quick.Controls第二条是纯QWidget QSS。QML方案在动画效果和自定义绘制上更强Qt其实也有现成的Qt VirtualKeyboard模块但对我来说有几个问题项目主程序是Qt Widgets嵌入QML需要额外引入Qt Quick相关模块和QML runtime老项目升级成本高团队里纯C的人维护QML也不是很顺手。所以我选了QWidget QSS。理由很实在和现有Widgets代码是无缝衔接的可以直接new出来用不需要额外启动一个QML引擎。模块依赖少Qt5和Qt6都能编译项目里其他人接手也容易。QSS做按钮样式非常顺手圆角、渐变、按压缩放都能覆盖。信号槽机制天然适合按键之间的协调和向外部发送按键信息。选型这块没有绝对优劣。如果你的主程序本身就是QML工程那当然直接用Qt Quick的虚拟键盘更省事。我写这篇博文的场景是标准的Widgets程序所以下面所有代码和思路都围绕这个展开。1.3 功能清单与模块划分我把这个小键盘的需求收敛成了一张明确的清单方便后面编码时对照检查功能说明数字键0-9、小数点、正负号切换字母键26个字母支持大小写切换功能键退格、回车、空格、Shift浮动显示无边框窗口置顶可拖动自动输入点击按键后把内容送进当前焦点输入框不抢焦点键盘弹出后输入框光标不丢失样式可换全部按键用QSS控制外观模块上我拆成了三个部分VirtualKeyboard负责整体布局和业务逻辑KeyButton这块直接用QPushButton加属性即可不需要额外继承事件发送这块单独抽了一个函数处理。正常情况一个类加一个QSS文件就能搞定代码量不大但逻辑踩坑点不少。2. 核心实现按键布局与事件发送2.1 用QGridLayout搭建自适应按键面板按键面板我选用QGridLayout而不是一行一行堆QHBoxLayout。原因是QGridLayout天然支持表格行列布局而且可以很方便地做到“所有按键等宽等高”当键盘窗口被拉伸时按钮会自动填满空余区域。核心代码如下QGridLayout* layout new QGridLayout(this); layout-setSpacing(6); const QStringList numberKeys { 1, 2, 3, 4, 5, 6, 7, 8, 9, ., 0, - }; for (int i 0; i numberKeys.size(); i) { QPushButton* btn new QPushButton(numberKeys.at(i), this); btn-setSizePolicy(QSizePolicy::Expanding, QSizePolicy::Expanding); layout-addWidget(btn, i / 3, i % 3); }这里最关键的是每条按钮都设置了QSizePolicy::Expanding这么做的目的是让按钮在窗口缩放时自动拉伸。做触摸屏应用时按键不能太小一般推荐把按钮最小尺寸控制在48x48像素以上这也是触屏行业约定俗成的一个安全点击尺寸太小了操作工戴手套点不准。如果某一排按键数量不满不需要硬塞空控件用layout-setColumnStretch(0, 1)这种方式把列之间的比例调好视觉上就不会歪。我后来在数字键盘和字母键盘切换时前排有3个键、后排有3个键用Grid布局切换非常方便。2.2 按键映射从按钮文本到实际输入很多新手写虚拟键盘喜欢根据按钮文本判断行为比如文本等于-就是退格等于 就是空格。这种做法在按钮少的时候看着简单但一旦加Shift、Enter、大小写切换等特殊功能键代码会乱成一锅粥而且按钮文本一旦为了显示好看改成中文字符判断逻辑也要跟着变。我建议用枚举区分按键动作。创建按键时传入一个KeyAction用QMapQPushButton*, KeyAction保存映射关系enum KeyAction { KeyNormal, // 普通字符键 KeyBackspace, // 退格 KeyEnter, // 回车 KeySpace, // 空格 KeyShift // 大小写切换 };创建按钮的逻辑这样写QPushButton* VirtualKeyboard::createKey(const QString label, KeyAction action) { QPushButton* btn new QPushButton(label, this); btn-setSizePolicy(QSizePolicy::Expanding, QSizePolicy::Expanding); btn-setFocusPolicy(Qt::NoFocus); m_keyActions.insert(btn, action); connect(btn, QPushButton::clicked, this, [this, btn]() { handleKey(m_keyActions.value(btn), btn-text()); }); return btn; }点击时统一进入handleKey函数void VirtualKeyboard::handleKey(KeyAction action, const QString text) { switch (action) { case KeyNormal: insertText(text); break; case KeyBackspace: sendKeyEvent(Qt::Key_Backspace, QString()); break; case KeyEnter: sendKeyEvent(Qt::Key_Return, QString(\n)); break; case KeySpace: insertText( ); break; case KeyShift: toggleShift(); break; } }这种设计的价值在于后续扩展符号键、Tab键、方向键时只需要加一个枚举和一个case分支而不是在一堆字符串比较里找逻辑。代码的可维护性和可读性都会好很多。2.3 向目标输入框发送按键信息这个环节是整个虚拟键盘的“心脏”做法有两种。第一种是直接操作焦点控件。通过QApplication::focusWidget()拿到当前焦点控件然后qobject_castQLineEdit*调用insert()方法。这种方案对QLineEdit很直接代码简洁但有一个问题如果焦点落在QTextEdit或自定义控件上insert()就未必存在。第二种是构造QKeyEvent用QCoreApplication::sendEvent发送给焦点控件。这种更接近物理键盘的真实行为兼容性更好。我在项目中最终采用了第二种。void VirtualKeyboard::sendKeyEvent(int qtKey, const QString text) { QWidget* focus QApplication::focusWidget(); if (!focus) return; QKeyEvent press(QEvent::KeyPress, qtKey, Qt::NoModifier, text); QKeyEvent release(QEvent::KeyRelease, qtKey, Qt::NoModifier, text); QApplication::sendEvent(focus, press); QApplication::sendEvent(focus, release); }普通字符键使用sendKeyEvent(Qt::Key_A, a)这种方式注意要同时设置Qt::Key枚举和文本。Qt::Key决定这个键是哪个物理键位text决定它输入什么字符。QLineEdit处理KeyPress时依赖event-text()来插入字符如果只传枚举不传文本很多输入控件会不做任何反应。注意如果只需要向QLineEdit输入QLineEdit::insert()其实比sendEvent更高效也不需要构造事件。但考虑到虚拟键盘可能被用在QTextEdit、QPlainTextEdit甚至自定义控件上sendEvent方案的通用性强很多。两种方案在同一个项目里也可以共存比如退格键走sendEvent普通文本走insert看实际场景取舍。2.4 焦点管理键盘不能抢输入框的焦点这是我实际开发中踩得最深的坑没有之一。刚开始我把键盘用一个普通QWidget弹出来结果发现用户点击键盘的那一刻输入框的光标立刻消失了。原因是键盘窗口弹出时默认是激活状态点击键盘按钮时焦点从输入框转移到了键盘窗口上输入框自然就失去了焦点。解决这个问题的思路有两个维度第一个维度是窗口不给激活权。设置窗口属性Qt::WA_ShowWithoutActivating并配合Qt::Tool | Qt::FramelessWindowHint | Qt::WindowStaysOnTopHint这些窗口标志。setWindowFlags(Qt::Tool | Qt::FramelessWindowHint | Qt::WindowStaysOnTopHint); setAttribute(Qt::WA_ShowWithoutActivating);Qt::Tool这个flag比较特殊它让窗口不抢占焦点、不出现在任务栏非常适合用来做这种悬浮面板。Qt::WindowStaysOnTopHint保证键盘永远在主窗口上层。第二个维度是禁止按钮抢焦点。每一个按键都要显式调用setFocusPolicy(Qt::NoFocus)否则点击按钮后焦点还是会先被按钮拿走。我就是在createKey()里统一设置了NoFocus这样不管用户点多少次按键焦点都始终留在当前输入框。这两个维度缺一不可缺了任何一个都会出现“键盘一弹出输入框就失焦”的问题。3. 界面美化与交互反馈3.1 QSS定制按键外观虚拟键盘毕竟是给现场操作人员用的外观不能太丑。QSS是我觉得最舒服的定制方式。以深色界面为例一套比较稳的按键样式如下QPushButton { background-color: #3c3f41; color: #ffffff; border: 1px solid #555555; border-radius: 6px; font-size: 20px; min-height: 48px; } QPushButton:hover { background-color: #4b6eaf; } QPushButton:pressed { background-color: #2d5a8c; padding-top: 2px; } QPushButton:focus { outline: none; }min-height: 48px是我做触屏应用时养成的习惯。桌面应用可以不用这么大但触屏场景下太小真的很误事。这里有个容易忽略的点:focus { outline: none; }。在Windows和Linux的部分平台上按钮获得焦点后会画一个虚线框触屏上看起来特别丑。设置NoFocus策略后大部分情况不会出现但加上这行更稳妥防止某些样式表在特殊环境下把焦点框画出来。3.2 无边框窗口拖动与置顶显示因为用了FramelessWindowHint窗口没有标题栏就不能靠系统拖动必须自己处理鼠标事件。我在键盘顶部留了一条空白区域当作拖动手柄然后在鼠标事件里实现移动void VirtualKeyboard::mousePressEvent(QMouseEvent* e) { if (e-button() Qt::LeftButton) { m_dragPos e-globalPosition().toPoint() - frameGeometry().topLeft(); } QWidget::mousePressEvent(e); } void VirtualKeyboard::mouseMoveEvent(QMouseEvent* e) { if (e-buttons() Qt::LeftButton) { move(e-globalPosition().toPoint() - m_dragPos); } QWidget::mouseMoveEvent(e); }注意Qt 5和Qt 6在鼠标位置获取上的区别。Qt 5用e-globalPos()Qt 6里globalPos()被废弃改用e-globalPosition().toPoint()。如果项目要跨两个大版本编译最好在这里包一层兼容逻辑。如果觉得整个键盘都是按键、没有空白区域可以拖那就在顶部加一个专门的手柄Widget把这个手柄的鼠标事件传递给VirtualKeyboard或者直接在顶部放一个不参与点击的空白label单独给它装事件过滤器。这个看实际布局怎么设计我建议第一行下面就是数字区拖动把手放最上方用背景透明但是事件区域存在的QWidget再配合鼠标事件体验比较自然。3.3 按键状态反馈与大小写切换打字必须有手感反馈QSS里的:pressed状态已经可以模拟出“按键被按下去”的视觉变化加一个padding-top: 2px的细节会让按键看起来有下沉感。大小写切换是虚拟键盘另一个交互重点。我给Shift键设置了setCheckable(true)这样切换的时候可以通过:checked状态显示高亮QPushButton[keyRoleshift]:checked { background-color: #ff9800; color: #000000; }实际的切换逻辑写在toggleShift()函数中void VirtualKeyboard::toggleShift() { m_shift !m_shift; for (auto it m_keyActions.begin(); it ! m_keyActions.end(); it) { QPushButton* btn it.key(); if (it.value() KeyNormal) { QString text btn-text(); btn-setText(m_shift ? text.toUpper() : text.toLower()); } } }改按钮文本的时候要注意连接的lambda捕获的是按下时的文本这个文本是从按钮上取的所以改了按钮文本之后下一次按键会自动取新文本逻辑上是通的。但有一类情况要小心如果你在handleKey里根据实例状态而不是按钮文本来处理字符那切换只改显示不改逻辑也会出问题。所以普通字符键的逻辑要保证“显示什么就发送什么”不要额外做二次映射。4. 集成到Qt工程与打包发布4.1 把虚拟键盘接入已有项目集成方式我建议做成一个独立类使用方只需要创建并显示即可VirtualKeyboard *keyboard new VirtualKeyboard(); keyboard-show();但键盘弹出来之后要出现在合适的位置。我这边是给主窗口的输入框安装事件过滤器在FocusIn事件里判断焦点控件类型然后让键盘移动到输入框下方再显示bool MainWindow::eventFilter(QObject* obj, QEvent* ev) { if (ev-type() QEvent::FocusIn) { if (auto* edit qobject_castQLineEdit*(obj)) { QPoint pos edit-mapToGlobal(QPoint(0, edit-height())); keyboard-move(pos.x(), pos.y() 5); keyboard-show(); } } return QWidget::eventFilter(obj, ev); }用mapToGlobal把输入框底部坐标转成屏幕坐标然后键盘的左上角放在这个位置。这样用户点击任意输入框键盘都会自动跟着输入框走体验比固定位置好很多。4.2 windeployqt打包与平台插件问题打包发布这块“No Qt platform plugin could be initialized”是高频噩梦。这不是程序逻辑问题本质是程序在运行时没有找到Qt平台插件Windows下就是platforms目录里的qwindows.dll。最稳妥的做法是使用Qt自带的windeployqt工具。在Qt命令行环境下执行windeployqt yourApp.exe它会自动把依赖的Qt库、插件目录、样式文件都复制到exe同级目录。但要注意如果程序运行时手动设置了QCoreApplication::addLibraryPath()要确保这个路径确实存在否则平台插件还是加载不到。杀毒软件偶尔会把Qt的dll误报隔离导致发布后程序启动崩溃。这种情况建议在发布机上关闭实时防护或者将所有dll加入白名单。如果你用了QSS文件、图片等资源用Qt资源系统打包进exe最省心。如果坚持用外部文件方式记得在发布目录里保留相对路径结构。还有一点提一下如果你或读者朋友是在国产系统比如麒麟上部署Qt程序遇到启动崩溃或缺库问题优先检查编译环境与目标系统的glibc版本是否匹配。最省事的方法是直接在目标系统同版本环境下编译或者用较老的基线系统编一套兼容版本。4.3 在不同平台上的适配经验Qt的跨平台很方便但细节上还是有一些坑。Windows下字体用微软雅黑或者Segoe UILinux下字体用Noto Sans CJK如果不指定字体Qt在不同的Linux发行版上效果差异会很明显。字体大小建议用QFontMetrics结合屏幕DPI计算不要写死。高分屏适配是老话题了。如果程序在4K屏上显示很小检查是否在main()开头添加了高DPI设置QApplication::setAttribute(Qt::AA_EnableHighDpiScaling);对Qt 6来说高DPI默认启用但Qt 5必须显式开启。开启之后大部分布局会自动放大不过QSS里的固定像素值和间距还是不会跟着变所以我前面一直强调尽量不要写死像素值布局让布局器自己算。5. 常见问题排查实录5.1 键盘一点就隐藏这个问题的典型表现是键盘弹出来点任意一个按键键盘瞬间消失或者主窗口闪烁。排查思路先检查窗口是否有Qt::WA_ShowWithoutActivating再检查所有按键是否设置了Qt::NoFocus。这两个设置只要漏掉一个就会让键盘窗口在点击时激活导致输入框失焦。失焦又会触发某些业务逻辑比如隐藏键盘或者重置状态表现就是“一点就隐藏”。如果是多文档或多窗口界面还要检查焦点控件的父窗口是否是当前活跃窗口。比如焦点输入框在子窗口A键盘却在主窗口最顶层此时点击键盘虽然焦点不丢但键盘和输入框不在同一个窗口层级用户会感觉键盘“挡不住”“点不到”。遇到这种情况把键盘的父窗口设置为输入框所在的顶层窗口而不是主窗口。5.2 点击按键没有任何反应这类问题比键盘隐藏更隐蔽因为界面看起来完全正常就是输入框里没有字符。我的排查步骤是这样的在handleKey入口加一行qDebug()先确认按键点击信号有没有触发。如果不触发检查connect是否建立成功。打印QApplication::focusWidget()的返回值。返回nullptr说明焦点在键盘窗口自己身上回到5.1的问题。如果焦点控件是QLineEdit测试直接用edit-insert(a)是否有效。如果insert有响应但sendEvent没响应大概率是QKeyEvent构造参数有问题检查text()参数是否传入。如果焦点控件不是常规输入控件而是自定义控件那要确认它的keyPressEvent里是否处理了对应键位。这里我补充一个细节QKeyEvent的构造里text参数不要和Qt::Key混淆。Qt::Key_A是键位文本是a。有些输入控件会根据text插入字符有些会根据key判断行为两个都设置正确才能保证通用性最好。5.3 输入中文怎么办这是一个需求层面容易踩爆的坑。如果只是数字加英文字母上文提到的按键映射方案完全够用。但如果你要支持中文输入问题复杂度会瞬间翻倍。中文输入法依赖输入法引擎Windows下是TSFLinux下是fcitx或IBus。虚拟键盘要从零实现中文输入比如拼音候选、模糊音、词库这是巨大的工程不适合在一个自制小键盘里硬做。我的建议是需求评审时明确键盘支持的字符集优先锁定数字、ASCII字母、常见符号。如果需要中文走另一条路线让目标输入框保留系统输入法能力虚拟键盘只负责在焦点控件上拉起输入法或者干脆在输入框旁额外做一个中文候选列表控件。这个问题的价值不在代码而在需求边界。提前跟客户对齐“哪些能输入、哪些不能输入”比后期疯狂加班补功能划算得多。5.4 高分屏下布局错位有朋友遇到过在4K显示器上跑键盘按钮变得很小或者首行按钮和末行按钮高度不一致整体布局歪掉。排查经验有两条检查QApplication::setAttribute(Qt::AA_EnableHighDpiScaling)有没有开启。Qt5在高DPI模式下如果不开启窗口尺寸按逻辑像素计算实际显示会非常模糊或过小。检查布局里是否有写死的setFixedSize或绝对坐标。虚拟键盘最好全部依赖layout的伸缩规则不要用setGeometry去摆按钮。遇到个别按钮宽度不一时优先检查该按钮是否被setMinimumWidth或者setMaximumWidth限制过。我在初版实现里给退格键额外设了一个固定宽度结果切换到字母键盘时所有按钮宽度都歪了后来统一改为Expanding问题就消失了。整个虚拟小键盘做下来我最深的一个体会是Qt里写一个能点的按钮面板并不难难点全在键盘与宿主窗口的交互关系上。焦点不抢、事件能送到、布局能自适应这三件事理顺了键盘本身只是往GridLayout里塞按钮的事。以后你的项目里遇到类似需求不妨也先做一个小小的浮窗原型把焦点行为验证清楚再往上叠功能。本文还有配套的精品资源点击获取