1. QT 全屏显示与鼠标指针隐藏到底难在哪如果你正在做 QT 桌面程序尤其是工控面板、自助终端、展厅大屏这类场景大概率会遇到两个很烦人的问题窗口怎么都铺不满屏幕鼠标指针像个钉子户一样赖在画面上不走。这两个问题单独看都不复杂但叠在一起、再放到不同平台X11、Embedded、Windows上跑坑就一个接一个。先说全屏。很多人第一反应是showFullScreen()这函数确实好用但它有个硬性前提调用它的 widget 必须是顶级窗口。如果你的窗口是嵌在父窗口里的子窗口Qt::SubWindow调了也白调界面纹丝不动。这时候就得先改窗口标志位把它变成独立窗口再全屏。另一个常见误区是直接move()resize()想手动铺满结果发现对子窗口完全无效——因为子窗口的几何位置是由父窗口的布局系统管的你不先把它变成窗口模式move 和 resize 就是空操作。再说鼠标指针。触摸屏设备上鼠标指针不仅没用还会挡住 UI 元素甚至误触。隐藏它的方法有好几种但每种都有适用边界。-nomouse启动参数最省事但代价是触摸事件也可能一起失效等于把输入废了。setCursor(Qt::BlankCursor)只对当前 widget 生效鼠标一移出这个控件就又冒出来了。QApplication::setOverrideCursor()是全局的但有个尴尬的细节程序刚启动时指针还在得等你在触摸屏上点一下、动一下它才消失。真正从启动到退出全程不出现指针的是QWSServer::setCursorVisible(false)但它是 QT Embedded 专属你在 X11 环境下编译会直接报undefined reference to QWSServer::setCursorVisible(bool)。所以这篇文章要解决的不是“知道有这些 API”而是“在真实开发环境里怎么把它们配好、编译过、跑起来”。我会结合 TaoToken 统一 Key 通道把开发环境的接入参数、可复制的 QT 配置代码、编译运行后的验证动作串成一条完整链路。你跟着做能直接在自己的工程里落地全屏 无指针的桌面交互效果。适合谁看正在用 QT 做桌面端/嵌入式端 UI 的开发者尤其是需要全屏展示、触摸交互、又不想被鼠标指针干扰的场景。如果你只是写个普通窗口应用这篇可能有点重但全屏和指针这两块的知识点你迟早用得上。TaoToken 在这里的角色是统一 Key/API 通道。开发调试阶段你可能需要调用模型能力做界面文案生成、日志分析、或者辅助排查编译错误TaoToken 让你用一个 Key 走通多个模型不用在多个平台之间来回切。下面我会先讲接入再讲 QT 配置最后讲验证和排错。2. TaoToken 统一 Key 通道接入前置准备在动手改 QT 代码之前先把开发环境的 API 通道配好。这一步不是必须的——你完全可以只改 QT 代码——但如果你想让调试过程更顺比如用模型帮你分析编译报错、生成测试用例、或者做界面文本的多语言转换那先把 TaoToken 接上会省很多事。TaoToken 的核心价值是统一 Key。你不需要为每个模型单独申请账号、单独管 Key一个 Key 就能在多个模型之间切换。对于 QT 桌面开发这种可能涉及代码生成、报错分析、文档整理的场景统一通道能明显减少环境切换的成本。接入需要三个东西Base URL、API Key、Model ID。Base URL 是https://taotoken.net/api注意这个地址不带任何查询参数是纯 API 端点。API Key 需要你去控制台创建创建入口在https://taotoken.net/console/api-keys。Model ID 根据你要用的模型填比如你想用 Claude 系列做代码分析就填对应的模型标识。我建议你在项目根目录建一个.env文件或者配置头文件把这三个值集中管理不要硬编码在源码里。QT 项目可以用qmake的DEFINES或者 CMake 的target_compile_definitions把配置注入进去。下面是一个.env的示例结构TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_API_KEYsk-你的实际Key TAOTOKEN_MODEL_ID你的模型ID如果你用的是 QT Creator可以在项目的构建设置里加环境变量或者直接在代码里读qgetenv。这样做的目的是调试阶段改 Key 不用重新编译换模型也不用动源码。另外如果你要做的是长期编码或者 Agent 类的任务比如让模型持续帮你 review QT 代码、自动生成测试可以考虑 Coding Plan入口在https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcode_plan。这个适合需要反复调用、长期跑的场景比单次对话更划算。如果你只是想先验证模型能不能通可以用模型对话入口https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodel_chat发一条消息看看返回是否正常。验证通过后再往 QT 工程里集成。接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc里面有完整的参数说明和示例。我建议你先花五分钟把文档过一遍尤其是错误码部分后面排错会用到。这里要强调一点TaoToken 是 API 通道不是编辑器替代品。你的 QT 代码还是在 QT Creator 或者你习惯的 IDE 里写TaoToken 只是帮你调用模型能力。两者是配合关系不是替代关系。配置好之后你可以先用 curl 测一下通道是否通curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: $TAOTOKEN_MODEL_ID, messages: [{role: user, content: ping}] }如果返回正常的 JSON 结构说明 Key 和通道都没问题。如果返回 401说明 Key 不对或者没带上如果返回连接错误检查网络和 Base URL 是否写错。这一步过了再往下做 QT 配置。3. 可复制的 QT 全屏与指针隐藏配置代码这一节是核心我会给出完整的、可复制的配置代码包括窗口标志设置、全屏调用、指针隐藏以及 TaoToken 的配置片段。你直接拿去改改就能用。先看窗口全屏。前面说过showFullScreen()只对顶级窗口有效。所以第一步是确保你的窗口是顶级窗口。如果你在写一个独立的 QT 应用主窗口默认就是顶级的直接调showFullScreen()就行。但如果你是在一个多窗口应用里某个子窗口需要全屏就得先改标志位// 将子窗口转为独立窗口并去掉边框 this-setWindowFlags(Qt::Window | Qt::FramelessWindowHint); this-showFullScreen();Qt::Window表示这是一个独立窗口Qt::FramelessWindowHint去掉标题栏和边框。这两个组合起来窗口就能铺满整个屏幕而且没有系统装饰。如果你不想用showFullScreen()也可以手动设置几何尺寸this-setWindowFlags(Qt::Window | Qt::FramelessWindowHint); this-resize(QApplication::desktop()-screenGeometry().size()); this-move(0, 0); this-show();这种方式更灵活适合你需要精确控制窗口位置的场景。注意QApplication::desktop()在 QT5 之后有些变化QT6 里推荐用QScreenQScreen *screen QGuiApplication::primaryScreen(); this-setGeometry(screen-geometry()); this-showFullScreen();再说指针隐藏。分两种情况如果你只在某个控件上隐藏指针用setCursorthis-setCursor(Qt::BlankCursor);但这种方式只在鼠标位于该控件上时生效移出去就恢复。如果你要全局隐藏用QApplication::setOverrideCursorQApplication::setOverrideCursor(Qt::BlankCursor);这个在程序启动时调用全局生效。但有个细节程序刚启动时指针可能还在需要用户触摸或移动后才消失。如果你要的是从启动到退出全程无指针在 QT Embedded 环境下用QWSServer#include QWSServer QWSServer::setCursorVisible(false);注意这个只在 QT Embedded 编译环境下有效X11 下会报链接错误。如果你在 PC 上调试用setOverrideCursor就够了移植到板子上再换成QWSServer。下面是 TaoToken 的配置片段放在你的项目配置里。如果你用 CMake可以这样写# CMakeLists.txt add_definitions(-DTAOTOKEN_BASE_URL\https://taotoken.net/api\) add_definitions(-DTAOTOKEN_MODEL_ID\你的模型ID\)API Key 不要写进 CMake用环境变量注入// 在代码里读取 QString apiKey qgetenv(TAOTOKEN_API_KEY); QString baseUrl QString(TAOTOKEN_BASE_URL); QString modelId QString(TAOTOKEN_MODEL_ID);如果你用 qmake在.pro文件里加DEFINES TAOTOKEN_BASE_URL\\\https://taotoken.net/api\\\ DEFINES TAOTOKEN_MODEL_ID\\\你的模型ID\\\这样配置的好处是Base URL 和 Model ID 编译期确定API Key 运行期注入安全性和灵活性兼顾。完整的 main 函数示例#include QApplication #include QScreen #include mainwindow.h int main(int argc, char *argv[]) { QApplication app(argc, argv); // 全局隐藏鼠标指针 QApplication::setOverrideCursor(Qt::BlankCursor); MainWindow w; // 全屏显示 w.setWindowFlags(Qt::Window | Qt::FramelessWindowHint); w.showFullScreen(); return app.exec(); }这段代码在 X11 和 Windows 下都能跑全屏和无指针效果都有。移植到 Embedded 时把setOverrideCursor换成QWSServer::setCursorVisible(false)即可。如果你需要退出全屏用showNormal()恢复this-showNormal(); this-setWindowFlags(Qt::SubWindow);注意顺序先showNormal()恢复大小再改回子窗口模式。如果反过来窗口可能回不到原来的位置和尺寸。4. 编译运行与验证请求的成功结果代码写完了接下来是编译和验证。这一步很关键因为全屏和指针隐藏的效果不跑起来是看不出来的。先编译。如果你用 qmakeqmake your_project.pro make如果你用 CMakemkdir build cd build cmake .. make编译过程中如果报undefined reference to QWSServer::setCursorVisible(bool)说明你在 X11 环境下用了 Embedded 专属的 API。解决办法有两个一是换成QApplication::setOverrideCursor(Qt::BlankCursor)二是切换到 QT Embedded 编译环境。PC 调试阶段建议用第一种。编译通过后运行./your_app预期结果是窗口铺满整个屏幕没有标题栏和边框鼠标指针不可见。如果你在触摸屏上测试触摸事件应该正常工作不会因为隐藏指针而失效。验证全屏是否成功可以在代码里加一行日志qDebug() Window geometry: this-geometry(); qDebug() Screen geometry: QGuiApplication::primaryScreen()-geometry();如果两个 geometry 一致说明全屏成功。如果不一致检查setWindowFlags是否生效以及是否在show()之前调用了全屏函数。验证指针是否隐藏可以在程序运行后移动鼠标看屏幕上是否还有指针。如果指针还在检查setOverrideCursor是否在QApplication初始化之后、窗口显示之前调用。顺序错了可能不生效。再验证 TaoToken 通道是否通。你可以在 QT 里发一个简单的 HTTP 请求#include QNetworkAccessManager #include QNetworkRequest #include QNetworkReply void testTaoToken() { QNetworkAccessManager *manager new QNetworkAccessManager(); QNetworkRequest request(QUrl(https://taotoken.net/api/v1/chat/completions)); request.setHeader(QNetworkRequest::ContentTypeHeader, application/json); request.setRawHeader(Authorization, Bearer qgetenv(TAOTOKEN_API_KEY)); QJsonObject body; body[model] QString(TAOTOKEN_MODEL_ID); QJsonArray messages; QJsonObject msg; msg[role] user; msg[content] ping; messages.append(msg); body[messages] messages; QNetworkReply *reply manager-post(request, QJsonDocument(body).toJson()); connect(reply, QNetworkReply::finished, [reply]() { if (reply-error() QNetworkReply::NoError) { qDebug() TaoToken response: reply-readAll(); } else { qDebug() TaoToken error: reply-errorString(); } reply-deleteLater(); }); }如果返回正常的 JSON说明通道没问题。如果返回 401检查 API Key 是否正确读取。如果返回连接超时检查 Base URL 和网络。实测下来全屏和指针隐藏这两个功能在 X11 和 Windows 下都比较稳定Embedded 下需要注意QWSServer的编译环境。TaoToken 通道在 QT 里用QNetworkAccessManager调用也很顺没有额外的依赖。5. 本篇常见错误排查这一节列出几个高频报错和排查方法都是我在实际项目里踩过的。第一个undefined reference to QWSServer::setCursorVisible(bool)。这个错误的原因是你在 X11 或者 Windows 环境下编译了 QT Embedded 专属的代码。QWSServer只在 QT Embedded 里有定义X11 版本没有。解决办法PC 调试阶段用QApplication::setOverrideCursor(Qt::BlankCursor)替代移植到板子上再换回QWSServer。如果你确实需要在 PC 上模拟 Embedded 行为可以加条件编译#ifdef Q_WS_QWS #include QWSServer QWSServer::setCursorVisible(false); #else QApplication::setOverrideCursor(Qt::BlankCursor); #endif第二个local proxy failed或者连接 TaoToken 时超时。这个通常不是 TaoToken 的问题而是你的网络环境或者代理设置。检查你的 QT 网络请求是否走了系统代理如果走了可能需要手动设置QNetworkProxy。另外确认 Base URL 是https://taotoken.net/api不要多加斜杠或者路径。第三个401 Unauthorized。这个最直接就是 API Key 不对。检查三件事Key 是否从https://taotoken.net/console/api-keys正确创建Key 是否完整复制没有多余空格请求头是否是Authorization: Bearer sk-xxx格式。如果 Key 没问题还是 401检查是不是用了过期的 Key。第四个reading choices相关错误。这个通常出现在你解析 TaoToken 返回的 JSON 时字段路径写错了。返回结构里choices是一个数组第一个元素的message.content才是模型输出。如果你直接读choices.content就会报错。正确的解析方式QJsonDocument doc QJsonDocument::fromJson(reply-readAll()); QJsonArray choices doc.object()[choices].toArray(); if (!choices.isEmpty()) { QString content choices[0].toObject()[message].toObject()[content].toString(); }第五个OAuth 相关报错。如果你用的是需要 OAuth 的模型或者服务检查 token 是否过期。TaoToken 的 API Key 方式不需要 OAuth但如果你在别的地方混用了 OAuth 流程可能会冲突。统一用 API Key 方式最省事。第六个全屏后窗口不响应键盘事件。这个通常是因为FramelessWindowHint去掉了标题栏窗口失去了焦点。解决办法是在showFullScreen()之后调用activateWindow()和setFocus()w.showFullScreen(); w.activateWindow(); w.setFocus();第七个指针隐藏后触摸失效。这个多半是因为你用了-nomouse启动参数。这个参数会同时禁用鼠标和触摸事件。改用setOverrideCursor或者QWSServer::setCursorVisible(false)就不会影响触摸。如果你在排查过程中需要模型帮你分析报错日志可以把错误信息贴到模型对话里让它帮你定位。入口在https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodel_chat。对于复杂的编译错误模型通常能给出比搜索引擎更精准的提示。6. 把全屏调试链路固定下来全屏显示和指针隐藏这两个功能单看代码量不大但真正落地的时候平台差异、编译环境、调用顺序每个环节都可能出问题。我的建议是把这一套配置固定成项目模板新项目直接复用不要每次重新踩坑。具体做法是在项目里建一个platform_config.h把平台相关的全屏和指针代码用宏隔开。X11/Windows 用setOverrideCursorEmbedded 用QWSServer。全屏统一用setWindowFlags(Qt::Window | Qt::FramelessWindowHint)加showFullScreen()退出用showNormal()加setWindowFlags(Qt::SubWindow)。这样不管在哪个平台编译代码都不用大改。TaoToken 的配置也建议固定下来。Base URL 和 Model ID 写进构建配置API Key 走环境变量。这样换模型、换 Key 都不用动源码。如果你需要长期做 QT 开发并且经常用模型辅助编码Coding Plan 会比单次调用更合适入口在https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcode_plan。最后说一个实用技巧在 QT Creator 里你可以把全屏和指针隐藏的代码做成代码片段snippet用快捷键快速插入。这样每次新建窗口类的时候不用手动敲一遍。另外调试阶段可以加一个快捷键比如 F11切换全屏和窗口模式方便对比效果。这些小的工程习惯比记住某个 API 更有长期价值。如果你在接入 TaoToken 或者配置 QT 全屏时遇到问题先看接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc大部分参数和错误码都有说明。Key 的管理在https://taotoken.net/console/api-keys需要新 Key 或者吊销旧 Key 都在这里操作。