简介这是一份面向Qt开发者与嵌入式界面开发者的虚拟软键盘实现资源针对触摸屏或无实体键盘场景下需要文本输入的界面需求提供可直接嵌入现有工程的轻量级键盘组件。资源在Qt5.6环境下编写作者说明理论上兼容Qt4并已在PC机与ARM嵌入式开发板上验证运行适合具备一定Qt基础、希望快速补齐输入模块的开发者参考。压缩包共10个文件约14KB以cpp与h源码为主体配合pro工程文件、ui界面文件及用户配置类文件结构精简核心键盘逻辑与主窗口示例分离清晰便于按需裁剪移植。目前已有4930人学习下载读者可从中获得键盘布局与按键响应的实现思路、信号槽交互方式以及跨平台移植的参考做法减少从零搭建软键盘的试错成本。1. 从一块触摸屏说起QT虚拟软键盘能解决什么去年帮某公司做一个工控一体机的项目硬件到位、系统跑起来结果卡在一个特别朴素的问题上设备没有物理键盘只有一块电阻触摸屏用户要输入参数、填工单号系统自带的输入法要么弹不出来要么弹出来挡住半个界面要么在嵌入式环境里根本没装。那几天翻来覆去改最后落到一个很直接的方案上——自己用 QT 写一套虚拟软键盘跟着输入框走点哪儿弹哪儿用完自动收。这份 QT 虚拟软键盘资源解决的就是这类场景嵌入式触摸设备、自助终端、医疗仪器面板、收银机凡是「有屏幕没键盘」的地方都需要它。它适合两类人一类是刚接手 QT 项目、被输入法问题卡住的新手照着能跑通另一类是要把软键盘嵌进自己业务界面的熟手关心的是架构怎么拆、按键怎么映射、焦点怎么管。2. 技术选型与工程结构为什么是 QWidget 而不是 QML2.1 选型逻辑QWidget 路线在嵌入式场景的性价比拿到这个项目第一件事是看它用什么技术栈。结论很明确纯 C Qt Widgets没有引入 QML也没有依赖第三方输入法框架。这个选择在嵌入式触摸场景里是有道理的。QML 做动画和触摸手势确实漂亮但代价是运行时多一层 Qt Quick 引擎内存占用和启动时间都上去了很多工控板子跑的是精简版 LinuxQt Quick 模块未必完整编进去。Widgets 路线的好处是编译产物小、依赖少、和现有业务界面大概率也是 Widgets 写的无缝混排一个QWidget子类就能塞进任何布局里。软键盘本身的核心诉求其实不复杂一组按钮、一个按键信号、一个文本提交接口、一套焦点跟随逻辑。用 Widgets 实现代码量可控调试直观出问题看堆栈就能定位。常见做法是把键盘做成一个独立的顶层窗口Qt::Tool或Qt::Popup类型而不是嵌在主窗口布局里这样它不会挤压业务界面弹出位置也能自由控制。提示如果目标板子的 Qt 是裁剪编译的先确认widgets模块在quick模块不在也没关系这个方案不依赖它。2.2 目录结构一个可独立编译的键盘模块长什么样这类资源通常按「键盘模块 演示主程序」两层组织目录大致如下。不同版本细节会有出入但骨架基本一致VirtualKeyboard/ ├── VirtualKeyboard.pro # qmake 工程文件 ├── src/ │ ├── keyboardwidget.h/.cpp # 键盘主窗口布局与按键管理 │ ├── keybutton.h/.cpp # 单个按键控件处理按下/长按 │ ├── keyboardlayout.h/.cpp # 键位表定义字母/数字/符号页 │ └── inputcontext.h/.cpp # 焦点跟踪与文本提交桥接 ├── demo/ │ ├── main.cpp # 演示入口 │ └── mainwindow.h/.cpp # 带若干输入框的示例界面 └── resources/ └── keyboard.qrc # 图标、样式表资源这个拆法的关键在inputcontext这一层。键盘本身不该知道「当前是哪个输入框」它只负责产生字符和功能键事件谁在接收、光标在哪、要不要限制长度交给一个中间层去管。这样键盘可以复用到任何界面业务代码只需要在输入框获得焦点时通知键盘「目标变了」。2.3 工程文件与编译依赖.pro文件是理解依赖关系最直接的地方典型内容如下# VirtualKeyboard.pro QT core gui widgets # 只依赖基础模块不引入 quick TARGET VirtualKeyboard TEMPLATE lib # 编成静态库或动态库供业务引用 CONFIG staticlib c11 INCLUDEPATH src SOURCES \ src/keyboardwidget.cpp \ src/keybutton.cpp \ src/keyboardlayout.cpp \ src/inputcontext.cpp HEADERS \ src/keyboardwidget.h \ src/keybutton.h \ src/keyboardlayout.h \ src/inputcontext.h RESOURCES resources/keyboard.qrcTEMPLATE lib加CONFIG staticlib意味着这个键盘是作为库产出的业务工程在.pro里LIBS -L... -lVirtualKeyboard就能链进来。如果只是想快速看效果把TEMPLATE改成app、把demo/main.cpp加进SOURCES直接编译成可执行程序也行。c11是底线代码里用到了std::function做按键回调老编译器会报错。编译命令按 qmake 的标准流程走qmake VirtualKeyboard.pro make -j4如果板子上是交叉编译环境先 source 对应的 qmake 环境再执行上面两条。编译报「找不到 widgets 模块」说明 Qt 安装不完整需要补装qtbase5-dev或对应版本的开发包。3. 核心模块拆解按键、布局与焦点跟踪三条线3.1 按键控件一个按钮要处理的不只是 clicked很多人以为软键盘的按键就是QPushButton加个clicked信号真做起来会发现不够用。触摸屏上手指按下去有抖动快速连打会丢字符长按删除要连续触发这些都得在按键控件里处理。核心实现大致是这样// keybutton.cpp KeyButton::KeyButton(const QString text, KeyType type, QWidget *parent) : QPushButton(text, parent), m_type(type) { setFocusPolicy(Qt::NoFocus); // 关键按键本身不抢焦点 setAutoRepeat(true); // 开启自动重复支持长按删除 setAutoRepeatDelay(400); // 首次重复延迟 400ms setAutoRepeatInterval(60); // 之后每 60ms 触发一次 connect(this, QPushButton::clicked, this, [this]() { emit keyPressed(m_type, text()); }); }setFocusPolicy(Qt::NoFocus)是血泪经验。默认按钮会抢焦点一点键盘输入框就失焦了光标消失后续字符不知道往哪儿送。把按键设成不接收焦点焦点始终留在业务输入框上键盘只做「事件转发」。setAutoRepeat配合clicked信号长按退格键就能连续删字符不用自己写定时器。keyPressed信号带两个参数按键类型字符键、退格、回车、切换页、隐藏和文本内容上层根据类型分流处理。3.2 键位布局用数据表驱动别把按钮写死键位如果一个个new QPushButton写死加一个符号页就得改一堆代码。合格的做法是用数据表描述每一页的键位布局代码只负责遍历生成// keyboardlayout.cpp const QListQListKeyDef KeyboardLayout::pages() { static const QListQListKeyDef data { // 第 0 页小写字母 { {q},{w},{e},{r},{t},{y},{u},{i},{o},{p}, {a},{s},{d},{f},{g},{h},{j},{k},{l}, {Shift, KeyType::Func},{z},{x},{c},{v},{b},{n},{m}, {Del, KeyType::Backspace},{123, KeyType::SwitchPage},{Space, KeyType::Space} }, // 第 1 页数字与符号 { {1},{2},{3},{4},{5},{6},{7},{8},{9},{0}, {-},{_},{},{},{},{#},{.},{comma}, {Del, KeyType::Backspace},{ABC, KeyType::SwitchPage},{Space, KeyType::Space} } }; return data; }KeyDef是个简单结构体含显示文本和按键类型。KeyboardWidget在构造时遍历当前页的KeyDef按每行固定列数塞进QGridLayout。切页时清空布局重新生成或者预先建好所有页用QStackedWidget切换后者切换更快、不闪屏推荐后者。这样加一页德文、加一排功能键只改数据表布局代码一行不动。3.3 焦点跟踪与文本提交键盘和输入框之间的桥这是整个项目最容易翻车的地方。键盘要往「当前有焦点的输入框」里写字但 Qt 没有全局的「焦点变化」信号可以直接订阅。常见做法是装一个应用级事件过滤器监听QEvent::FocusIn// inputcontext.cpp bool InputContext::eventFilter(QObject *obj, QEvent *ev) { if (ev-type() QEvent::FocusIn) { // 只关心能接收文本输入的控件 if (auto *edit qobject_castQLineEdit *(obj)) { m_target edit; m_keyboard-showFor(edit); // 键盘定位到输入框下方 } else if (auto *text qobject_castQTextEdit *(obj)) { m_target text; m_keyboard-showFor(text); } } return QObject::eventFilter(obj, ev); } void InputContext::onKeyPressed(KeyType type, const QString text) { if (!m_target) return; switch (type) { case KeyType::Char: m_target-insertPlainText(text); // 统一走 QTextCursor 接口 break; case KeyType::Backspace: m_target-textCursor().deletePreviousChar(); break; case KeyType::Enter: m_keyboard-hide(); emit submitted(m_target-toPlainText()); break; default: break; } }m_target用QPointer更稳妥输入框被销毁时自动置空避免野指针。insertPlainText和textCursor().deletePreviousChar()是QLineEdit和QTextEdit都有的接口通过QTextCursor统一所以不用为两种控件写两套逻辑。showFor里根据输入框的mapToGlobal位置算键盘弹出坐标屏幕下半部分就往上弹避免被虚拟键盘自己挡住——这个判断不做在小屏设备上键盘会盖住正在输入的框用户看不见自己打了什么。4. 跑起来与接进业务从 demo 到实际界面的落地步骤4.1 先跑 demo验证环境和基本交互拿到资源别急着往业务里塞先跑 demo 确认环境没问题。步骤很直接用 Qt Creator 打开.pro选好套件编译运行或者命令行qmake make。跑起来应该看到一个带两三个输入框的窗口点输入框软键盘从下方弹出点字母能输入点 Del 能删点回车键盘收起。如果键盘弹不出来先查两件事一是InputContext有没有在main.cpp里通过qApp-installEventFilter(context)装上漏了这行焦点事件根本进不来二是键盘窗口的Qt::WindowFlags有没有设对设成Qt::Tool时在某些窗口管理器下不显示改成Qt::Popup或普通无边框窗口试试。如果按键点了没反应多半是setFocusPolicy(Qt::NoFocus)漏了焦点被按钮抢走m_target变成空。4.2 接进业务界面三行代码的集成方式集成到自己的工程核心就三步。第一步把src目录和库文件加进业务.pro第二步在main.cpp创建InputContext并安装事件过滤器第三步业务界面正常写QLineEdit不用做任何特殊处理// main.cpp int main(int argc, char *argv[]) { QApplication app(argc, argv); MainWindow w; auto *ctx new InputContext(w); // 父对象设为窗口随窗口销毁 app.installEventFilter(ctx); // 全局焦点跟踪 w.show(); return app.exec(); }InputContext构造时内部创建KeyboardWidget键盘是独立顶层窗口不占业务布局。业务代码完全无感输入框该怎么写还怎么写。这种「零侵入」是这套设计最大的价值——老项目改造时不用动几十个界面文件加三行就全站生效。4.3 参数调优位置、尺寸、动画实际设备上默认参数往往要调。键盘高度建议按屏幕高度的 35%40% 设太小按键点不准太大遮挡内容。弹出位置用输入框的全局坐标判断输入框中心在屏幕上半部键盘贴底弹在下半部键盘贴顶弹。动画用QPropertyAnimation做 150ms 的位移过渡比直接show()生硬弹出体验好很多但嵌入式低端板子上动画可能掉帧可以留个开关关掉。注意电阻屏没有多点触控按键尺寸别小于 40×40 像素否则误触率会高到没法用。这是硬件决定的不是代码能救的。5. 避坑与排查五个真实踩过的坑5.1 输入框失焦后键盘不消失现象点完输入框弹出键盘再点界面空白处键盘还挂在那儿。原因只监听了FocusIn没处理FocusOut而且点空白处焦点可能转移到某个不可输入的控件上。解决在事件过滤器里同时处理FocusOut判断新焦点对象是否仍是文本输入控件不是就延迟 100ms 隐藏键盘延迟是为了避免输入框之间切换时键盘闪一下。5.2 中文输入法场景下字符重复现象接了系统输入法后软键盘打的字母既进了输入法候选又直接进了输入框。原因软键盘直接调insertPlainText绕过了输入法框架两套输入路径打架。解决如果业务需要中文软键盘只负责产生按键事件通过QInputMethodEvent提交给 Qt 的输入法体系而不是直接改文本纯英文数字场景则关掉系统输入法避免冲突。5.3 长按删除删过头现象长按退格松手后还在继续删。原因setAutoRepeat的重复信号在松手后可能还有一两个排队事件。解决在KeyButton的mouseReleaseEvent里主动setAutoRepeat(false)再恢复或者用定时器自己控制重复节奏松手即停比依赖内置机制可控。5.4 键盘弹出位置算错现象多屏或高 DPI 设备上键盘弹到屏幕外面去了。原因用了控件相对坐标而不是全局坐标或者没考虑devicePixelRatio。解决统一用mapToGlobal转全局坐标再和QGuiApplication::primaryScreen()-availableGeometry()比较高 DPI 下坐标计算交给 Qt 的QScreen接口别自己乘缩放系数。5.5 编译过了运行崩在构造现象程序启动就崩堆栈指向键盘构造。原因KeyboardLayout里的静态数据表在全局构造阶段被访问此时 Qt 的某些单例还没初始化好。解决把静态数据改成函数内static局部变量第一次调用时初始化或者干脆在KeyboardWidget构造完成后再加载布局数据避开初始化顺序问题。6. 二次开发把软键盘改成你业务需要的样子这套代码真正值钱的地方在于它的可改造性几个方向可以直接上手。第一加业务专用键。工控场景常要「清空」「确认提交」「扫码触发」在KeyDef里加类型在onKeyPressed的switch里加分支发个自定义信号出去业务层接住做处理键盘模块本身不用改结构。第二换皮肤。所有按键样式集中在keyboard.qrc里的 qss改颜色、圆角、按下态背景不动 C 代码。第三做输入校验联动。InputContext拿到m_target后可以读它的validator或自定义属性比如某个框只允许数字就在showFor时自动切到数字页用户体验直接上一个台阶。改造后的验证方法我一般这么走先在 demo 里加一个和业务同类型的输入框把新键位、新皮肤、新校验都跑一遍再拿真机或同分辨率模拟器测触摸精度和弹出位置最后才合进业务工程。跳过 demo 直接上业务出问题时分不清是键盘的锅还是业务的锅排查成本翻倍。改造点改动位置验证方式新增功能键keyboardlayout.cppinputcontext.cppdemo 里点按看信号是否发出换皮肤resources/*.qss真机看对比度和触摸反馈输入类型联动inputcontext.cpp的showFor数字框自动切数字页多语言键位keyboardlayout.cpp加页切页不闪屏、不错位有个习惯是从那以后养成的任何软键盘改动我都先在 demo 工程里跑一遍完整输入流程——点框、打字、删字、切页、回车提交、点空白收起——六步全过才往业务里合。这套流程帮我挡掉过好几次「改了一个键位结果整页布局错乱」的低级问题。希望这份拆解帮到你拿到资源先跑 demo再按自己的业务往里加东西比从头写一套省太多时间。本文还有配套的精品资源点击获取