简介：QCodeEditor 是一份基于 Qt5 的代码编辑器小部件资源，主要面向需要为桌面应用快速嵌入轻量级编辑能力的 Qt 开发者。该小部件支持自动括号匹配、自动缩进、空格替换制表符，并内置 C++、GLSL、XML、JSON 等多语言的高亮规则与补全规则，还可选择 Qt Creator 风格外观，能够覆盖代码查看与简易编辑的常见需求。资源包共 73 个文件，以 hpp/cpp 源文件为主，辅以 qrc/xml/json 等配置与语法规则文件，压缩包体积仅 108KB，结构清晰，便于按需裁剪或扩展自定义语言。项目采用 CMake 构建，既能作为子模块集成到现有工程，也可独立编译使用，源码中还包括示例工程与样式定义可供参考。当前已有 817 人学习下载，适合希望深入理解语法高亮与代码补全实现机制，或需要定制编辑器外观与行为的 Qt 中级及以上开发者。
1. 别从零写代码编辑器：QCodeEditor 小部件能省下三周工作量
上个月前，我在做一个跨平台工具，界面里需要嵌一个脚本编辑器，能打开 JSON、Python 和 C++ 文件，要有行号、语法高亮、自动缩进。一开始我打算用 QPlainTextEdit 配合自绘高亮，结果才发现正则状态机、行号边距、括号匹配、撤销栈这些坑远比想象中密集，三天了连高亮都没稳定。后来我换了 QCodeEditor 这个 Qt 代码编辑器小部件，半天时间就把功能接进去了，样式和交互几乎就是现成的。如果你也在用 Qt5 写桌面工具，需要嵌入式编辑能力又不想背 QScintilla 那种重量级依赖，这份资源值得先拉进工程里跑一遍。
2. 拆解 QCodeEditor 的核心设计：不是魔法，是 QPlainTextEdit + 规则表
2.1 控件体系：编辑器、行号区、语法高亮器各自的分工
QCodeEditor 整体结构并不神秘，它就是在一个 QPlainTextEdit 子类上面挂了两个辅助对象：一个行号区（LineNumberArea）和一个语法高亮器（Highlighter）。这种分层和 Qt Creator 的编辑器架构类似，但实现更精简。编辑器本身负责文本编辑、光标、滚动，它会在 paintEvent 和 resizeEvent 里把左侧位置让出来，行号区作为一个 QWidget 覆盖在同一视口上。
行号区与编辑器通过信号绑定，常见的做法是：编辑器内维护一个 LineNumberArea 指针，当 blockCount 改变、updateRequest 触发或光标移入移出时，调用行号区的 update 和宽度调整。QCodeEditor 通常在构造时设置setViewportMargins，把编辑区左边留出行号宽度，这样文本不会与行号重叠。这个机制能正常工作依赖一个细节：updateRequest信号必须连接到行号区的update槽，否则滚动时行号会糊成一团。高亮器则是标准的 QSyntaxHighlighter 子类，重写highlightBlock，对每个文本块应用格式。
拆开看，你不需要改动骨架，只需要往规则表里塞东西。这个设计的好处是：控件边界清晰，编辑器不关心语言，语言不认识界面，想加一个语言只需要新增一组高亮规则，不会污染主代码。
2.2 高亮规则是怎么驱动的：正则表达式表与状态切换
QCodeEditor 的高亮器内部维护了一个QVector<HighlightRule>规则表，每条规则包含一个QRegularExpression和一个QTextCharFormat。highlightBlock执行时，会遍历当前语言的语言规则，对每个规则调用match并setFormat。规则表的方式对 C++、Java、JavaScript 这类按关键字和正则划分的语言很友好，因为它不需要复杂的词法分析器。
多行注释的处理方式是把高亮状态挂在setCurrentBlockState上。第一次遇到/*时记录状态，下一行如果还没遇到*/就继续沿用注释格式，直到遇到结束符再清空状态。这个机制是 QSyntaxHighlighter 的标准用法，需要注意同一个高亮器实例不能同时被多个编辑器复用，因为状态是按QTextBlock存储的，复用会串线。我一般会在资源包里找到PythonHighlighter.cpp这类实现，然后复制一个新的类改成自己的规则。
规则表的匹配顺序也很重要。很多刚入门的人把关键字规则放在注释规则前面，结果字符串里的关键字也被高亮了。QCodeEditor 的规则表里，注释和字符串规则优先于关键字规则，顺序错了就会出现颜色污染，这个在 5 章踩坑里再展开。
2.3 为什么选择 QPlainTextEdit 而不是 QScintilla
做 Qt 桌面端代码编辑器，绕不开的一个选型问题是：用 QScintilla 还是自研 QPlainTextEdit 方案？QScintilla 是 Scintilla 的 Qt 封装，功能非常强，SciTE、大量 IDE 都基于它，但有两个硬伤：一是编译需要单独构建第三方库，跨平台分发时要把依赖一起带上；二是它的 API 风格偏 C 风格，与 Qt 的 model/view 习惯有明显隔阂，新手第一次接触会被setSciCall这类接口劝退。
QCodeEditor 走的是纯 Qt 路线，它只依赖 QtWidgets 和 QtGui 模块，不需要额外链接第三方库。对比下来，它更适合的场景是：工具需要嵌入一个「够用但不花哨」的编辑器，能高亮常见语言，能支持行号和缩进，偶尔做做代码校验，但不想让安装包体积为了一个编辑器膨胀一倍。如果目标是做一个专业级 IDE，那 QScintilla 值得考虑；如果只是工具里需要一个编辑器，我把话放这儿：QCodeEditor 的几十个源码文件比你手写的三周高亮方案要稳定得多。
3. 把 QCodeEditor 接进你的 Qt5 工程：qmake 与 CMake 两条路
3.1 资源包里的文件该放哪：目录结构与 include 路径
拿到 QCodeEditor 资源后，第一件事不是双击 .pro 试图编译，而是先看目录结构。常见的包内组织是根目录下有两块：src和example。src里是编辑器本体，包括CodeEditor.h/.cpp、LineNumberArea.h/.cpp、若干Highlighter子类；example里是演示程序，用来确认控件的基本用法。
我习惯把这类第三方控件放在项目的3rdparty/QCodeEditor目录下，而不是直接堆进src里。这样 qmake 和 CMake 的路径都清晰，后续如果控件升级也只影响一个目录。放好后，需要把头文件路径加入 INCLUDEPATH。头文件之间的依赖关系是：CodeEditor引用Highlighter，Highlighter引用QRegularExpression，所以 Qt 模块不需要额外添加，Qt5 里QtWidgets和QtCore就够了。
3.2 qmake 集成：简单粗暴但管用
如果你的项目还在用 qmake，集成 QCodeEditor 很直接。假设控件的 src 目录是3rdparty/QCodeEditor/src，在 .pro 文件里加：
INCLUDEPATH += $$PWD/3rdparty/QCodeEditor/src SOURCES += \ $$PWD/3rdparty/QCodeEditor/src/CodeEditor.cpp \ $$PWD/3rdparty/QCodeEditor/src/LineNumberArea.cpp \ $$PWD/3rdparty/QCodeEditor/src/Highlighter.cpp HEADERS += \ $$PWD/3rdparty/QCodeEditor/src/CodeEditor.h \ $$PWD/3rdparty/QCodeEditor/src/LineNumberArea.h \ $$PWD/3rdparty/QCodeEditor/src/Highlighter.h这段代码把整个控件编译进你的工程，而不是让 Qt Creator 单独去加载一个子项目。逻辑说明：$$PWD是 qmake 提供的变量，指向 .pro 文件所在目录，用它拼接路径可以避免相对路径在不同构建目录下的歧义。参数说明：如果有多个语言高亮器文件，需要一并加入 SOURCES 和 HEADERS，比如PythonHighlighter、CppHighlighter，否则链接时会报未定义符号。我习惯于把高亮器文件名列在最前面，这样后来维护时一眼就能看到哪些语言支持。
3.3 CMake 集成：更现代的做法
新项目用 CMake 的话，代码更干净。可以把 QCodeEditor 的 src 目录当作一个静态库目标，然后在你的可执行文件里链接：
add_subdirectory(3rdparty/QCodeEditor) target_include_directories(your_target PRIVATE 3rdparty/QCodeEditor/src ) target_link_libraries(your_target PRIVATE qcodeeditor)逻辑说明：add_subdirectory会让 CMake 把控件自己的 CMakeLists.txt 也展开，由它生成qcodeeditor目标。注意参数：QCodeEditor 的 CMakeLists 通常会把 Qt5 的依赖声明为find_package(Qt5 QUIET COMPONENTS Widgets)，如果你的工程已经找到过 Qt5，尽量避免重复添加，只在链接库层面操作就行。如果你的构建服务器比较保守，也可以直接用 source 列表方式：
set(QCODE_EDITOR_SRC 3rdparty/QCodeEditor/src/CodeEditor.cpp 3rdparty/QCodeEditor/src/LineNumberArea.cpp ) set(QCODE_EDITOR_HDR 3rdparty/QCodeEditor/src/CodeEditor.h ) target_sources(your_target PRIVATE ${QCODE_EDITOR_SRC} ${QCODE_EDITOR_HDR}) target_include_directories(your_target PRIVATE 3rdparty/QCodeEditor/src)这里target_sources的好处是不破坏现有 target 结构，也不需要额外管理一个库目标，缺点是如果以后要加第三方库，编译时间会涨在同一个 target 里。
3.4 最小可运行示例：一个带行号的高亮编辑器
集成完成后，写一个最小 main.cpp 验证控件能跑。下面这段是我每次集成完都会先跑一遍的冒烟测试：
#include <QApplication> #include <QMainWindow> #include "CodeEditor.h" #include "CppHighlighter.h" int main(int argc, char *argv[]) { QApplication app(argc, argv); QMainWindow window; window.setWindowTitle("QCodeEditor Smoke Test"); CodeEditor* editor = new CodeEditor(&window); auto* highlighter = new CppHighlighter(editor->document()); // 这里使用 document() 初始化高亮器，保证生命周期跟随文档 editor->setPlainText( "#include <iostream>\nint main() {\n" " for(int i=0; i<5; ++i) {\n" " std::cout << i << std::endl;\n" " }\n" "}\n" ); window.setCentralWidget(editor); window.resize(800, 600); window.show(); return app.exec(); }这段代码执行后的预期现象是：窗口内出现一个带行号的编辑区，C++ 关键字有颜色，数字有颜色，注释也有颜色。逻辑说明：new CppHighlighter(editor->document())是关键，高亮器的父对象是文档，而不是编辑器，这样高亮器会跟随文档结构走，不会在编辑器销毁前被提前清理。参数说明：如果你不需要高亮，直接省略 highlighter 创建那行，控件本身仍然能显示行号和基本缩进。如果想测试其它语言，把CppHighlighter换成资源包里对应的高亮器头文件就行，两者接口一致。
4. 定制主题与语言高亮：把默认样式改成你自己的风格
4.1 编辑器常规配色：字体、背景、当前行
默认的 QCodeEditor 自带一套类似 VS Code Dark 的样式，但实际集成时几乎都要改。编辑器配色主要通过 QTextCharFormat 和 QPalette 完成，不要依赖setStyleSheet，因为语法高亮的颜色是highlightBlock里用QTextCharFormat直接刷到文本块上的，QSS 管不了这些。
修改背景和当前行颜色的标准做法是：先改控件自身的调色板，再改视口背景。代码片断如下：
editor->setFont(QFont("JetBrains Mono", 11)); editor->setTabStopDistance(4 * QFontMetrics(editor->font()).horizontalAdvance(' ')); QPalette pal = editor->palette(); pal.setColor(QPalette::Base, QColor("#1e1e1e")); pal.setColor(QPalette::Text, QColor("#d4d4d4")); editor->setPalette(pal); editor->setStyleSheet("QPlainTextEdit { selection-background-color: #264f78; }");参数说明：setTabStopDistance在 Qt 5.10 后取代了已废弃的setTabStopWidth，如果你用的 Qt 版本较老，需要换成setTabStopWidth(4 * fontMetrics().width(' '))。另一个坑是jetBrains Mono字体不一定在所有系统都存在，商用环境里我一般用Consolas或monospace做后备。背景色和前景色改完后，当前行高亮的颜色在 QCodeEditor 里通常由setCurrentLineColor提供，我建议在控件初始化时调用：
editor->setCurrentLineColor(QColor("#2b2b2b"));这个接口是控件自己暴露的，读者可能看到的是setCurrentLineColor，如果资源里没有这个函数，就说明版本较老，需要在paintEvent里额外画当前行的背景，那是后话。
4.2 新增一种语法：三步注册高亮规则
假设你要支持 TOML 文件高亮，但资源包里没有现成的 TOML 高亮器，那就自己写一个。步骤不多，完全照着现有 Python 高亮器的骨架抄就行。第一步，新建TomlHighlighter.h和TomlHighlighter.cpp；第二步，在构造函数里添加规则；第三步，把文件加进工程编译。核心的构造函数代码：
TomlHighlighter::TomlHighlighter(QTextDocument* document) : QSyntaxHighlighter(document) { HighlightRule rule; QTextCharFormat keyFormat; keyFormat.setForeground(QColor("#569CD6")); keyFormat.setFontWeight(QFont::Bold); rule.pattern = QRegularExpression("^\\s*[A-Za-z_\\-]+(?=\\s*=)"); rule.format = keyFormat; rules.append(rule); QTextCharFormat stringFormat; stringFormat.setForeground(QColor("#CE9178")); rule.pattern = QRegularExpression("\"[^\"\\n]*\""); rule.format = stringFormat; rules.append(rule); QTextCharFormat commentFormat; commentFormat.setForeground(QColor("#6A9955")); commentFormat.setFontItalic(true); rule.pattern = QRegularExpression("#[^\n]*"); rule.format = commentFormat; rules.append(rule); }这段代码的逻辑是：用正则(?=\\s*=)做前瞻匹配，只匹配等号左边的 key，又不把等号吃掉。参数说明：QRegularExpression默认是贪婪匹配，如果你写字符串规则时用了".*"，同一行的多个字符串会被当成一个大字符串，所以字符串规则里我加了[^"\\n]*来限定不能跨行。添加规则后还要记得重写highlightBlock函数，遍历 rules 执行 setFormat：
void TomlHighlighter::highlightBlock(const QString &text) { for (const HighlightRule &rule : rules) { QRegularExpressionMatchIterator it = rule.pattern.globalMatch(text); while (it.hasNext()) { QRegularExpressionMatch match = it.next(); setFormat(match.capturedStart(), match.capturedLength(), rule.format); } } }这里的遍历方式与 QCodeEditor 内置高亮器保持一致。性能上，规则数量控制在 20 条以内基本不会有感觉，超过 50 条后，每行滚动都要跑一遍正则，会有轻微卡顿。
4.3 保存与恢复用户习惯：用 QSettings 记住配色
工具型应用里用户改过的字体和主题，不能每次都重置。我的做法是在关闭时写 QSettings，在初始化时读 QSettings。因为 QCodeEditor 的配色分散在调色板和高亮规则里，所以我做了一个集中的EditorSettings结构体。这里只贴关键的恢复逻辑：
void loadEditorSettings(QPlainTextEdit* editor, QSettings& settings) { QString fontFamily = settings.value("editor/fontFamily", "Consolas").toString(); int fontSize = settings.value("editor/fontSize", 11).toInt(); QFont font(fontFamily, fontSize); editor->setFont(font); int tabWidth = settings.value("editor/tabWidth", 4).toInt(); editor->setTabStopDistance(tabWidth * QFontMetrics(font).horizontalAdvance(' ')); QColor bgColor = settings.value("editor/bgColor", QColor("#1e1e1e")).value<QColor>(); QPalette pal = editor->palette(); pal.setColor(QPalette::Base, bgColor); editor->setPalette(pal); }参数说明：settings.value第二个参数是默认值，QColor用value<QColor>()取出，否则会报类型转换错误。保存时对应的setValue要写入 QColor，settings.setValue("editor/bgColor", bgColor)Qt 会自动把 QColor 存成 QVariant。这一套做完，用户调整过的编辑器外观在下次启动时还能保持，这是一个工具从「能用」到「好用」的常见分水岭。
4.4 常用参数速查表
QCodeEditor 相关参数并不算多，但每个参数都有自己容易踩坑的地方。下面是我整理出的一张速查表，集成的时候按行对照检查：
| 参数或接口 | 推荐值 | 说明 |
|---|---|---|
setTabStopDistance | 4 * 字符宽度 | 别用固定像素值，字体变了会导致 Tab 宽度不对 |
setCurrentLineColor | QColor("#2b2b2b") | 深色主题建议亮度低于背景，浅色主题用淡黄 |
setLineWrapMode | QPlainTextEdit::NoWrap | 代码编辑器默认不换行，如果需要换行记得关行号同步 |
setCenterOnScroll | false | 设置成 true 会让光标跳转时滚动幅度过大 |
setCursorWidth | 2 | 高 DPI 下 1 像素光标不容易看到 |
QRawFontMetrics相关 | 无需设 | 别手动改 metrics，否则行号区宽度和文本区会脱节 |
这表是用一笔笔血泪换来的，尤其是第一行和最后一行，几乎每个接手 QCodeEditor 的人都会踩到。
5. 避坑指南：QCodeEditor 集成中的 5 个高频翻车现场
5.1 现象：光标消失或光标块异常
现象是编辑器能输入，但光标形状是 1 像素细线，甚至在深色背景下完全看不见。原因通常不是 QSS 问题，而是 QPlainTextEdit 的光标宽度在高 DPI 下被压缩，或者控件的调色板没有给Window颜色。解决方法是显式设置光标宽度：
editor->setCursorWidth(2); QPalette pal = editor->palette(); pal.setColor(QPalette::Window, QColor("#1e1e1e")); editor->setPalette(pal);第一种解决的是物理像素，第二种解决的是光标绘制时的背景合成。如果这两步还不行，请检查是否在编辑器初始化之后调用了setPlainText，它偶尔会把视图状态重置。
5.2 现象：高亮错位或刷新不全
现象是滚动后部分行没有高亮，或者注释串到了下面的代码行。大概率是两件事造成的：高亮器实例生命周期不对，或者状态标记缺失。我曾经在一个封装里用new CppHighlighter(editor)创建高亮器，然后编辑器与文档分离，结果高亮器随编辑器销毁，文档还在用旧状态，编码全是乱的。解决：
auto* highlighter = new CppHighlighter(editor->document()); // 不要 new 在 editor 上，文档生命周期才与文本内容同步同时检查highlightBlock里是否正确调用了setCurrentBlockState。如果上一行是/*，下一行没有继承注释状态，请在多行注释规则匹配后加上：
if (blockState() == 1) { // 继续是注释 }5.3 现象：QSS 背景与行号区色差
现象是编辑区是自定义的深色背景，行号区却是默认白色，非常刺眼。原因是 QSS 里的setStyleSheet("QPlainTextEdit { background-color: #1e1e1e; }")管不到行号区，行号区是独立的 QWidget 子类。解决方法是同时设置行号区的调色板，QCodeEditor 里有lineNumberArea对象，用它的 update 槽来响应调色板变更：
QPalette pal = editor->lineNumberArea()->palette(); pal.setColor(QPalette::Window, QColor("#252526")); pal.setColor(QPalette::HighlightedText, QColor("#d4d4d4")); editor->lineNumberArea()->setPalette(pal);如果没有lineNumberArea()接口，就在构造行号区时传入编辑器的调色板，并且在paintEvent里用QPainter::fillRect绘制背景色。
5.4 现象：复制粘贴后缩进乱套
现象是外部复制一段带 TAB 的代码，粘贴进来后缩进宽度不一致，行号与代码错位。原因是 QCodeEditor 的行号区宽度是默认用fontMetrics.horizontalAdvance(' ')计算的，并没有考虑制表符实际渲染宽度。解决方法是重写setTabStopDistance为空格宽度，并且在粘贴事件里统一把\t替换成四个空格：
connect(editor, &QPlainTextEdit::textChanged, editor, [editor]() { if (editor->tabStopDistance() < 0) { editor->setTabStopDistance(4 * QFontMetrics(editor->font()).horizontalAdvance(' ')); } });最简单的方案：砍掉 TAB 的语义，统一只接受空格。如果用户确实需要 TAB，那在插入前把\t转成QString(" ")，一行代码解决，但要在按键事件层做。
5.5 现象：编译报“未定义引用 vtable”
现象是链接时出现vtable for ...错误，或者moc相关错误。原因很简单：你的高亮器类里有Q_OBJECT宏，但工程里没有把对应的头文件交给 moc 处理。在 qmake 里，只要头文件列在HEADERS中，qmake 会自动生成 moc；但如果你用的是target_sources方式，很容易漏掉头文件，或者高亮器 .cpp 文件被误放在 SOURCES 里而头文件没在 HEADERS 里。解决：
set(QCODE_EDITOR_HDR 3rdparty/QCodeEditor/src/TomlHighlighter.h 3rdparty/QCodeEditor/src/CodeEditor.h ) target_sources(your_target PRIVATE ${QCODE_EDITOR_HDR} 3rdparty/QCodeEditor/src/TomlHighlighter.cpp )CMake 的AUTOMOC功能会自动扫描头文件里的Q_OBJECT，但如果没开set(CMAKE_AUTOMOC ON)，就要在 CMakeLists 里加上。这一步是集成 QCodeEditor 时出现编译错误的最常见原因，没有之一。
6. 进阶：把 QCodeEditor 武装成轻量 IDE 的最后一公里
编辑控件能跑之后，很多人发现它离「顺手」还差两个点：括号匹配和自动补全。QCodeEditor 资源包里不一定有现成的括号高亮，但我们可以用一个极小的技巧实现括号匹配。在编辑器的cursorPositionChanged信号里，读取当前光标前后的字符，如果是(、)、[、{等，就用setExtraSelections给它们画一个背景框：
void matchParentheses(QPlainTextEdit* editor) { QTextCursor cursor = editor->textCursor(); QTextBlock block = cursor.block(); QString text = block.text(); int pos = cursor.position() - block.position(); if (pos <= 0 || pos > text.length()) return; QChar prevChar = text.at(pos - 1); QChar nextChar = (pos < text.length()) ? text.at(pos) : QChar::Null; QChar matchChar = QChar::Null; if (prevChar == '(') matchChar = ')'; else if (prevChar == ')') matchChar = '('; else if (prevChar == '[') matchChar = ']'; else if (prevChar == ']') matchChar = '['; // 扩展开列处理大括弧 QList<QTextEdit::ExtraSelection> selections; if (!matchChar.isNull()) { QTextEdit::ExtraSelection sel; sel.format.setBackground(QColor("#264f78")); sel.cursor = cursor; selections.append(sel); } editor->setExtraSelections(selections); }这段代码里text.at(pos - 1)和text.at(pos)分别检查光标左右两侧的字符，保证光标在括号左右移动时都能匹配到最近的配对符号。setExtraSelections不会改变文档内容，只是临时绘制选区，所以不用担心污染文本。
自动补全的实现更轻量：在keyPressEvent里拦截用户输入，当输入if、for、func等前缀时，弹一个 QListWidget 放在编辑器的正上方。由于 QCodeEditor 是基于 QPlainTextEdit 的，我们可以在keyPressEvent的末尾调用QPlainTextEdit::keyPressEvent保持默认行为，再触发补全列表的更新。这个方法比接 QCompleter 要可控，因为 QCompleter 的弹窗定位在 QPlainTextEdit 上经常有小 bug。
到这里，QCodeEditor 的资源集成路线基本走通。如果你手头这份资源包里没有某个语言的高亮器，按 4.2 的模板复制一份就能加；如果你做的是离线工具，记得把所有字符格式颜色都用 QSettings 保存，不要写死在 C++ 里。我从那以后每次集成第三方控件，都会把 moc 自动扫描、行号区调色板、高亮器生命周期这三件事当作检查清单，强制走一遍，再也没有在编辑器上过夜。希望这份笔记能帮你省掉我当年趟过的那些坑，把时间花在真正有用的功能上。
本文还有配套的精品资源，点击获取
