1. QTextCursor 到底是什么，为什么富文本编辑绕不开它
如果你正在用 Qt 写桌面文本编辑器，或者要给 QTextEdit 加一个「加粗」「改颜色」「查找替换」的功能，那你迟早会撞上 QTextCursor。简单说，QTextCursor 是 Qt 里操作 QTextDocument 的「遥控器」——它既是一个插入点，也是一段选区，还能携带格式信息。你看到的每一次光标闪烁、每一段被选中的蓝色高亮，背后都是它在工作。
它和 QTextEdit 的关系，有点像「数据」和「视图」。QTextEdit 负责把文档画出来、接收键盘鼠标事件；而真正决定「在第几个字符插入什么、把哪一段改成红色」的，是 QTextCursor。所以当你想做格式刷、撤销重做、块级样式这些功能时，直接操作 QTextEdit 的接口往往不够用，必须下沉到 QTextCursor 这一层。
适合谁看这篇？三类人：一是刚接触 Qt、想搞懂 QTextEdit 内部机制的初学者；二是正在做 Markdown 编辑器、代码编辑器、富文本笔记类产品的开发者；三是被「光标位置对不上」「格式只生效一半」这类问题折磨过的老手。我会从初始化、移动、选区、格式、撤销栈联动一路讲到排错，代码都能直接复制到 Qt Creator 里跑。
先建立一个核心认知：QTextCursor 是「值语义」的。你从textEdit->textCursor()拿到的是一个副本，改完必须setTextCursor()塞回去，界面才会更新。这一点是后面很多坑的根源，记住它。
2. 环境准备与 TaoToken 接入：让 AI 帮你写 QTextCursor 代码
写 Qt 代码时，我经常需要快速生成一段 QTextCursor 操作逻辑，或者让模型帮我解释某个枚举的含义。这时候一个稳定的模型调用入口就很省事。TaoToken 提供统一的 API 接入，官网在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 端点是 https://taotoken.net/api ，你可以把它当成一个兼容常见调用格式的模型网关，用来做代码补全、报错解释、文档润色都行。
先说清楚它不是什么：它不是编辑器替代品，也不是让你跳过 Qt 学习。它的定位是「你写 QTextCursor 卡住时，旁边有个能问的助手」。比如你不确定movePosition的n参数在NextWord下怎么算，直接问它比翻文档快。
接入前你需要准备三样东西，这也是后面所有配置的基础：
- Base URL：
https://taotoken.net/api - API Key：在控制台创建，地址是 https://taotoken.net/console/api-keys
- Model ID：按你需要的模型填，比如对话类或代码类模型
如果你用的是 Claude Code 这类命令行编码工具，可以走它的接入文档 https://taotoken.net/doc ，里面有针对性的配置说明。想先试试模型对话效果，可以直接打开 https://taotoken.net/models 体验。长期做编码和 Agent 任务的话，Coding Plan 会更划算，入口在 https://taotoken.net/coding-plan 。
这里给一个通用的配置片段，很多工具都认这种结构，把 Key 和 Model 换成你自己的即可：
{ "base_url": "https://taotoken.net/api", "api_key": "sk-你的Key", "model": "你的ModelID" }如果你用的是 Cline 配合 MCP，或者 Codex 的auth.json，配置思路一致，核心就是 Base URL、Key、Model ID 三件套齐全。缺任何一个都会在请求时报错，后面第 5 节会专门讲这些报错怎么认。
3. 可复制的 QTextCursor 初始化与移动配置
这一节是全文的核心，我给出一份可以直接粘进 Qt Creator 的完整示例，覆盖初始化、移动、选区、格式应用。先看头文件和工程配置：在.pro文件里加上QT += widgets，然后新建一个main.cpp。
#include <QApplication> #include <QTextEdit> #include <QTextCursor> #include <QTextCharFormat> #include <QTextBlockFormat> #include <QDebug> int main(int argc, char *argv[]) { QApplication app(argc, argv); QTextEdit editor; editor.setWindowTitle("QTextCursor Demo"); editor.resize(600, 400); // 1. 插入初始文本 QTextCursor cursor = editor.textCursor(); cursor.insertText("Hello, QTextCursor!\n"); cursor.insertText("This is a demo about cursor movement.\n"); cursor.insertText("Third line for block format test.\n"); // 2. 移动到文档开头并选中全部 cursor.setPosition(0); cursor.movePosition(QTextCursor::End, QTextCursor::KeepAnchor); // 3. 应用字符格式：蓝色 + 粗体 QTextCharFormat charFormat; charFormat.setForeground(Qt::blue); charFormat.setFontWeight(QFont::Bold); cursor.mergeCharFormat(charFormat); // 4. 单独给第一行加块格式（背景色） cursor.setPosition(0); cursor.movePosition(QTextCursor::EndOfBlock, QTextCursor::KeepAnchor); QTextBlockFormat blockFormat; blockFormat.setBackground(QColor(255, 245, 200)); cursor.mergeBlockFormat(blockFormat); // 5. 把光标塞回编辑器，界面才会刷新 editor.setTextCursor(cursor); editor.show(); return app.exec(); }这段代码有几个关键点值得拆开讲。第一，insertText是「在光标处插入」，插入后光标自动后移，所以连续三次insertText会依次追加，不需要手动移动位置。第二，setPosition(0)把锚点和光标都放到文档开头，此时没有选区；紧接着movePosition(QTextCursor::End, QTextCursor::KeepAnchor)保持锚点在 0、把光标移到末尾，于是形成「全选」。这就是MoveAnchor和KeepAnchor的本质区别：前者移动时丢弃选区，后者移动时扩展选区。
第三，mergeCharFormat和mergeBlockFormat的区别要记牢。字符格式作用于「选中的文字」，比如颜色、粗体、字号；块格式作用于「整个段落」，比如背景色、对齐、缩进。你如果对一段文字用mergeBlockFormat设背景，效果是整段背景变色，而不是只变选中那几个字。
再补充一个常用的移动操作对照表，方便你查：
| MoveOperation | 含义 | 典型用途 |
|---|---|---|
| Start / End | 文档开头 / 末尾 | 全选、跳转 |
| Up / Down | 上移 / 下移一行 | 键盘导航 |
| StartOfBlock / EndOfBlock | 当前段落首 / 尾 | 段落级操作 |
| NextWord / PreviousWord | 下一个 / 上一个单词 | 单词级选区 |
| NextCharacter | 下一个字符 | 精细移动 |
如果你想让光标移动时保留选区，第二个参数一律传QTextCursor::KeepAnchor；想取消选区重新开始，传QTextCursor::MoveAnchor。这个参数写错，是「选区莫名其妙消失」的最常见原因。
4. 验证请求与运行结果：在 Qt Creator 里跑起来
代码写好了，怎么确认它真的生效？按下面的步骤在 Qt Creator 里走一遍。
第一步，新建工程。打开 Qt Creator，选择File -> New File or Project -> Application (Qt) -> Qt Widgets Application，一路下一步，构建套件选你本机装好的（比如 Desktop Qt 6.x MinGW 64-bit）。工程建好后，把自动生成的main.cpp内容替换成上一节的代码。
第二步，检查.pro文件。确保里面有QT += widgets，否则QTextEdit会报找不到头文件。Qt 6 用 CMake 的话，在CMakeLists.txt里确认find_package(Qt6 COMPONENTS Widgets REQUIRED)和target_link_libraries(... Qt6::Widgets)都在。
第三步，编译运行。点左下角的绿色三角，或者按Ctrl+R。如果编译报错，先看是不是漏了#include <QTextCharFormat>或<QTextBlockFormat>，这两个头文件很容易忘。
第四步，观察窗口。正常的话你会看到一个 600x400 的窗口，里面三行文字：第一行是浅黄色背景、蓝色粗体；后两行是蓝色粗体但没有背景。第一行有背景，是因为块格式只作用于第一段。如果你看到的是「全部都有背景」，那说明你的块格式选区跨了多个块，检查EndOfBlock是不是写成了End。
第五步，做交互验证。在editor.show()之前加一行qDebug() << cursor.selectedText();，运行后看应用程序输出窗口，应该打印出你选中的文本。这一步能帮你确认选区范围是否符合预期，比肉眼看界面更准。
实测下来，最容易出问题的不是逻辑，而是「忘了 setTextCursor」。你改了 cursor 的格式，但没塞回 editor，界面纹丝不动，然后你怀疑人生。记住：cursor 是副本，改完必须还回去。
5. 常见报错排查：401、local proxy failed、reading choices、OAuth
这一节把两类问题放一起讲：一类是 Qt 编译运行时的错，一类是你用 TaoToken 辅助写代码时的接入错。先看接入侧，这几个报错我见过太多次。
401 Unauthorized：Key 不对或没带。检查你的 API Key 是否完整复制，有没有多余空格；确认请求头里的鉴权字段格式正确。如果用的是auth.json或 settings 文件，确认 Key 字段名和工具要求的一致。
local proxy failed：本地代理配置有问题。这类报错通常出现在工具的网络设置里，检查是不是填了一个不存在的本地端口，或者代理地址写错。把代理相关配置清空、直连 API 端点，往往就好了。
reading choices 相关报错：一般是响应结构不符合预期，常见于 Model ID 填错，或者请求体格式和端点不匹配。确认你填的 Model ID 在服务端是有效的，请求的 JSON 结构符合文档要求。
OAuth 相关报错：多见于命令行编码工具首次登录。按文档走一遍授权流程，确认回调地址和本地端口没被占用。如果反复失败，清掉本地缓存的凭证重新授权。
再看 Qt 侧。编译报QTextCursor: No such file or directory，说明没包含头文件或没加 widgets 模块。运行时报QObject::connect: Cannot queue arguments，通常是你在跨线程操作 cursor，QTextCursor 不是线程安全的，所有操作放主线程。界面不刷新，回到那句老话：setTextCursor调了吗？
还有一个隐蔽的坑：cursor.position()返回的是「字符索引」，但换行符\n也算一个字符。你按行号算位置时，如果没把换行符算进去，位置就会偏移。稳妥做法是用QTextBlock遍历，而不是自己数字符。
6. 继续深入：把 QTextCursor 用进真实编辑器
到这里，初始化、移动、选区、格式、排错都过了一遍。如果你要把它用进真实项目，下一步建议研究三件事：撤销栈、格式刷、查找替换。
撤销栈方面，QTextDocument 自带 undo/redo，但你要用beginEditBlock()和endEditBlock()把一组操作包起来，否则一次格式应用会被拆成很多步撤销，用户体验很差。格式刷方面，核心是读取当前charFormat()存起来，再mergeCharFormat到新选区。查找替换方面，用document()->find()拿到 cursor，再操作。
写这类功能时，我习惯让模型帮我审一遍边界情况，比如空文档、选区跨块、光标在文档末尾。TaoToken 的模型对话入口 https://taotoken.net/models 适合快速验证这类逻辑，接入文档 https://taotoken.net/doc 里有配置细节，API Key 在 https://taotoken.net/console/api-keys 创建。长期做编辑器开发的话，Coding Plan https://taotoken.net/coding-plan 能省不少调用成本。
最后留一个实用技巧：调试 QTextCursor 时，别只盯着界面看。把cursor.position()、cursor.anchor()、cursor.hasSelection()、cursor.selectedText()打成日志，比肉眼判断准得多。光标这东西，看得见的是闪烁，看不见的是锚点和位置，把这两个值盯住，九成的诡异问题都能定位。
