简介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 的高亮器内部维护了一个QVectorHighlightRule规则表每条规则包含一个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引用HighlighterHighlighter引用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 i0; i5; 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 执行 setFormatvoid 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)).valueQColor(); QPalette pal editor-palette(); pal.setColor(QPalette::Base, bgColor); editor-setPalette(pal); }参数说明settings.value第二个参数是默认值QColor用valueQColor()取出否则会报类型转换错误。保存时对应的setValue要写入 QColorsettings.setValue(editor/bgColor, bgColor)Qt 会自动把 QColor 存成 QVariant。这一套做完用户调整过的编辑器外观在下次启动时还能保持这是一个工具从「能用」到「好用」的常见分水岭。4.4 常用参数速查表QCodeEditor 相关参数并不算多但每个参数都有自己容易踩坑的地方。下面是我整理出的一张速查表集成的时候按行对照检查参数或接口推荐值说明setTabStopDistance4 * 字符宽度别用固定像素值字体变了会导致 Tab 宽度不对setCurrentLineColorQColor(#2b2b2b)深色主题建议亮度低于背景浅色主题用淡黄setLineWrapModeQPlainTextEdit::NoWrap代码编辑器默认不换行如果需要换行记得关行号同步setCenterOnScrollfalse设置成 true 会让光标跳转时滚动幅度过大setCursorWidth2高 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 [; // 扩展开列处理大括弧 QListQTextEdit::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 自动扫描、行号区调色板、高亮器生命周期这三件事当作检查清单强制走一遍再也没有在编辑器上过夜。希望这份笔记能帮你省掉我当年趟过的那些坑把时间花在真正有用的功能上。本文还有配套的精品资源点击获取
)
