1. 从三个属性说起：为什么 windowOpacity、cursor、font 值得单独拎出来
如果你正在写 Qt 桌面程序，QWidget 的属性面板里能改的东西少说几十个，但真正在项目里高频出现、又容易踩坑的，其实就那么几个。windowOpacity、cursor、font 这三个就是典型代表：它们看起来简单，一个管透明度、一个管鼠标形状、一个管字体，但实际用起来各有各的脾气。
比如 windowOpacity，你设成 0.5 发现窗口半透明了，但子控件也跟着一起透，想只让背景透、按钮不透就得多想一步。cursor 更微妙，你在某个按钮上设了手型光标，结果鼠标一移到子控件上就变回箭头，因为光标是跟着具体 widget 走的。font 则涉及字体族、字号、粗细、下划线等一堆属性，代码里设和样式表里设还可能打架。
这篇就围绕这三个属性，把获取方法、设置方法、常见坑点讲清楚，同时给出一份可以直接复制的 settings.json 骨架，配合 TaoToken 的统一 Key/API 通道，让 AI 辅助编码工具在 Qt 项目里也能稳定跑起来。适合正在做 Qt 界面、想快速调试窗口效果、又希望把 AI 编码工具配置一次到位的朋友。
2. TaoToken 前置：统一 Key 与 API 通道在 Qt 项目里的位置
在 Qt 项目里用 AI 辅助编码，常见做法是让编辑器或命令行工具去调模型接口。问题在于，不同工具要填的 Base URL、Key、模型名格式经常不一样，换一个工具就得重新配一遍。TaoToken 的思路是提供一个统一的 Key 和 API 通道，你只需要在配置文件里写一次，多个工具可以共用。
官网入口在这里：https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 地址是 https://taotoken.net/api ，注意 API 地址后面不加 UTM 参数，保持干净。
对于 Qt 项目来说，这个配置的意义在于：你在写 QWidget 属性调试代码时，可以让 AI 工具直接读你的项目文件、给出修改建议，而不需要每次手动复制粘贴上下文。配置一次之后，无论是模型对话、代码补全还是 Agent 式编码，都走同一个通道。
需要先拿到 API Key，入口在控制台的 API Keys 页面：https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite 。拿到之后，下面这份 settings.json 骨架就可以直接用了。
3. 可复制配置：settings.json 骨架与 QWidget 属性验证代码
3.1 settings.json 骨架
这份骨架把 TaoToken 的 API 通道和模型信息集中管理，你可以根据自己用的工具调整字段名，但核心的 base_url 和 api_key 保持一致。
{ "provider": "taotoken", "base_url": "https://taotoken.net/api", "api_key": "sk-你的Key填这里", "model": "claude-sonnet-4-20250514", "max_tokens": 4096, "temperature": 0.3, "tools": { "coding_plan": { "enabled": true, "endpoint": "https://taotoken.net/api/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite" }, "chat": { "enabled": true, "endpoint": "https://taotoken.net/api/chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite" } }, "project": { "type": "qt", "source_dir": "./src", "ui_dir": "./ui", "build_system": "cmake" } }几个字段说明：base_url 固定用 https://taotoken.net/api ，不要在后面拼多余路径；api_key 从控制台复制；model 按你实际可用的填；tools 里的两个 endpoint 分别对应长期编码场景和模型对话场景，按需启用。
3.2 windowOpacity 验证代码
windowOpacity 的取值范围是 0.0 到 1.0，0.0 全透明，1.0 完全不透明。获取用 windowOpacity()，设置用 setWindowOpacity(float)。注意内部会对超出范围的值做判断，大于 1.0 或小于 0.0 不会生效，但为了代码规范，建议在外面先 clamp 一下。
#include <QWidget> #include <QPushButton> #include <QVBoxLayout> #include <algorithm> class OpacityDemo : public QWidget { Q_OBJECT public: OpacityDemo(QWidget *parent = nullptr) : QWidget(parent) { auto *layout = new QVBoxLayout(this); auto *btnAdd = new QPushButton("增加不透明度", this); auto *btnSub = new QPushButton("降低不透明度", this); layout->addWidget(btnAdd); layout->addWidget(btnSub); connect(btnAdd, &QPushButton::clicked, this, [this]() { float cur = windowOpacity(); cur = std::min(1.0f, cur + 0.1f); setWindowOpacity(cur); qDebug() << "当前不透明度:" << windowOpacity(); }); connect(btnSub, &QPushButton::clicked, this, [this]() { float cur = windowOpacity(); cur = std::max(0.0f, cur - 0.1f); setWindowOpacity(cur); qDebug() << "当前不透明度:" << windowOpacity(); }); } };实测下来，setWindowOpacity 对整个窗口生效，包括子控件。如果你只想让背景半透明而按钮保持不透明，需要改用样式表里的 rgba 背景色，或者用 QGraphicsOpacityEffect 单独作用在某个控件上。
3.3 cursor 验证代码
cursor 控制鼠标悬停在某个 widget 上时的形状。获取用 cursor() 返回 QCursor 对象，设置用 setCursor(const QCursor&)。Qt 内置了一批光标形状，比如 Qt::PointingHandCursor、Qt::CrossCursor、Qt::WaitCursor 等。
#include <QWidget> #include <QPushButton> #include <QCursor> #include <QPixmap> class CursorDemo : public QWidget { Q_OBJECT public: CursorDemo(QWidget *parent = nullptr) : QWidget(parent) { auto *btnHand = new QPushButton("手型光标", this); auto *btnCross = new QPushButton("十字光标", this); auto *btnCustom = new QPushButton("自定义光标", this); btnHand->setCursor(Qt::PointingHandCursor); btnCross->setCursor(Qt::CrossCursor); QPixmap pixmap(":/images/cursor.png"); if (!pixmap.isNull()) { pixmap = pixmap.scaled(32, 32, Qt::KeepAspectRatio, Qt::SmoothTransformation); QCursor customCursor(pixmap, 0, 0); btnCustom->setCursor(customCursor); } qDebug() << "btnHand 光标形状:" << btnHand->cursor().shape(); } };这里有个容易踩的坑：pixmap.scaled() 不会修改原对象，而是返回一个新的副本，所以必须把返回值重新赋给 pixmap，否则缩放不生效。另外，setCursor 只对当前 widget 生效，鼠标移到子控件上会切换到子控件自己的光标。如果想全局覆盖，可以用 QGuiApplication::setOverrideCursor()，但记得配对调用 restoreOverrideCursor()。
3.4 font 验证代码
font 控制 widget 的字体信息，获取用 font() 返回 QFont 对象，设置用 setFont(const QFont&)。QFont 里常用的属性包括 family、pointSize、weight、bold、italic、underline、strikeOut。
#include <QWidget> #include <QLabel> #include <QFont> class FontDemo : public QWidget { Q_OBJECT public: FontDemo(QWidget *parent = nullptr) : QWidget(parent) { auto *label = new QLabel("字体属性演示", this); QFont font; font.setFamily("Microsoft YaHei"); font.setPointSize(14); font.setWeight(QFont::Bold); font.setItalic(true); font.setUnderline(true); label->setFont(font); QFont current = label->font(); qDebug() << "字体族:" << current.family(); qDebug() << "字号:" << current.pointSize(); qDebug() << "是否加粗:" << current.bold(); qDebug() << "是否斜体:" << current.italic(); qDebug() << "是否下划线:" << current.underline(); } };注意：如果你同时用了样式表设置字体，样式表的优先级通常高于 setFont。调试时如果发现 setFont 不生效，先检查有没有在别处写了 font-family 或 font-size 的 QSS。
4. 验证请求与成功结果：配置连通性检查
配置写好了，代码也写了，接下来要确认 TaoToken 通道能正常通。最直接的方式是用 curl 发一个最小请求，看返回是否正常。
curl -X POST https://taotoken.net/api/chat \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk-你的Key" \ -d '{ "model": "claude-sonnet-4-20250514", "max_tokens": 64, "messages": [ {"role": "user", "content": "回复 OK 两个字母即可"} ] }'如果返回里能看到正常的 JSON 结构，并且 content 里有模型输出，说明 Key 和通道都没问题。如果返回 401，检查 Key 是否复制完整；如果返回 404，检查 base_url 是否写成了 https://taotoken.net/api 而不是别的路径。
在 Qt 项目里，你也可以写一个简单的网络请求来验证，但更推荐先用命令行确认通道通，再回到编辑器里配置工具。这样出问题时能快速定位是通道问题还是工具配置问题。
成功的结果应该是：命令行返回正常 JSON，编辑器里的 AI 工具能读取你的 Qt 项目文件并给出针对 QWidget 属性的修改建议。比如你问「windowOpacity 设成 0.5 后子控件也透明了怎么办」，工具能结合你的代码给出用 QGraphicsOpacityEffect 或样式表 rgba 的方案。
5. 本篇常见错排查
5.1 windowOpacity 设了没反应
先检查值是否在 0.0 到 1.0 之间。虽然 Qt 内部会判断，但如果你传了 NaN 或者从字符串转换失败的值，可能静默不生效。另外，某些平台或窗口管理器对窗口透明度支持有限，可以换一个平台试试。如果只想让背景透明，不要用 setWindowOpacity，改用样式表：
this->setStyleSheet("background-color: rgba(255, 255, 255, 128);");5.2 cursor 在子控件上失效
这是正常行为，因为光标是 per-widget 的。如果你希望整个窗口区域都用同一种光标，可以在父 widget 上设，然后确保子控件没有覆盖。或者用 QGuiApplication::setOverrideCursor() 做全局覆盖，但记得在合适的时机 restore。
5.3 font 设置被样式表覆盖
Qt 里样式表的优先级高于代码里的 setFont。如果你在 QSS 里写了 font-size 或 font-family，代码里的设置可能不生效。排查方法是先把样式表注释掉，看 setFont 是否生效。如果确实需要两者共存，把字体设置也统一放到样式表里管理。
5.4 settings.json 里 base_url 写错
常见错误是写成 https://taotoken.net/api/chat 或 https://taotoken.net/api/v1。base_url 应该只到 https://taotoken.net/api ，具体的 endpoint 由工具自己拼接。如果你用的工具要求填完整路径，再按工具文档调整。
5.5 API Key 泄露风险
settings.json 如果提交到 Git，Key 就暴露了。建议把 Key 放在环境变量里，settings.json 里只写占位符，或者把 settings.json 加入 .gitignore。TaoToken 控制台可以随时吊销和重新生成 Key，发现泄露及时处理。
6. 配置分流与下一步
如果你主要是在排障和接入阶段，建议先去 API Keys 页面确认 Key 状态，再对照接入文档检查 base_url 和请求格式。API Keys 入口：https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite ，文档入口：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。
如果你只是想快速验证模型能不能正常对话，用模型对话入口发一条测试消息就行：https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite 。
如果你打算长期在 Qt 项目里用 AI 辅助编码，比如让工具帮你批量改 QWidget 属性、生成重复的 UI 代码，那 Coding Plan 更合适：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。配置一次，后面写 Qt 界面时就能随时让工具读你的代码给建议，省去反复复制粘贴的麻烦。
最后提醒一句：windowOpacity、cursor、font 这三个属性虽然简单，但组合起来调试时，建议先用 qDebug() 把当前值打出来，确认获取到的和设置的是否一致。很多时候问题不在设置方法，而在于你以为设了、其实被后面的代码覆盖了。
