1. 从一次焦点“卡住”的调试说起
如果你正在用 QT 做富文本文档阅读器，大概率遇到过这样的场景：文档里插了一堆超链接，用户按 Tab 键想跳到下一个链接，结果焦点要么原地不动，要么直接跳出了 QTextBrowser，跑到别的控件上去了。这个问题我第一次遇到时也懵了很久，后来翻到QTextBrowser::focusNextPrevChild的源码才明白，焦点切换在富文本场景下并不是简单的控件焦点转移，而是由文本控制层接管的一套锚点查找逻辑。
QTextBrowser::focusNextPrevChild(bool next)这个虚函数，就是 QT 用来处理“下一个/上一个可聚焦元素”的入口。它和普通 QWidget 的焦点链不一样：普通控件靠setTabOrder排顺序，而 QTextBrowser 会优先在文档内部找锚点（anchor），只有找不到锚点时才回退到QTextEdit::focusNextPrevChild，把焦点交给外部控件。理解这条链路，对调试富文本阅读器、帮助文档、内嵌链接的日志面板都非常关键。
这篇内容我会从源码实现拆到可运行配置，同时把 TaoToken 的统一 Key/API 通道接进来，给出一套settings.json和config.toml的配置骨架，让你在调试焦点行为的同时，也能顺手把模型调用通道配好。适合正在做 QT 富文本组件、需要接入大模型能力做文档摘要或链接解释的开发者。
2. TaoToken 前置：统一 Key 与 API 通道准备
在动手改 QT 代码之前，先把调用通道准备好。TaoToken 在这里扮演的角色是统一入口：你不需要为每个模型单独维护一套 Key 和 Base URL，而是用同一个 API Key 走同一个通道，切换模型时只改模型名即可。对 QT 项目来说，这意味着你的网络请求层可以写得更薄，配置项集中在一个文件里。
你需要先拿到 API Key。访问控制台创建：
https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite创建完成后，Key 只在创建时完整显示一次，复制保存好。API 的基础地址是：
https://taotoken.net/api注意这个地址不带任何查询参数，直接作为 Base URL 使用。如果你用的是兼容 OpenAI 风格的客户端，通常填到/v1这一层，具体以接入文档为准：
https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite这里有个容易踩的坑：很多人把官网首页地址当成 API 地址填进代码，结果请求一直 404。官网是给人看的，API 是给程序调的，两者不要混。另外，Key 不要硬编码进 QT 的.cpp文件里，建议走配置文件或环境变量，后面我会给出settings.json和config.toml两种骨架。
3. 可复制配置：settings.json 与 config.toml 骨架
QT 项目读取配置的方式比较灵活，我一般用QSettings读 JSON，或者用 toml++ 读 TOML。下面两份骨架你可以直接复制，把YOUR_API_KEY换成控制台里拿到的 Key。
先看settings.json，适合用QJsonDocument解析的场景：
{ "taotoken": { "base_url": "https://taotoken.net/api", "api_key": "YOUR_API_KEY", "default_model": "claude-sonnet-4-20250514", "timeout_ms": 30000, "max_retries": 2 }, "qtextbrowser": { "links_accessible_by_keyboard": true, "focus_wrap": false, "highlight_on_focus": true } }再看config.toml，适合偏好 TOML 可读性的项目：
[taotoken] base_url = "https://taotoken.net/api" api_key = "YOUR_API_KEY" default_model = "claude-sonnet-4-20250514" timeout_ms = 30000 max_retries = 2 [qtextbrowser] links_accessible_by_keyboard = true focus_wrap = false highlight_on_focus = true两个配置里links_accessible_by_keyboard这一项直接对应源码里的Qt::LinksAccessibleByKeyboard交互标志。如果你在QWidgetTextControl::setFocusToNextOrPreviousAnchor里看到它返回 false，第一件事就是检查这个标志有没有被设上。默认情况下 QTextBrowser 是开启的，但如果你自定义了QTextEdit子类并手动改了interactionFlags，就可能把它关掉，导致 Tab 键完全找不到锚点。
读取配置的 QT 侧代码可以这样写，以 JSON 为例：
#include <QFile> #include <QJsonDocument> #include <QJsonObject> struct TaoTokenConfig { QString baseUrl; QString apiKey; QString defaultModel; int timeoutMs = 30000; }; TaoTokenConfig loadConfig(const QString &path) { TaoTokenConfig cfg; QFile f(path); if (!f.open(QIODevice::ReadOnly)) { qWarning() << "config open failed:" << path; return cfg; } const auto doc = QJsonDocument::fromJson(f.readAll()); const auto root = doc.object().value("taotoken").toObject(); cfg.baseUrl = root.value("base_url").toString(); cfg.apiKey = root.value("api_key").toString(); cfg.defaultModel = root.value("default_model").toString(); cfg.timeoutMs = root.value("timeout_ms").toInt(30000); return cfg; }这段代码只做读取，不做网络请求，方便你先验证配置路径对不对。实测下来，把配置读取和网络请求分开写，排障会快很多。
4. 源码链路：focusNextPrevChild 到底做了什么
现在回到焦点问题本身。QTextBrowser::focusNextPrevChild的实现可以拆成四步，我按调用顺序讲。
第一步，调用d->control->setFocusToNextOrPreviousAnchor(next)。这里的control是QWidgetTextControl，它才是真正管文档内锚点查找的对象。如果这个函数返回 true，说明文档内部找到了下一个锚点，焦点在文档内移动；返回 false，才走QTextEdit::focusNextPrevChild，把焦点交给外部控件。
第二步，setFocusToNextOrPreviousAnchor里先检查interactionFlags & Qt::LinksAccessibleByKeyboard。如果没设这个标志，直接返回 false。这就是为什么有些自定义控件 Tab 键完全失效——标志被关了。接着，如果当前光标没有选区，它会根据next把光标移到文档开头或结尾，作为查找起点。
第三步，findNextPrevAnchor是核心。它遍历QTextBlock和QTextFragment，找fmt.isAnchor() && fmt.hasProperty(QTextFormat::AnchorHref)的片段。找到锚点起点后，继续找第一个非锚点片段作为终点，最后用：
newAnchor.setPosition(anchorStart); newAnchor.setPosition(anchorEnd, QTextCursor::KeepAnchor);把锚点范围选中。KeepAnchor的作用是保持选区，让光标从 anchorStart 拉到 anchorEnd，形成一个可见的高亮选区。
第四步，回到setFocusToNextOrPreviousAnchor，如果cursor.hasSelection()为真，发出两个信号：updateRequest和visibilityRequest。前者通知重绘，后者通知滚动到可见区域。visibilityRequest最终连到QTextEditPrivate::_q_ensureVisible，里面通过hbar->setValue和vbar->setValue调整滚动条，让选中的锚点出现在视口里。
理解这条链路后，你会发现焦点“卡住”通常只有三个原因：LinksAccessibleByKeyboard没开、文档里根本没有带AnchorHref的片段、或者findNextPrevAnchor的遍历逻辑在你的文档结构下没匹配到。下面用实际请求验证一下配置和链路是否都通了。
5. 验证请求：确认通道与焦点行为
先验证 TaoToken 通道是否可用。用 curl 发一个最小请求，确认 Key 和 Base URL 没问题：
curl -s -X POST "https://taotoken.net/api/v1/messages" \ -H "Content-Type: application/json" \ -H "x-api-key: YOUR_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -d '{ "model": "claude-sonnet-4-20250514", "max_tokens": 64, "messages": [{"role": "user", "content": "reply with ok"}] }'如果返回里带content字段，说明通道通了。如果返回 401，检查 Key 是否复制完整；返回 404，检查 Base URL 是不是误填了官网地址。这一步过了，再回到 QT 侧。
QT 侧验证焦点行为，可以写一个最小可运行片段，往 QTextBrowser 里塞两个带 href 的锚点，然后拦截focusNextPrevChild看返回值：
#include <QTextBrowser> #include <QTextCursor> #include <QDebug> class DebugBrowser : public QTextBrowser { public: bool focusNextPrevChild(bool next) override { const bool handled = QTextBrowser::focusNextPrevChild(next); qDebug() << "focusNextPrevChild next=" << next << "handled=" << handled << "cursorHasSelection=" << textCursor().hasSelection() << "anchorAtCursor=" << anchorAtCursor(); return handled; } }; void setupDoc(DebugBrowser *browser) { browser->setOpenLinks(false); browser->setOpenExternalLinks(false); browser->setHtml( "<p>intro text</p>" "<p><a href=\"https://taotoken.net/doc\">doc link</a></p>" "<p>middle text</p>" "<p><a href=\"https://taotoken.net/api-keys\">keys link</a></p>" ); }运行后按 Tab 键，观察输出。正常情况下第一次 Tab 会选中第一个锚点，handled=true，cursorHasSelection=true，anchorAtCursor返回对应 href。第二次 Tab 选中第二个锚点。如果handled=false，说明文档内没找到锚点，焦点会跳出去。
如果你想把焦点行为调得更顺手，可以在配置里把focus_wrap打开，然后在子类里手动处理边界：当next=true且已经是最后一个锚点时，把光标移回第一个锚点。这个逻辑不复杂，但要注意别和QTextEdit::focusNextPrevChild的回退冲突。
6. 本篇常见错排查
报错一：Tab 键完全没反应，焦点不移动。先查interactionFlags是否包含Qt::LinksAccessibleByKeyboard。可以在构造函数里显式设置：
setTextInteractionFlags(textInteractionFlags() | Qt::LinksAccessibleByKeyboard);报错二：焦点跳到了外部控件，没在文档内循环。这是findNextPrevAnchor返回 false 的正常回退行为。检查你的 HTML 里锚点是否真的带href属性。只有<a name="x">没有href的锚点，fmt.hasProperty(QTextFormat::AnchorHref)为 false，不会被识别。
报错三：选中了锚点但视口没滚动过去。检查visibilityRequest信号是否被正确连接。如果你重写了QTextEdit的私有初始化流程，可能漏掉了_q_ensureVisible的连接。标准 QTextBrowser 不需要手动连，但自定义控件要留意。
报错四：请求返回 404 或连接超时。确认 Base URL 是https://taotoken.net/api，不是官网首页。确认请求头里的 Key 字段名和接入文档一致，不同客户端字段名可能是x-api-key或Authorization。
报错五：配置读取为空，baseUrl 是空字符串。检查 JSON 路径是否正确，QJsonDocument::fromJson解析失败时不会抛异常，只会返回空对象。建议在读取后加一句qDebug() << cfg.baseUrl，确认非空再往下走。
报错六：切换模型后请求失败。模型名要和通道支持的名称一致，不要自己拼写。如果拿不准，先用模型对话页面确认可用模型列表：
https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite7. 接入与长期编码的分流建议
如果你只是偶尔在 QT 项目里调一下模型做文档摘要，用 API Key 加接入文档就够了，配置骨架照上面抄即可。Key 管理页面在这里：
https://taotoken.net/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如果你在做的是长期编码项目，比如 QT 富文本编辑器要持续接入 Agent 做链接解释、文档问答，那更适合用 Coding Plan，把调用额度、模型切换、项目级配置统一管理：
https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite想先快速验证模型输出效果，不写代码，可以直接在模型对话页面试：
https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=chat&utm_campaign=rewrite最后补一个实用技巧：调试focusNextPrevChild时，把anchorAtCursor()和textCursor().selectionStart()/selectionEnd()一起打出来，能快速判断是锚点没找到，还是找到了但选区范围不对。我试过在文档里混排中英文和图片，锚点位置计算偶尔会偏，这时候对比QTextFragment::position()和实际选区，基本一眼就能定位。
：TaoToken统一Key接入与settings.json配置骨架)
