简介面向 Linux 平台 Qt 开发者的无线网络连接示例工程围绕 WIFI 扫描、列表展示、连接认证与密码输入等常见需求提供一套可参考的桌面端实现。项目通过系统调用与 wpa_supplicant 服务交互支持刷新搜索附近网络、最多显示 20 个 WIFI、连接 WEP/WPA2 等加密方式并在密码输入环节集成可弹出的软键盘适合课程设计、嵌入式界面原型及 Qt 网络模块学习。压缩包共 21 个文件约 2.94MB以 5 个 cpp 与 4 个 h 文件承载扫描、连接及界面逻辑3 个 ui 文件描述主界面与 WIFI 设置布局qrc、png、bmp 等提供图标和背景素材pro 文件与软键盘模块便于直接构建和复用。已有 1014 人学习。读者可据此梳理 Linux 下 Qt 调用外部服务完成无线管理的完整链路理解界面刷新、加密类型选择、密码软键盘联动及列表数量控制等实现方式并在此基础上替换业务界面或扩展连接状态提示、错误处理与配置保存形成可运行的 WIFI 连接工具。1. 一块触摸屏加一个 WiFi 列表这个 Qt 小工具的定位现场装好的设备只有一块七寸触摸屏没有鼠标也没有实体键盘客户需要自己选择 WiFi、输入密码、看到连接结果。在这个场景里Qt 自带的那套网络配置接口往往帮不上忙真正负责连接的是系统里的 wpa_supplicant而 Qt 要做的是把它的文本输出变成可以点击的列表再配一个能自动弹出的软键盘。这份源码解决的正是这三件事WiFi 搜索、连接状态显示、输入法弹窗。它适合做嵌入式面板、自助终端、工控屏的开发者也适合刚接手 Qt Widgets 项目、想把 QProcess 和焦点管理弄明白的人。整个工程不引入第三方库纯 Qt 加系统命令换块板子改两行配置就能跑。2. 工程结构与技术选型Qt Widgets 加 QProcess 两件套这个项目的技术组合非常朴素界面用 Qt Widgets 手写底层靠 QProcess 调系统命令。看着不够“现代”但在嵌入式面板这个场景里是最稳的路子不依赖额外的服务编译产物小出问题时能直接在命令行里复现同一条命令排查起来不会面对无法直接观察的状态。2.1 目录结构与模块划分工程按职责切成了四层UI 层不碰任何系统命令后端层不碰任何控件中间用一个数据结构串起来。这种切法的好处是换平台时只动core/一个目录界面代码一行不改。WifiPanel/ ├── WifiPanel.pro # qmake 工程Qt5.9 以上都能直接打开 ├── main.cpp # 启动、全局焦点监听、键盘单例 ├── core/ │ ├── wifibackend.h # 后端抽象接口UI 只认它 │ ├── wpabackend.h/.cpp # Linux 实现wpa_cli │ └── netshbackend.h/.cpp # Windows 实现netsh wlan ├── model/ │ ├── wifilistmodel.h/.cpp # 列表数据按信号强度降序 │ └── wifiitem.h # 一条热点的结构体 ├── ui/ │ ├── mainwindow.h/.cpp/.ui # 扫描按钮、热点列表、状态栏 │ ├── wificard.h/.cpp # 单条热点卡片含信号格与锁图标 │ └── passworddialog.* # 密码输入弹窗 └── input/ ├── softkeyboard.h/.cpp # 自绘软键盘 └── keyboard_layout.h # 按键布局表换键盘只动这个文件wifiitem.h里只有四个字段是整个工程里被引用最多的一个结构体struct WifiItem { QString ssid; // 热点名显示在卡片第一行 QString bssid; // 用于区分同名热点列表里不显示 int rssi -100; // dBm-30 极强-90 几乎连不上 bool secure false; // true 时卡片上挂一把锁点进去弹密码框 };字段顺序和后续解析代码强绑定rssi默认给 -100 而不是 0是为了让“没解析到信号强度”的热点自动排到列表最后不至于因为默认值 0 反而被当成满格信号顶到第一位。2.2 为什么不用 Qt 自带的网络配置接口QNetworkConfigurationManager这条路看起来最“Qt”实际用起来坑不少。Qt 5.15 起它已经被标记废弃Qt 6 直接移除一旦哪天升级 Qt 版本整个扫描模块就得重写。更麻烦的是它在 Linux 上的实现依赖 NetworkManager 的 bearer 插件而大量精简过的嵌入式镜像里只装了 wpa_supplicant根本没有 NetworkManagerallConfigurations()返回的是空列表界面上就是一个永远不会填满的空框。所以这里改成了最原始也最可控的做法QProcess 调wpa_cli拿回纯文本自己解析。代价是要自己处理异步和编码收益是任何一台能连 WiFi 的 Linux 设备上都能跑而且出问题时你在终端里敲同一条命令看到的就是程序看到的东西不用去猜 Qt 内部到底做了什么。软键盘同理。Qt 官方的虚拟键盘模块QT_IM_MODULEqtvirtualkeyboard功能完整但它要求编译 Qt 时带上该模块很多预编译的嵌入式 Qt 包并不包含。工程里干脆自己画一个键盘按键布局放在keyboard_layout.h的数组里改键位就是改几行数据。2.3 编译配置与运行时依赖.pro文件很干净只依赖 core、gui、widgets 三个模块没有 network 也没有 dbus# WifiPanel.pro —— 只依赖三个 Qt 模块交叉编译时不用同步裁剪 QT core gui widgets CONFIG c11 TARGET WifiPanel TEMPLATE app SOURCES main.cpp \ core/wpabackend.cpp \ model/wifilistmodel.cpp \ ui/mainwindow.cpp \ ui/wificard.cpp \ ui/passworddialog.cpp \ input/softkeyboard.cpp HEADERS core/wifibackend.h \ core/wpabackend.h \ model/wifiitem.h \ ui/mainwindow.h \ input/softkeyboard.h # 嵌入式板子上常用 eglfs 或 linuxfb没有窗口管理器 # 编译时不用写死运行时用 QT_QPA_PLATFORM 指定即可运行时依赖只有三样缺一样程序都会“能启动但扫不到任何热点”一是系统里wpa_supplicant服务正在跑二是wpa_cli可执行文件在 PATH 里三是网卡接口名对得上。接口名默认写wlan0很多板子叫wlp2s0或者wlan1程序启动时会先用ip link列一遍做校验。权限是另一个必须提前处理的问题。wpa_cli默认走/var/run/wpa_supplicant/wlan0这个控制 socket普通用户没有读写权限。常见做法是给运行账号加一条 sudoers 规则放行wpa_cli或者更干脆在wpa_supplicant.conf里加ctrl_interface_groupnetdev把运行账号塞进netdev组省掉每次弹密码的麻烦。提示如果用 eglfs 平台插件跑记得确认 Qt 编译时带了该插件不少预编译包只带 linuxfb直接跑会停在“This plugin does not support propagateSizeHints”的报错上。3. 核心链路拆解从一次扫描到一次连接成功整条链路上有四个关键节点触发扫描、拉取结果、解析成列表、发起连接最后再加一个状态回传把界面文案接上。这里的每一环都有“看起来能用、真机上就崩”的细节下面按执行顺序拆。3.1 扫描异步命令加轮询等待结果wpa_cli scan是个异步命令敲下去立刻返回OK但结果要等射频扫完一轮才有通常 1 到 3 秒。很多人第一版写成了“scan 完马上 scan_results”拿到的永远是上一次的缓存表现就是“第一次点扫描是空的点第二次才出东西”这个现象在真机上极其容易被误判成权限问题。正确的做法是先发扫描再用一个短周期定时器轮询结果等到结果非空才认为扫完了void WpaBackend::startScan() { // 1. 先触发一次扫描这个命令是异步的返回 OK 不代表扫完了 run({scan}); // 2. 300ms 轮询一次结果最多等 10 轮超时就当失败处理 auto *timer new QTimer(this); timer-setInterval(300); auto *tries new int(0); connect(timer, QTimer::timeout, this, [this, timer, tries] { if ((*tries) 10) { // 3 秒还没结果放弃 timer-stop(); timer-deleteLater(); delete tries; emit scanFailed(QStringLiteral(扫描超时检查网卡是否被占用)); return; } const QString raw run({scan_results}, 1500); const QListWifiItem list parseScanResults(raw); if (list.isEmpty()) return; // 结果为空说明还没扫完继续等 timer-stop(); timer-deleteLater(); delete tries; emit scanFinished(list); // 结果非空才算收敛 }); timer-start(); }run()是个薄封装负责起进程、等结束、取标准输出QString WpaBackend::run(const QStringList args, int timeoutMs) { QProcess p; // wpa_cli 的输出编码跟着系统 locale 走固定成 UTF-8 免得中文 SSID 变问号 QProcessEnvironment env QProcessEnvironment::systemEnvironment(); env.insert(LANG, C.UTF-8); p.setProcessEnvironment(env); p.start(wpa_cli, QStringList{-i, m_iface} args); if (!p.waitForFinished(timeoutMs)) { p.kill(); // 超时必须 kill否则进程越积越多 return QString(); } return QString::fromUtf8(p.readAllStandardOutput()); }-i后面跟的是网卡接口名这是整个后端里唯一必须和硬件对上号的参数。timeoutMs给 1500 是为了兜住“射频卡死”这种极端情况进程不 kill 掉的话下一次点击会在后台堆一串僵尸wpa_cli几分钟后整个界面就开始卡。超时上限设 10 轮是因为 2.4G 环境下扫一轮全信道最坏也就 2 秒多超过 3 秒基本可以判定是硬件问题而不是等待时间不够。3.2 结果解析把文本变成卡片列表scan_results返回的是标准的制表符分隔文本第一行是bssid / frequency / signal level / flags / ssid表头后面每行一条记录。解析时有两个容易踩的点同名的多 AP 会重复出现flags 字段里[ESS]并不代表开放网络。static QListWifiItem parseScanResults(const QString raw) { QHashQString, WifiItem best; // key 用 ssid同名只留信号最强的一条 const QStringList lines raw.split(\n, Qt::SkipEmptyParts); for (const QString line : lines) { const QStringList f line.split(\t); if (f.size() 5) continue; // 表头、Selected interface 都落在这 if (f.at(0).contains(:)) continue; // 保险起见再挡一次非记录行 WifiItem it; it.bssid f.at(0).trimmed(); it.rssi f.at(2).toInt(); // flags 形如 [WPA2-PSK-CCMP][ESS]开放的只有 [ESS]没有 WPA/WEP 字样 it.secure f.at(3).contains(WPA) || f.at(3).contains(WEP); it.ssid f.at(4).trimmed(); if (it.ssid.isEmpty()) continue; // 隐藏网络先不上列表 auto old best.find(it.ssid); if (old best.end() || it.rssi old-rssi) best.insert(it.ssid, it); // 同名热点保留信号更强的那台 } return best.values(); }f.size() 5这一行同时过滤掉了表头和Selected interface wlan0这类干扰输出比逐条判断前缀要省事。去重用的是按 ssid 建哈希表、保留 rssi 最大值的策略因为一个路由器挂 2.4G 和 5G 两个频段时会返回两条完全同名的记录列表里显示两个一模一样的卡片会让用户很困惑他分不清该点哪个。解析完交给WifiListModel之前要按rssi降序排一次界面上最上面永远是信号最好的那个用户扫完直接点第一个基本上就能连上。3.3 连接add_network 到 select_network连接一个从未连过的热点在 wpa_supplicant 的语义里是三步先申请一个 network 槽位再往槽位里写 ssid 和密码最后选中它。这三步任何一步失败都要把槽位删掉否则配置里会堆一堆残废的 network下次开机会依次重试表现就是“开机后 WiFi 图标转半天才连上”。bool WpaBackend::connectTo(const QString ssid, const QString psk) { const QString id run({add_network}).trimmed(); // 返回自增的 network id if (id.isEmpty()) return false; run({set_network, id, ssid, \ ssid \}); if (psk.isEmpty()) { run({set_network, id, key_mgmt, NONE}); // 开放网络必须显式声明 } else { // 密码要用双引号包住wpa_cli 靠这个区分“字符串参数”和“命令参数” run({set_network, id, psk, \ psk \}); } const QString ret run({select_network, id}).trimmed(); if (ret ! QLatin1String(OK)) { // 密码长度不对、ssid 不存在都会 FAIL run({remove_network, id}); run({save_config}); emit connectFailed(ssid, ret); return false; } m_currentId id; run({save_config}); // 写盘断电重启后能自动连回来 return true; }几个参数值得单独说。ssid和psk外面的双引号不是可有可无的装饰wpa_cli 在解析命令行时会把带空格或特殊字符的参数拆开SSID 里有个空格就整个错位。key_mgmt NONE对应的是开放网络如果漏掉这一行wpa_supplicant 会默认按 WPA 去握手连开放热点会一直卡在4WAY_HANDSHAKE状态。save_config会触发一次全量写盘在 SD 卡上频繁调用有磨损风险所以只在连接成功后调一次不要放在轮询里。3.4 状态回传把 wpa_state 翻译成界面文案连接发起之后状态是异步变的用一个 500ms 的定时器轮询status最省事比起上wpa_cli -a挂动作脚本要少很多进程管理的心智负担void WpaBackend::pollStatus() { const QString out run({status}, 800); QString state QStringLiteral(DISCONNECTED); for (const QString line : out.split(\n)) { if (line.startsWith(wpa_state)) state line.mid(10).trimmed(); if (line.startsWith(ssid)) m_ssid line.mid(5).trimmed(); if (line.startsWith(ip_address)) m_ip line.mid(11).trimmed(); } emit statusChanged(state, m_ssid, m_ip); }界面层拿到的state是原始字符串映射关系放在 UI 里做后端不掺和文案wpa_state界面显示界面动作SCANNING正在扫描…列表显示骨架占位禁用扫描按钮ASSOCIATING正在连接…密码框按钮置灰防重复提交4WAY_HANDSHAKE正在验证密码…同上此时不要提前判失败COMPLETED已连接显示 IP关闭密码框刷新顶部状态条DISCONNECTED未连接恢复列表可点允许重试INACTIVE网卡未就绪提示检查接口名不建议让用户自己重试4WAY_HANDSHAKE这个状态被单独拎出来是因为它在信号弱的时候能停留七八秒如果这时界面还显示“正在连接”并允许用户再点一次很容易触发并发连接最终两边都失败。4. 软键盘模块焦点驱动的输入方案密码框和 SSID 输入框在触摸屏上没法用物理键盘软键盘必须满足两个条件才算合格输入框一获得焦点就自动弹出失去焦点自动收起弹出的位置不能盖住正在输入的那个框。工程里用的是自绘 QWidget 加事件注入的方案比配置输入法插件更可控。4.1 自绘键盘的按键布局与事件注入键盘本身是个普通 QWidget按键矩形由一个静态数组生成改键位只改keyboard_layout.h// keyboard_layout.h —— 每行按键{显示文字, Qt 键值, 相对宽度权重} static const QListQListKeyDef kLayout { {{1,Qt::Key_1,1},{2,Qt::Key_2,1},{3,Qt::Key_3,1},{4,Qt::Key_4,1}, {5,Qt::Key_5,1},{6,Qt::Key_6,1},{7,Qt::Key_7,1},{8,Qt::Key_8,1}, {9,Qt::Key_9,1},{0,Qt::Key_0,1}}, {{q,Qt::Key_Q,1},{w,Qt::Key_W,1},{e,Qt::Key_E,1},/* … */}, {{大写,Qt::Key_CapsLock,1.5},{空格,Qt::Key_Space,5},{退格,Qt::Key_Backspace,1.5}} };按键事件的注入方式决定了这套键盘好不好用。有人喜欢直接edit-setText(edit-text() ch)拼字符串两三行代码就能跑但光标位置、选中替换、撤销栈全丢了用户点中间插一个字会发现光标跳到了末尾。正确做法是把按键包成 QKeyEvent 发给当前输入框让 QLineEdit 自己维护这些状态void SoftKeyboard::sendKey(int key, const QString text) { if (!m_target) return; // 退格、回车这类控制键不能带 text // 否则 QLineEdit 会先删一个字符、再把这个“文字”插回去 const QString t (key Qt::Key_Backspace || key Qt::Key_Return) ? QString() : text; QKeyEvent press(QEvent::KeyPress, key, Qt::NoModifier, t); QApplication::sendEvent(m_target, press); // 只发 press 就够了 if (key Qt::Key_Return) { // 回车即收键盘 emit committed(); hide(); } }只发KeyPress不发KeyRelease是有意为之QLineEdit 处理字符输入只看 press多发一个 release 在某些 Qt 版本上会触发两次自动补全。Qt::Key_Space的text要传一个真正的空格字符串 传空字符串的话空格键会变成“什么都没发生”。4.2 焦点跟踪什么时候弹出、什么时候收起键盘做成全局单例靠QApplication::focusChanged信号决定弹不弹。这个信号在main.cpp里只连一次所有输入框共享同一个键盘实例QObject::connect(qApp, QApplication::focusChanged, [](QWidget *, QWidget *now) { auto *edit qobject_castQLineEdit *(now); SoftKeyboard *kb SoftKeyboard::instance(); if (edit !edit-isReadOnly()) { kb-bindTo(edit); // 记住当前目标按键往这里打 kb-showAtBottom(); // 贴屏幕底部弹出 } else { kb-hide(); // 焦点跑到列表或按钮上就收起来 } });bindTo()里存的是裸指针这里必须处理一个常见崩溃输入框在键盘还开着的时候被deleteLater()销毁键盘再按键就是野指针。稳妥的做法是在bindTo里连一次QObject::destroyed信号把m_target置空。isReadOnly()的判断也必要否则用户点一个只读的展示框键盘弹出来却打不进字体验上很像“程序卡了”。showAtBottom()自己算坐标不依赖布局管理器void SoftKeyboard::showAtBottom() { QWidget *host parentWidget(); if (!host) return; const int h 260; // 键盘高度按屏幕 DPI 调 setGeometry(0, host-height() - h, host-width(), h); raise(); // 必须置顶不然被热点列表盖住 show(); }4.3 布局避让键盘不能盖住输入框键盘占了屏幕底部 260 像素密码框如果正好在列表下方弹出来就被压住了用户一边打字一边看不到自己输的是什么。工程里把内容放进QScrollArea键盘弹出后主动把焦点控件滚到可视区void MainWindow::ensureVisible(QWidget *w) { QScrollArea *area ui-scrollArea; // 传控件中心点坐标Y 方向留 40 像素余量避免控件刚好贴在键盘边缘 const QRect r w-geometry(); area-ensureVisible(r.center().x(), r.center().y(), 0, 40); }在 800×480 这种小屏上h不要死磕 260按屏幕高度取 45% 更合理横竖屏切换时也不会突然把整个界面挤没。5. 排查与避坑五个真机上翻车的现场下面这些都在真设备上遇到过共同点是模拟器上完全正常、装到板子上才暴露。5.1 扫描与连接类问题现象程序启动正常点“扫描”后列表永远是空的命令行敲wpa_cli scan_results却有数据。原因网卡接口名写死成了wlan0而板子上实际叫wlp1s0wpa_cli -i wlan0一直在连一个不存在的控制 socket返回的是空字符串而不是报错。解决启动时先跑一次ip -o link show把结果里所有非lo的接口名取出来做匹配找不到就退回到手工配置。别指望用QNetworkInterface::allInterfaces()反查无线接口在部分驱动下 flags 里不带IsWireless。现象第一次连接成功断开后第二次连同一个热点一直卡在4WAY_HANDSHAKE直到超时。原因连接失败时没有清理刚add_network出来的槽位配置里残留着旧密码wpa_supplicant 优先用了那个旧槽位。解决在select_network返回非 OK 的分支里补上remove_network加save_config并且程序启动时用list_networks清一遍所有历史槽位只保留当前要用的那个。现象中文 SSID 的热点在列表里显示成方块或者问号点进去连接必失败。原因进程环境继承了系统的LANG很多精简镜像里是LANG空值wpa_cli输出的编码于是跟着 C locale 走读出来再fromUtf8就散了。解决在run()里显式往QProcessEnvironment塞LANGC.UTF-8读输出统一fromUtf8。这一条看似玄学实际是最容易复现的编码坑。5.2 界面与输入类问题现象触摸屏上点密码框键盘弹出来了但按键没反应点了好几下才偶尔打进去一个字。原因键盘 QWidget 只重写了mousePressEvent而触摸屏驱动在部分配置下派发的是QTouchEventQt 没做合成mousePressEvent压根不触发。解决给键盘控件设setAttribute(Qt::WA_AcceptTouchEvents)并重写event()拦QEvent::TouchBegin把它转换成自己的按键命中判断。这一条改完之后触摸响应从“时灵时不灵”变成了跟鼠标完全一致。现象键盘弹出后输入框被盖住用户看不见自己输的密码输完点确定还报密码错误。原因只做了showAtBottom()没做滚动避让输入框在QScrollArea里的位置没变。解决在键盘的showEvent里回调主窗口的ensureVisible(m_target)把当前焦点控件滚进可视区。同时在密码框下面预留 40 像素的底部边距滚动到底时也不会贴边。6. 二次开发把后端抽成接口换平台只改一个类第一次给这套代码加 Windows 支持时我把#ifdef Q_OS_WIN直接塞进了 UI 的槽函数里三个月后再看那段代码已经没法读了。后来重构成一个纯虚接口UI 层只认接口具体实现按平台在工厂里选// wifibackend.h —— 所有平台实现这一个接口界面层不出现任何平台宏 class IWifiBackend : public QObject { Q_OBJECT public: explicit IWifiBackend(QObject *parent nullptr) : QObject(parent) {} virtual void startScan() 0; virtual bool connectTo(const QString ssid, const QString psk) 0; virtual void disconnectFrom(const QString ssid) 0; virtual QString backendName() const 0; // 用于状态栏显示当前后端 signals: void scanFinished(const QListWifiItem items); void scanFailed(const QString reason); void statusChanged(const QString state, const QString ssid, const QString ip); }; // 工厂换平台只动这几行UI 代码一行不改 static IWifiBackend *createBackend(QObject *parent) { #ifdef Q_OS_WIN return new NetshBackend(parent); // netsh wlan show networks modebssid #else return new WpaBackend(parent); #endif }Windows 后端的实现思路和 Linux 完全不同值得提前知道netsh wlan show networks modebssid只能扫连接必须先用netsh wlan add profile filenamexxx.xml导入一个描述网络的 XML 配置再netsh wlan connect name...。所以那个后端里多了一步“用 SSID 和密码拼 XML 写进临时目录”密码字段是明文文件权限记得设成只读用完立刻删掉。改造时有几个验证顺序值得记一下先只跑后端在main.cpp里手写几行连接scanFinished把结果qDebug出来确认能扫到再往上接界面然后单独测connectTo用错误的密码跑一遍确认失败分支真的会清理槽位最后才接界面重点看快速连点扫描按钮时会不会并发起多个进程。跳过前两步直接调界面出了问题你分不清是后端解析错了还是信号槽没连上。一个具体的技巧在WpaBackend里加一个环境变量开关WIFI_DEBUG1打开后把每一行wpa_cli命令和返回内容都打到日志里。我在现场排查时全靠这个开关只要用户把日志拷回来基本上一眼能定位是密码错、信号弱还是接口名不对。记得日志里的密码字段要做一次掩码替换别把用户密码原样写进文件。从那以后我每次接新的嵌入式板子都会先在终端里手敲一遍wpa_cli -i xxx scan、scan_results、status确认三条命令的输出格式跟程序里假设的一致再动代码。看起来多花五分钟能省掉后面半小时盯着空列表猜原因的功夫。希望帮到你。本文还有配套的精品资源点击获取
简介面向 Linux 平台 Qt 开发者的无线网络连接示例工程围绕 WIFI 扫描、列表展示、连接认证与密码输入等常见需求提供一套可参考的桌面端实现。项目通过系统调用与 wpa_supplicant 服务交互支持刷新搜索附近网络、最多显示 20 个 WIFI、连接 WEP/WPA2 等加密方式并在密码输入环节集成可弹出的软键盘适合课程设计、嵌入式界面原型及 Qt 网络模块学习。压缩包共 21 个文件约 2.94MB以 5 个 cpp 与 4 个 h 文件承载扫描、连接及界面逻辑3 个 ui 文件描述主界面与 WIFI 设置布局qrc、png、bmp 等提供图标和背景素材pro 文件与软键盘模块便于直接构建和复用。已有 1014 人学习。读者可据此梳理 Linux 下 Qt 调用外部服务完成无线管理的完整链路理解界面刷新、加密类型选择、密码软键盘联动及列表数量控制等实现方式并在此基础上替换业务界面或扩展连接状态提示、错误处理与配置保存形成可运行的 WIFI 连接工具。1. 一块触摸屏加一个 WiFi 列表这个 Qt 小工具的定位现场装好的设备只有一块七寸触摸屏没有鼠标也没有实体键盘客户需要自己选择 WiFi、输入密码、看到连接结果。在这个场景里Qt 自带的那套网络配置接口往往帮不上忙真正负责连接的是系统里的 wpa_supplicant而 Qt 要做的是把它的文本输出变成可以点击的列表再配一个能自动弹出的软键盘。这份源码解决的正是这三件事WiFi 搜索、连接状态显示、输入法弹窗。它适合做嵌入式面板、自助终端、工控屏的开发者也适合刚接手 Qt Widgets 项目、想把 QProcess 和焦点管理弄明白的人。整个工程不引入第三方库纯 Qt 加系统命令换块板子改两行配置就能跑。2. 工程结构与技术选型Qt Widgets 加 QProcess 两件套这个项目的技术组合非常朴素界面用 Qt Widgets 手写底层靠 QProcess 调系统命令。看着不够“现代”但在嵌入式面板这个场景里是最稳的路子不依赖额外的服务编译产物小出问题时能直接在命令行里复现同一条命令排查起来不会面对无法直接观察的状态。2.1 目录结构与模块划分工程按职责切成了四层UI 层不碰任何系统命令后端层不碰任何控件中间用一个数据结构串起来。这种切法的好处是换平台时只动core/一个目录界面代码一行不改。WifiPanel/ ├── WifiPanel.pro # qmake 工程Qt5.9 以上都能直接打开 ├── main.cpp # 启动、全局焦点监听、键盘单例 ├── core/ │ ├── wifibackend.h # 后端抽象接口UI 只认它 │ ├── wpabackend.h/.cpp # Linux 实现wpa_cli │ └── netshbackend.h/.cpp # Windows 实现netsh wlan ├── model/ │ ├── wifilistmodel.h/.cpp # 列表数据按信号强度降序 │ └── wifiitem.h # 一条热点的结构体 ├── ui/ │ ├── mainwindow.h/.cpp/.ui # 扫描按钮、热点列表、状态栏 │ ├── wificard.h/.cpp # 单条热点卡片含信号格与锁图标 │ └── passworddialog.* # 密码输入弹窗 └── input/ ├── softkeyboard.h/.cpp # 自绘软键盘 └── keyboard_layout.h # 按键布局表换键盘只动这个文件wifiitem.h里只有四个字段是整个工程里被引用最多的一个结构体struct WifiItem { QString ssid; // 热点名显示在卡片第一行 QString bssid; // 用于区分同名热点列表里不显示 int rssi -100; // dBm-30 极强-90 几乎连不上 bool secure false; // true 时卡片上挂一把锁点进去弹密码框 };字段顺序和后续解析代码强绑定rssi默认给 -100 而不是 0是为了让“没解析到信号强度”的热点自动排到列表最后不至于因为默认值 0 反而被当成满格信号顶到第一位。2.2 为什么不用 Qt 自带的网络配置接口QNetworkConfigurationManager这条路看起来最“Qt”实际用起来坑不少。Qt 5.15 起它已经被标记废弃Qt 6 直接移除一旦哪天升级 Qt 版本整个扫描模块就得重写。更麻烦的是它在 Linux 上的实现依赖 NetworkManager 的 bearer 插件而大量精简过的嵌入式镜像里只装了 wpa_supplicant根本没有 NetworkManagerallConfigurations()返回的是空列表界面上就是一个永远不会填满的空框。所以这里改成了最原始也最可控的做法QProcess 调wpa_cli拿回纯文本自己解析。代价是要自己处理异步和编码收益是任何一台能连 WiFi 的 Linux 设备上都能跑而且出问题时你在终端里敲同一条命令看到的就是程序看到的东西不用去猜 Qt 内部到底做了什么。软键盘同理。Qt 官方的虚拟键盘模块QT_IM_MODULEqtvirtualkeyboard功能完整但它要求编译 Qt 时带上该模块很多预编译的嵌入式 Qt 包并不包含。工程里干脆自己画一个键盘按键布局放在keyboard_layout.h的数组里改键位就是改几行数据。2.3 编译配置与运行时依赖.pro文件很干净只依赖 core、gui、widgets 三个模块没有 network 也没有 dbus# WifiPanel.pro —— 只依赖三个 Qt 模块交叉编译时不用同步裁剪 QT core gui widgets CONFIG c11 TARGET WifiPanel TEMPLATE app SOURCES main.cpp \ core/wpabackend.cpp \ model/wifilistmodel.cpp \ ui/mainwindow.cpp \ ui/wificard.cpp \ ui/passworddialog.cpp \ input/softkeyboard.cpp HEADERS core/wifibackend.h \ core/wpabackend.h \ model/wifiitem.h \ ui/mainwindow.h \ input/softkeyboard.h # 嵌入式板子上常用 eglfs 或 linuxfb没有窗口管理器 # 编译时不用写死运行时用 QT_QPA_PLATFORM 指定即可运行时依赖只有三样缺一样程序都会“能启动但扫不到任何热点”一是系统里wpa_supplicant服务正在跑二是wpa_cli可执行文件在 PATH 里三是网卡接口名对得上。接口名默认写wlan0很多板子叫wlp2s0或者wlan1程序启动时会先用ip link列一遍做校验。权限是另一个必须提前处理的问题。wpa_cli默认走/var/run/wpa_supplicant/wlan0这个控制 socket普通用户没有读写权限。常见做法是给运行账号加一条 sudoers 规则放行wpa_cli或者更干脆在wpa_supplicant.conf里加ctrl_interface_groupnetdev把运行账号塞进netdev组省掉每次弹密码的麻烦。提示如果用 eglfs 平台插件跑记得确认 Qt 编译时带了该插件不少预编译包只带 linuxfb直接跑会停在“This plugin does not support propagateSizeHints”的报错上。3. 核心链路拆解从一次扫描到一次连接成功整条链路上有四个关键节点触发扫描、拉取结果、解析成列表、发起连接最后再加一个状态回传把界面文案接上。这里的每一环都有“看起来能用、真机上就崩”的细节下面按执行顺序拆。3.1 扫描异步命令加轮询等待结果wpa_cli scan是个异步命令敲下去立刻返回OK但结果要等射频扫完一轮才有通常 1 到 3 秒。很多人第一版写成了“scan 完马上 scan_results”拿到的永远是上一次的缓存表现就是“第一次点扫描是空的点第二次才出东西”这个现象在真机上极其容易被误判成权限问题。正确的做法是先发扫描再用一个短周期定时器轮询结果等到结果非空才认为扫完了void WpaBackend::startScan() { // 1. 先触发一次扫描这个命令是异步的返回 OK 不代表扫完了 run({scan}); // 2. 300ms 轮询一次结果最多等 10 轮超时就当失败处理 auto *timer new QTimer(this); timer-setInterval(300); auto *tries new int(0); connect(timer, QTimer::timeout, this, [this, timer, tries] { if ((*tries) 10) { // 3 秒还没结果放弃 timer-stop(); timer-deleteLater(); delete tries; emit scanFailed(QStringLiteral(扫描超时检查网卡是否被占用)); return; } const QString raw run({scan_results}, 1500); const QListWifiItem list parseScanResults(raw); if (list.isEmpty()) return; // 结果为空说明还没扫完继续等 timer-stop(); timer-deleteLater(); delete tries; emit scanFinished(list); // 结果非空才算收敛 }); timer-start(); }run()是个薄封装负责起进程、等结束、取标准输出QString WpaBackend::run(const QStringList args, int timeoutMs) { QProcess p; // wpa_cli 的输出编码跟着系统 locale 走固定成 UTF-8 免得中文 SSID 变问号 QProcessEnvironment env QProcessEnvironment::systemEnvironment(); env.insert(LANG, C.UTF-8); p.setProcessEnvironment(env); p.start(wpa_cli, QStringList{-i, m_iface} args); if (!p.waitForFinished(timeoutMs)) { p.kill(); // 超时必须 kill否则进程越积越多 return QString(); } return QString::fromUtf8(p.readAllStandardOutput()); }-i后面跟的是网卡接口名这是整个后端里唯一必须和硬件对上号的参数。timeoutMs给 1500 是为了兜住“射频卡死”这种极端情况进程不 kill 掉的话下一次点击会在后台堆一串僵尸wpa_cli几分钟后整个界面就开始卡。超时上限设 10 轮是因为 2.4G 环境下扫一轮全信道最坏也就 2 秒多超过 3 秒基本可以判定是硬件问题而不是等待时间不够。3.2 结果解析把文本变成卡片列表scan_results返回的是标准的制表符分隔文本第一行是bssid / frequency / signal level / flags / ssid表头后面每行一条记录。解析时有两个容易踩的点同名的多 AP 会重复出现flags 字段里[ESS]并不代表开放网络。static QListWifiItem parseScanResults(const QString raw) { QHashQString, WifiItem best; // key 用 ssid同名只留信号最强的一条 const QStringList lines raw.split(\n, Qt::SkipEmptyParts); for (const QString line : lines) { const QStringList f line.split(\t); if (f.size() 5) continue; // 表头、Selected interface 都落在这 if (f.at(0).contains(:)) continue; // 保险起见再挡一次非记录行 WifiItem it; it.bssid f.at(0).trimmed(); it.rssi f.at(2).toInt(); // flags 形如 [WPA2-PSK-CCMP][ESS]开放的只有 [ESS]没有 WPA/WEP 字样 it.secure f.at(3).contains(WPA) || f.at(3).contains(WEP); it.ssid f.at(4).trimmed(); if (it.ssid.isEmpty()) continue; // 隐藏网络先不上列表 auto old best.find(it.ssid); if (old best.end() || it.rssi old-rssi) best.insert(it.ssid, it); // 同名热点保留信号更强的那台 } return best.values(); }f.size() 5这一行同时过滤掉了表头和Selected interface wlan0这类干扰输出比逐条判断前缀要省事。去重用的是按 ssid 建哈希表、保留 rssi 最大值的策略因为一个路由器挂 2.4G 和 5G 两个频段时会返回两条完全同名的记录列表里显示两个一模一样的卡片会让用户很困惑他分不清该点哪个。解析完交给WifiListModel之前要按rssi降序排一次界面上最上面永远是信号最好的那个用户扫完直接点第一个基本上就能连上。3.3 连接add_network 到 select_network连接一个从未连过的热点在 wpa_supplicant 的语义里是三步先申请一个 network 槽位再往槽位里写 ssid 和密码最后选中它。这三步任何一步失败都要把槽位删掉否则配置里会堆一堆残废的 network下次开机会依次重试表现就是“开机后 WiFi 图标转半天才连上”。bool WpaBackend::connectTo(const QString ssid, const QString psk) { const QString id run({add_network}).trimmed(); // 返回自增的 network id if (id.isEmpty()) return false; run({set_network, id, ssid, \ ssid \}); if (psk.isEmpty()) { run({set_network, id, key_mgmt, NONE}); // 开放网络必须显式声明 } else { // 密码要用双引号包住wpa_cli 靠这个区分“字符串参数”和“命令参数” run({set_network, id, psk, \ psk \}); } const QString ret run({select_network, id}).trimmed(); if (ret ! QLatin1String(OK)) { // 密码长度不对、ssid 不存在都会 FAIL run({remove_network, id}); run({save_config}); emit connectFailed(ssid, ret); return false; } m_currentId id; run({save_config}); // 写盘断电重启后能自动连回来 return true; }几个参数值得单独说。ssid和psk外面的双引号不是可有可无的装饰wpa_cli 在解析命令行时会把带空格或特殊字符的参数拆开SSID 里有个空格就整个错位。key_mgmt NONE对应的是开放网络如果漏掉这一行wpa_supplicant 会默认按 WPA 去握手连开放热点会一直卡在4WAY_HANDSHAKE状态。save_config会触发一次全量写盘在 SD 卡上频繁调用有磨损风险所以只在连接成功后调一次不要放在轮询里。3.4 状态回传把 wpa_state 翻译成界面文案连接发起之后状态是异步变的用一个 500ms 的定时器轮询status最省事比起上wpa_cli -a挂动作脚本要少很多进程管理的心智负担void WpaBackend::pollStatus() { const QString out run({status}, 800); QString state QStringLiteral(DISCONNECTED); for (const QString line : out.split(\n)) { if (line.startsWith(wpa_state)) state line.mid(10).trimmed(); if (line.startsWith(ssid)) m_ssid line.mid(5).trimmed(); if (line.startsWith(ip_address)) m_ip line.mid(11).trimmed(); } emit statusChanged(state, m_ssid, m_ip); }界面层拿到的state是原始字符串映射关系放在 UI 里做后端不掺和文案wpa_state界面显示界面动作SCANNING正在扫描…列表显示骨架占位禁用扫描按钮ASSOCIATING正在连接…密码框按钮置灰防重复提交4WAY_HANDSHAKE正在验证密码…同上此时不要提前判失败COMPLETED已连接显示 IP关闭密码框刷新顶部状态条DISCONNECTED未连接恢复列表可点允许重试INACTIVE网卡未就绪提示检查接口名不建议让用户自己重试4WAY_HANDSHAKE这个状态被单独拎出来是因为它在信号弱的时候能停留七八秒如果这时界面还显示“正在连接”并允许用户再点一次很容易触发并发连接最终两边都失败。4. 软键盘模块焦点驱动的输入方案密码框和 SSID 输入框在触摸屏上没法用物理键盘软键盘必须满足两个条件才算合格输入框一获得焦点就自动弹出失去焦点自动收起弹出的位置不能盖住正在输入的那个框。工程里用的是自绘 QWidget 加事件注入的方案比配置输入法插件更可控。4.1 自绘键盘的按键布局与事件注入键盘本身是个普通 QWidget按键矩形由一个静态数组生成改键位只改keyboard_layout.h// keyboard_layout.h —— 每行按键{显示文字, Qt 键值, 相对宽度权重} static const QListQListKeyDef kLayout { {{1,Qt::Key_1,1},{2,Qt::Key_2,1},{3,Qt::Key_3,1},{4,Qt::Key_4,1}, {5,Qt::Key_5,1},{6,Qt::Key_6,1},{7,Qt::Key_7,1},{8,Qt::Key_8,1}, {9,Qt::Key_9,1},{0,Qt::Key_0,1}}, {{q,Qt::Key_Q,1},{w,Qt::Key_W,1},{e,Qt::Key_E,1},/* … */}, {{大写,Qt::Key_CapsLock,1.5},{空格,Qt::Key_Space,5},{退格,Qt::Key_Backspace,1.5}} };按键事件的注入方式决定了这套键盘好不好用。有人喜欢直接edit-setText(edit-text() ch)拼字符串两三行代码就能跑但光标位置、选中替换、撤销栈全丢了用户点中间插一个字会发现光标跳到了末尾。正确做法是把按键包成 QKeyEvent 发给当前输入框让 QLineEdit 自己维护这些状态void SoftKeyboard::sendKey(int key, const QString text) { if (!m_target) return; // 退格、回车这类控制键不能带 text // 否则 QLineEdit 会先删一个字符、再把这个“文字”插回去 const QString t (key Qt::Key_Backspace || key Qt::Key_Return) ? QString() : text; QKeyEvent press(QEvent::KeyPress, key, Qt::NoModifier, t); QApplication::sendEvent(m_target, press); // 只发 press 就够了 if (key Qt::Key_Return) { // 回车即收键盘 emit committed(); hide(); } }只发KeyPress不发KeyRelease是有意为之QLineEdit 处理字符输入只看 press多发一个 release 在某些 Qt 版本上会触发两次自动补全。Qt::Key_Space的text要传一个真正的空格字符串 传空字符串的话空格键会变成“什么都没发生”。4.2 焦点跟踪什么时候弹出、什么时候收起键盘做成全局单例靠QApplication::focusChanged信号决定弹不弹。这个信号在main.cpp里只连一次所有输入框共享同一个键盘实例QObject::connect(qApp, QApplication::focusChanged, [](QWidget *, QWidget *now) { auto *edit qobject_castQLineEdit *(now); SoftKeyboard *kb SoftKeyboard::instance(); if (edit !edit-isReadOnly()) { kb-bindTo(edit); // 记住当前目标按键往这里打 kb-showAtBottom(); // 贴屏幕底部弹出 } else { kb-hide(); // 焦点跑到列表或按钮上就收起来 } });bindTo()里存的是裸指针这里必须处理一个常见崩溃输入框在键盘还开着的时候被deleteLater()销毁键盘再按键就是野指针。稳妥的做法是在bindTo里连一次QObject::destroyed信号把m_target置空。isReadOnly()的判断也必要否则用户点一个只读的展示框键盘弹出来却打不进字体验上很像“程序卡了”。showAtBottom()自己算坐标不依赖布局管理器void SoftKeyboard::showAtBottom() { QWidget *host parentWidget(); if (!host) return; const int h 260; // 键盘高度按屏幕 DPI 调 setGeometry(0, host-height() - h, host-width(), h); raise(); // 必须置顶不然被热点列表盖住 show(); }4.3 布局避让键盘不能盖住输入框键盘占了屏幕底部 260 像素密码框如果正好在列表下方弹出来就被压住了用户一边打字一边看不到自己输的是什么。工程里把内容放进QScrollArea键盘弹出后主动把焦点控件滚到可视区void MainWindow::ensureVisible(QWidget *w) { QScrollArea *area ui-scrollArea; // 传控件中心点坐标Y 方向留 40 像素余量避免控件刚好贴在键盘边缘 const QRect r w-geometry(); area-ensureVisible(r.center().x(), r.center().y(), 0, 40); }在 800×480 这种小屏上h不要死磕 260按屏幕高度取 45% 更合理横竖屏切换时也不会突然把整个界面挤没。5. 排查与避坑五个真机上翻车的现场下面这些都在真设备上遇到过共同点是模拟器上完全正常、装到板子上才暴露。5.1 扫描与连接类问题现象程序启动正常点“扫描”后列表永远是空的命令行敲wpa_cli scan_results却有数据。原因网卡接口名写死成了wlan0而板子上实际叫wlp1s0wpa_cli -i wlan0一直在连一个不存在的控制 socket返回的是空字符串而不是报错。解决启动时先跑一次ip -o link show把结果里所有非lo的接口名取出来做匹配找不到就退回到手工配置。别指望用QNetworkInterface::allInterfaces()反查无线接口在部分驱动下 flags 里不带IsWireless。现象第一次连接成功断开后第二次连同一个热点一直卡在4WAY_HANDSHAKE直到超时。原因连接失败时没有清理刚add_network出来的槽位配置里残留着旧密码wpa_supplicant 优先用了那个旧槽位。解决在select_network返回非 OK 的分支里补上remove_network加save_config并且程序启动时用list_networks清一遍所有历史槽位只保留当前要用的那个。现象中文 SSID 的热点在列表里显示成方块或者问号点进去连接必失败。原因进程环境继承了系统的LANG很多精简镜像里是LANG空值wpa_cli输出的编码于是跟着 C locale 走读出来再fromUtf8就散了。解决在run()里显式往QProcessEnvironment塞LANGC.UTF-8读输出统一fromUtf8。这一条看似玄学实际是最容易复现的编码坑。5.2 界面与输入类问题现象触摸屏上点密码框键盘弹出来了但按键没反应点了好几下才偶尔打进去一个字。原因键盘 QWidget 只重写了mousePressEvent而触摸屏驱动在部分配置下派发的是QTouchEventQt 没做合成mousePressEvent压根不触发。解决给键盘控件设setAttribute(Qt::WA_AcceptTouchEvents)并重写event()拦QEvent::TouchBegin把它转换成自己的按键命中判断。这一条改完之后触摸响应从“时灵时不灵”变成了跟鼠标完全一致。现象键盘弹出后输入框被盖住用户看不见自己输的密码输完点确定还报密码错误。原因只做了showAtBottom()没做滚动避让输入框在QScrollArea里的位置没变。解决在键盘的showEvent里回调主窗口的ensureVisible(m_target)把当前焦点控件滚进可视区。同时在密码框下面预留 40 像素的底部边距滚动到底时也不会贴边。6. 二次开发把后端抽成接口换平台只改一个类第一次给这套代码加 Windows 支持时我把#ifdef Q_OS_WIN直接塞进了 UI 的槽函数里三个月后再看那段代码已经没法读了。后来重构成一个纯虚接口UI 层只认接口具体实现按平台在工厂里选// wifibackend.h —— 所有平台实现这一个接口界面层不出现任何平台宏 class IWifiBackend : public QObject { Q_OBJECT public: explicit IWifiBackend(QObject *parent nullptr) : QObject(parent) {} virtual void startScan() 0; virtual bool connectTo(const QString ssid, const QString psk) 0; virtual void disconnectFrom(const QString ssid) 0; virtual QString backendName() const 0; // 用于状态栏显示当前后端 signals: void scanFinished(const QListWifiItem items); void scanFailed(const QString reason); void statusChanged(const QString state, const QString ssid, const QString ip); }; // 工厂换平台只动这几行UI 代码一行不改 static IWifiBackend *createBackend(QObject *parent) { #ifdef Q_OS_WIN return new NetshBackend(parent); // netsh wlan show networks modebssid #else return new WpaBackend(parent); #endif }Windows 后端的实现思路和 Linux 完全不同值得提前知道netsh wlan show networks modebssid只能扫连接必须先用netsh wlan add profile filenamexxx.xml导入一个描述网络的 XML 配置再netsh wlan connect name...。所以那个后端里多了一步“用 SSID 和密码拼 XML 写进临时目录”密码字段是明文文件权限记得设成只读用完立刻删掉。改造时有几个验证顺序值得记一下先只跑后端在main.cpp里手写几行连接scanFinished把结果qDebug出来确认能扫到再往上接界面然后单独测connectTo用错误的密码跑一遍确认失败分支真的会清理槽位最后才接界面重点看快速连点扫描按钮时会不会并发起多个进程。跳过前两步直接调界面出了问题你分不清是后端解析错了还是信号槽没连上。一个具体的技巧在WpaBackend里加一个环境变量开关WIFI_DEBUG1打开后把每一行wpa_cli命令和返回内容都打到日志里。我在现场排查时全靠这个开关只要用户把日志拷回来基本上一眼能定位是密码错、信号弱还是接口名不对。记得日志里的密码字段要做一次掩码替换别把用户密码原样写进文件。从那以后我每次接新的嵌入式板子都会先在终端里手敲一遍wpa_cli -i xxx scan、scan_results、status确认三条命令的输出格式跟程序里假设的一致再动代码。看起来多花五分钟能省掉后面半小时盯着空列表猜原因的功夫。希望帮到你。本文还有配套的精品资源点击获取
