简介QCodeEditor 是一套基于 Qt5/C11 的代码编辑器小部件适用于需要在自有 Qt 应用中嵌入编辑/查看功能的开发者。它提供自动括号、自动缩进、空格转制表符、区块选择等编辑能力内置 GLSL、C、XML、JSON 等语言的高亮与补全规则同时示例中还包含 Python、Lua 的补全与高亮模块覆盖多种常见代码场景。压缩包共包含 73 个文件核心为 18 个 hpp 头文件与 18 个 cpp 源文件辅以 XML 语言规则、QRC 资源描述、CMake 构建脚本、JSON 配置及 README 说明整体仅 108KB轻量且结构清晰方便阅读与集成。该项目已有 817 人学习下载。源码内提供 Qt Creator 风格示例与完整语法高亮实现并包含行号区、语法样式、自动补全器等模块化实现有助于中高级 Qt 开发者理解编辑器组件设计目录按模块划分可快速定位高亮规则、补全器、行号区等实现也可按需修改规则、补充语言支持快速复用到个人工具或商业项目中。1. QCodeEditor 这个 Qt 小组件从零写编辑器之前先把它当底座凡是用 Qt Widgets 写工具的人都经历过这种尴尬界面骨架搭好了只差一个能输代码的输入框结果发现从行号到语法高亮都得自己造。QCodeEditor 就是这种场景下的现成答案——一个基于 Qt5/Qt6 Widgets 的 C 代码编辑器小部件把 QPlainTextEdit 上常见的行号区、语法高亮、关键字补全、搜索定位等能力打包成可复用组件。对做 IDE、脚本工具、日志分析器或教学 Demo 的人来说它直接把“编辑器长什么样”的技术债省掉把精力留给业务逻辑。这篇文章以 Qt 5.15.2 MSVC 2019 的接入为主线讲清组件结构、CMake 集成、高亮定制和最容易踩的坑新手按步骤能跑通熟手可以拿着参数表直接改。2. 先看懂它QPlainTextEdit 底座与行号、高亮、补全三组件2.1 为什么要选 QPlainTextEdit 而不是 QTextEditQCodeEditor 这类代码编辑器组件选 QPlainTextEdit 当底座很多入门者会以为只是因为“代码是纯文本”其实更关键的是文档模型差异。QTextEdit 面向富文本文档内部的 QTextDocument 要支持嵌入图片、表格、混合字体格式每次局部格式变化都可能触发更重的排版计算而 QPlainTextEdit 假设所有文本都用同一个默认格式把文档按文本块block组织渲染时只处理可见区域所以同样行数的文本后者滚动和插入明显更快。代码文件经常是几千行起步选 QPlainTextEdit 不是省事是性能考虑。另一个理由是高亮机制天然匹配。QSyntaxHighlighter 本身就是以文本块为单位刷新高亮某个块时只改这个块的额外格式不破坏整篇文档的格式状态。如果基类是 QTextEdit高亮器和富文本格式容易互相覆盖经常出现“上一行高亮还没消失下一行又染上色”的串色问题。QPlainTextEdit 的块状态模型让高亮、行号这些外围功能各改各的互不干扰。实际使用里还有两个参数我每次都会检查一是setLineWrapMode(QPlainTextEdit::NoWrap)代码编辑器一般不做软换行否则行号和文本块的映射会变得很别扭二是setTabStopDistance默认制表符宽度在有些平台上长得离谱我会设成 4 个空格宽度保证缩进风格统一。这两个设置按理说在 QCodeEditor 构造时就会处理但如果你自己二次封装很容易漏掉。注意如果你只是要在界面里显示一段带格式的帮助文本别用 QCodeEditorQTextEdit 加上只读属性就够了。代码编辑器的优化方向是“大量文本、频繁修改、行级更新”和文档展示是两个方向。2.2 行号区、高亮器、补全器的协作关系行号区在 QPlainTextEdit 里不是内置组件它是把一个小 QWidget 塞在编辑器的 viewport 左侧再通过三条信号连接让它跟编辑器“长在一起”。第一组是blockCountChanged信号文本块数量变化时重新计算行号区宽度第二组是updateRequest信号编辑器滚动或者重绘时把 viewport 的矩形和垂直偏移量传给行号区让行号跟着滚动同样的距离第三组是cursorPositionChanged当前行变化时触发当前行背景高亮。这三段连接缺一个都会出问题最典型的就是“鼠标滚轮滚动后行号上下错位”因为没消费updateRequest里带出来的 dy 偏移量。高亮器和补全器则是两条独立链路。高亮器挂在 QTextDocument 上不直接依赖编辑器窗口当文本块进入可视区域时才执行highlightBlock这也是为什么打开一个几 MB 的源文件不会卡死——它并不是真的“打开”它是按需高亮。补全器基于 QCompleter捕获编辑器的按键事件后弹出候选列表选中后用一个 QTextCursor 把候选词替换到光标位置。这里我建议把补全器的setCaseSensitivity和setFilterMode显式设置一下否则 Windows 和 Linux 下的默认行为不一致工程里换个机器补全结果就可能变。把典型的初始化和信号连接放在一起对照起来更清楚QCodeEditor::QCodeEditor(QWidget *parent) : QPlainTextEdit(parent) , lineNumberArea(new QCodeEditorLineNumberArea(this)) { setLineWrapMode(QPlainTextEdit::NoWrap); setTabStopDistance(4 * fontMetrics().horizontalAdvance( )); connect(this, QPlainTextEdit::blockCountChanged, this, QCodeEditor::updateLineNumberAreaWidth); connect(this, QPlainTextEdit::updateRequest, this, QCodeEditor::updateLineNumberArea); connect(this, QPlainTextEdit::cursorPositionChanged, this, QCodeEditor::highlightCurrentLine); updateLineNumberAreaWidth(0); highlightCurrentLine(); }参数说明NoWrap关闭软换行保证行号与文本块一一对应horizontalAdvance( )是在 Qt 5.11 之后取空格宽度的标准写法老版本需要用fontMetrics().width( )updateLineNumberAreaWidth(0)是为了让编辑器创建后的第一帧就有行号列的宽度而不是等用户输入后才出现。这个初始化顺序很多人会漏漏了之后行号区开始是 0 宽度必须发生一次文本变化才显示调试时很容易误判成样式问题。当前行高亮一般用ExtraSelection实现这也是 QCodeEditor 里常见的做法void QCodeEditor::highlightCurrentLine() { QListQTextEdit::ExtraSelection selections; if (!isReadOnly()) { QTextEdit::ExtraSelection selection; selection.format.setBackground(QColor(Qt::yellow).lighter(180)); selection.format.setProperty(QTextFormat::FullWidthSelection, true); selection.cursor textCursor(); selection.cursor.clearSelection(); selections.append(selection); } setExtraSelections(selections); }这段代码的逻辑是先构造一个全行宽度的背景色再把当前光标所在的 selection 交给编辑器绘制。关键在FullWidthSelection属性没有它高亮只覆盖光标到行尾的部分视觉效果会很难看clearSelection则是为了拿到一个不选中文本的光标位置避免每次移动光标都触发选区变化。2.3 最小高亮器骨架QSyntaxHighlighter 子类怎么写QCodeEditor 自带的高亮器往往通过加载资源文件来识别语言但明白继承关系仍然重要因为你很可能要扩展自己的 DSL。一个最简骨架长这样class BasicHighlighter : public QSyntaxHighlighter { Q_OBJECT public: explicit BasicHighlighter(QTextDocument *doc) : QSyntaxHighlighter(doc) { QTextCharFormat keywordFormat; keywordFormat.setForeground(QColor(#569CD6)); keywordFormat.setFontWeight(QFont::DemiBold); Rule rule; rule.pattern QRegularExpression(\\b(if|else|for|while|return)\\b); rule.format keywordFormat; rules.append(rule); } protected: void highlightBlock(const QString text) override { for (const Rule rule : rules) { auto match rule.pattern.match(text); while (match.hasMatch()) { setFormat(match.capturedStart(), match.capturedLength(), rule.format); match rule.pattern.match(text, match.capturedStart() match.capturedLength()); } } } private: struct Rule { QRegularExpression pattern; QTextCharFormat format; }; QVectorRule rules; };说明一下为什么要用QRegularExpression而不是老式QRegExpQt5 里前者用 PCRE 语法\\b单词边界处理得干净也不会出现中文环境下的匹配错位。setFormat的三个参数分别是起始位置、长度和格式循环里每次都要从上一处匹配的末尾继续查找否则while会死循环。关键词写在一个正则里比一行一行indexIn查询快得多文件行数多的时候差别尤其明显。3. 把 QCodeEditor 接进 Qt5 工程CMake 集成与最小可运行例子3.1 源码包结构以及为什么不建议编译成动态库一份典型的 QCodeEditor 源码包src/下面会拆出 QCodeEditor 本体、行号区、补全器、高亮器这几个模块另外还有resources/放语言定义和主题相关文件。依赖只有 Qt Widgets不碰网络和第三方库这是它接入成本极低的主要原因。我的建议是把它当源码直接编译进你的应用而不是先编成 dll 再链接。原因是这个小部件接口密集动态库版本一旦和 Qt 编译版本不一致运行期就报各种无法解析的外部符号处理起来比直接源码编译麻烦得多。QCodeEditor/ ├── src/ │ ├── QCodeEditor.cpp │ ├── QCodeEditor.h │ ├── QCodeEditorLineNumberArea.cpp │ ├── QCodeEditorLineNumberArea.h │ ├── QCodeEditorHighlighter.cpp │ └── QCodeEditorHighlighter.h ├── resources/ │ ├── languages/ │ └── theme/ └── CMakeLists.txt如果你拿到手的包结构略有出入以实际文件为准但大体逃不过这四组类。CMake 集成时不要用file(GLOB ...)去自动收集源文件虽然省事可一旦新增或删除文件CMake 不会自动重新生成构建系统容易留下“改代码不生效”的假象。显式列出源文件列表代价是几行代码换来的是构建过程可预期。3.2 CMakeLists 与 main.cpp 最小例子下面这个 CMake 配置是 Qt 5.15 MSVC 的场景我在几个项目里都用同一套模板cmake_minimum_required(VERSION 3.16) project(qce_demo LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) set(CMAKE_AUTOMOC ON) find_package(Qt5 5.15 REQUIRED COMPONENTS Widgets) add_executable(qce_demo main.cpp src/QCodeEditor.cpp src/QCodeEditor.h src/QCodeEditorLineNumberArea.cpp src/QCodeEditorLineNumberArea.h src/QCodeEditorHighlighter.cpp src/QCodeEditorHighlighter.h ) target_include_directories(qce_demo PRIVATE src) target_link_libraries(qce_demo PRIVATE Qt5::Widgets)两个必须解释的参数CMAKE_AUTOMOC负责扫描头文件里的Q_OBJECTQCodeEditor 的类都是带元对象系统的不开启这个选项连接时会报一堆 vtable 相关错误Qt5::Widgets是组件目标它自动带上 Qt5Core、Qt5Gui 的传递依赖不需要再单独find_packageCore 和 Gui。最小可运行例子只要一个窗口加一个编辑器#include QCodeEditor.h #include QApplication #include QFile #include QTextStream int main(int argc, char *argv[]) { QApplication app(argc, argv); QCodeEditor editor; editor.setWindowTitle(QCodeEditor on Qt5); editor.resize(800, 600); QFile file(main.cpp); if (file.open(QIODevice::ReadOnly | QIODevice::Text)) { QTextStream in(file); editor.setPlainText(in.readAll()); } editor.show(); return app.exec(); }setPlainText把文件内容一次性放进编辑器之后就不用管了。QTextStream读取时如果没有显式setCodec默认按本地编码读Windows 下遇到 UTF-8 文件会乱码这个点后面专门讲。如果你用的 QCodeEditor 版本里setPlainText不可用或者被封装成了其他接口直接换成editor.document()-setPlainText(...)效果一样QPlainTextEdit 的文档对象始终是那个 QTextDocument。3.3 Qt5 与 Qt6、MSVC 与 MinGW 的参数差异换到 Qt6 时CMake 里要把find_package(Qt5 5.15 ... )改成find_package(Qt6 ...)其余代码基本不动但要注意 Qt6 里很多枚举和类名做了清理比如QRegularExpression成为唯一正则接口旧代码里的QRegExp必须迁移。如果用 qmake则是在.pro文件里写QT widgets然后加一行CONFIG c17没有 CMake 的AUTOMOC概念因为 qmake 默认就处理 moc。MSVC 和 MinGW 的差异集中在两点。第一必须匹配 Qt 预编译二进制用 msvc2019_64 的 Qt 就得配 VS2019 的 MSVC 工具链MinGW 的 Qt 就得配对应版本的 MinGW-GCC混用会导致链接阶段出现大量“无法解析的外部符号”。第二MSVC 默认把源文件按本地代码页解析源码里有 UTF-8 中文注释时会报 C4819 警告甚至直接编译错需要在 CMake 里给 MSVC 加/utf-8if(MSVC) target_compile_options(qce_demo PRIVATE /utf-8) endif()这个选项不是什么玄学它就是告诉编译器“源文件、头文件、字符串字面量都按 UTF-8 处理”是解决中文字符串和注释乱码的第一道防线。4. 定制语法高亮与主题JSON 语言描述和继承高亮类的取舍4.1 内置语言文件的结构QCodeEditor 通常会把语法规则描述成外部资源这样加一种语言不需要重新编译。常见的语言定义结构大概是这样的{ name: C, extensions: [cpp, h, cc, cxx], keywords: [ alignas, alignof, auto, bool, break, case, catch, class, const, constexpr ], operators: [, -, *, /, , , !], comments: { line: //, blockStart: /*, blockEnd: */ } }这份 JSON 的作用是告诉高亮器三件事这个语言有哪些文件扩展名、哪些单词算关键字、注释符是什么。真正解析它的类负责把这些字段转成 QTextCharFormat 和 QRegularExpression然后在highlightBlock里逐行应用。你可以把它理解成“高亮规则的数据驱动层”改规则不动 C 代码。如果你要支持一种新语言比起在 C 里写死一长串关键字我更建议照着内置文件格式新增一个 JSON。理由很实际语法规则是会被频繁调整的比如给某个内部 DSL 增加指令名改 JSON 重新加载就行改代码就要重新编译调试成本完全不同。唯一的注意点是 JSON 里不要写 BOM 头某些加载逻辑对带 BOM 的文件会解析失败。4.2 自定义高亮规则关键字、字符串、注释的分类处理数据驱动适合规则简单的语言但碰到字符串和注释嵌套的情况纯 JSON 描述会有边界问题。比如 C 里的// http://example.com不能把整段 URL 当成注释的结束标志也不能把字符串里的//当成注释开始。这种场景我一般会退回继承高亮类的方式针对多行状态做显式处理void MyHighlighter::highlightBlock(const QString text) { // 第一遍处理多行注释状态 setFormat(0, text.length(), m_commentFormat); int commentStartIndex previousBlockState() InComment ? 0 : text.indexOf(/*); while (commentStartIndex 0) { int commentEndIndex text.indexOf(*/, commentStartIndex); int length commentEndIndex 0 ? commentEndIndex - commentStartIndex 2 : text.length() - commentStartIndex; setFormat(commentStartIndex, length, m_commentFormat); commentStartIndex text.indexOf(/*, commentStartIndex length); } // 第二遍覆盖关键字和字符串 if (previousBlockState() ! InComment) { for (const Rule rule : rules) { auto match rule.pattern.match(text); while (match.hasMatch()) { setFormat(match.capturedStart(), match.capturedLength(), rule.format); match rule.pattern.match(text, match.capturedStart() match.capturedLength()); } } } int lastCommentIndex text.lastIndexOf(/*); int lastCommentEnd text.lastIndexOf(*/); if (lastCommentEnd 0 lastCommentEnd lastCommentIndex) setCurrentBlockState(NoComment); else if (lastCommentIndex 0) setCurrentBlockState(InComment); else setCurrentBlockState(previousBlockState()); }这段代码的核心是previousBlockState()和setCurrentBlockState()。QSyntaxHighlighter 对每个文本块维护一个 int 状态多行注释的“上半行开着、下半行没关”就靠这个状态传递。我在highlightBlock开头先默认把整行设成注释格式再用关键字规则覆盖非注释部分比反过来做更稳妥因为注释优先级高只有先盖一层底才能避免 URL 里的//干扰关键字匹配。字符串和数字的处理不用每个字符都试用正则一次性命中比逐字符扫描快一个数量级QTextCharFormat stringFormat; stringFormat.setForeground(QColor(#CE9178)); QRegularExpression stringPattern(\([^\\\\\]|\\\\.)*\); auto match stringPattern.match(text); while (match.hasMatch()) { setFormat(match.capturedStart(), match.capturedLength(), stringFormat); match stringPattern.match(text, match.capturedStart() match.capturedLength()); }这个正则里[^\\\\\]表示非引号非反斜杠的字符\\\\.表示转义序列合起来就能正确处理字符串里的\和\\。如果你偷懒写成.*像abc def这种一行两个字符串的代码会被误判成一个超长字符串高亮结果直接翻车。4.3 主题配色与字体参数主题本质上就是一组 QPalette 和 QTextCharFormat 的组合QCodeEditor 能支持深色浅色切换是因为它把“语法元素颜色”和“编辑区基础色”分开了。我常用的参数配合如下界面元素对应项深色主题例子浅色主题例子背景色QPalette::Base#1E1E1E#FFFFFF前景色QPalette::Text#D4D4D4#333333当前行背景ExtraSelection#264F78#E8F2FE关键字QTextCharFormat#569CD6#0000FF字符串QTextCharFormat#CE9178#A31515注释QTextCharFormat#6A9955#008000字体方面编辑器必须用等宽字体Monospace这种逻辑族在各平台渲染不一致我会在 Windows 指定ConsolasLinux 指定JetBrains Mono或DejaVu Sans Mono。字号不要写死用QFontMetrics::horizontalAdvance推算出行号区宽度后跟随 DPI 缩放否则高分屏上字小得没法看。颜色对比度至少保证背景和文本的亮度差足够深色主题里最忌讳用纯黑色配深灰文字那等于让用户做视力测试。5. QCodeEditor 避坑与排查MSVC 依赖、中文乱码与高亮失效5.1 VS 编译时报“依赖项路径不存在”现象用 VS 打开 CMake 工程或编译时错误列表里出现类似:1 error: dependent ..\..\..\..\..\..\qt\5.15.2\msvc2019_64\include\qtwidgets\qwidget.h 不存在的报错工程里明明已经把 Qt 路径配好了头文件也找得到但 VS 的依赖跟踪器就是报找不到。原因这是 MSVC 的“源文件依赖”日志问题。VS 在编译时把头文件依赖写成相对路径如果工程目录和 Qt 安装目录之间的相对层级太多或者路径里带了中文、空格依赖跟踪就会解析失败。它不影响真正编译但会把错误信息刷屏让人误以为 Qt 环境坏了。解决先别急着重装 Qt。把 build 目录整个删掉用 CMake 重新生成一次构建脚本生成时把CMAKE_PREFIX_PATH显式指定到 Qt 的 msvc2019_64 目录。我还会顺手把 Qt 装到短路径比如C:\Qt\5.15.2\msvc2019_64工程也放到同一分区下相对路径层级就短了。如果是 VS 打开的工程删除.vs隐藏目录后重新打开也能清掉旧依赖缓存。5.2 中文注释乱码和 QTextStream 读取乱码现象编辑区里中文注释显示成乱码或者源码里字符串中文编译后运行显示为问号有时候编译不报错但 Qt Creator 和 MSVC 里看到的内容不一致。原因两个层面。一是源文件编码不是 UTF-8旧工程可能是 GBK 保存的二是 MSVC 默认按本地代码页解析源文件Qt 5.15 的 QString 默认又按 UTF-8 理解运行时字符串两边不对齐就乱。QTextStream 读取文件时同理不显式设置编码就按本地编码读UTF-8 中文文件在中文版 Windows 上必然乱码。解决先统一源文件保存为 UTF-8编译器选项按前面说的加/utf-8。读文件时显式指定编码QFile file(main.cpp); if (file.open(QIODevice::ReadOnly | QIODevice::Text)) { QTextStream in(file); in.setEncoding(QStringConverter::Utf8); // Qt6 // Qt5 写法: in.setCodec(UTF-8); editor.setPlainText(in.readAll()); }如果你还在用 Qt5setCodec(UTF-8)是老接口但足够用。乱码这种事没有银弹规则就一条源文件、编译器、运行时三个环节的编码声明必须一致我固定全部 UTF-8再没出过这种问题。5.3 高亮不生效或者补全弹出后崩溃现象编辑器显示出来了但关键字没有高亮或者输入单词后弹出补全候选框按回车或 ESC 直接崩溃。原因高亮不生效多数是因为高亮器挂载的时机不对。我之前写过把QSyntaxHighlighter子类创建出来后忘了setDocument或者稍晚在别的线程里去碰 QTextDocument结果高亮器静默失败。补全崩溃则典型是 QCompleter 的按键事件被编辑器消费后候选框还持有悬空指针或者在activated信号里直接修改了正在遍历的文本。解决高亮器必须在文档使用前挂载构造时传入 document 最稳auto highlighter new MyHighlighter(editor-document());不要在textChanged里重建高亮器正确做法是只修改规则后调用rehighlight()。补全器这边我一般会在回调里做个空指针保护并且不在信号处理里做复杂插入只更新光标位置让文本变化信号自然触发重绘。5.4 大文件滚动卡顿现象打开几万行的大文件滚动或打字时明显掉帧CPU 冲到接近满载甚至界面假死。原因QPlainTextEdit 的渲染是高效的瓶颈几乎一定在高亮器。常见的错误写法是在highlightBlock里对整行调用多组全局正则或者每次滚动都rehighlight()整篇文档。还有人在textChanged里做全文扫描等于把 O(n) 的操作复用到 O(n^2)。解决高亮只对当前可见块做这是 QSyntaxHighlighter 的默认行为别主动破坏它。滚动类操作不要触发重高亮只需要刷新可见区域。如果语言规则太复杂就把正则预编译好避免每次匹配都重新构造QRegularExpression对象这两点做到了几十万行的高亮基本都能保持流畅。6. 朝 IDE 再走半步查找替换、块缩进与 F5 一键运行6.1 给 QCodeEditor 补上查找和块缩进QCodeEditor 已经解决了“编辑器内核”但工程里真正要落地还得补几个顺手的小功能。查找最简单的方式是用 QPlainTextEdit 内置的find方法void findNext(QPlainTextEdit *editor, const QString text) { QTextDocument::FindFlags flags; if (QGuiApplication::keyboardModifiers() Qt::ShiftModifier) flags | QTextDocument::FindBackward; QTextCursor cursor editor-textCursor(); QTextCursor hit editor-document()-find(text, cursor, flags); if (hit.isNull()) { // 找不到就从文件头再找一圈 hit editor-document()-find(text, QTextCursor(editor-document()), flags); } if (!hit.isNull()) { editor-setTextCursor(hit); editor-ensureCursorVisible(); } }这个实现的关键是find的第二个参数传入当前光标位置的 cursor它会把查找范围限定为“光标到文件尾”返回 null 后再从文件头找一圈体验上就接近 IDE 的“循环查找”。块缩进则用QTextCursor的beginEditBlock批量处理一次操作记录为一件事撤销不会一段段跳。6.2 用 QShortcut 把运行按钮挂到 F5编辑器不是摆着看的写完代码总得跑。我会在编辑器外面加一个QShortcutQShortcut *runShortcut new QShortcut(QKeySequence(Qt::Key_F5), editor); runShortcut-setContext(Qt::WidgetWithChildrenShortcut); connect(runShortcut, QShortcut::activated, this, [this]() { QString code editor-toPlainText(); // 这里写你自己的脚本执行逻辑 runScript(code); });WidgetWithChildrenShortcut很重要它让快捷键只在当前窗口生效不会和全局事件冲突。真正执行脚本时不要在主线程里system()阻塞等待把进程放到QProcess异步启动拿到finished信号后再把输出刷到日志区。从那以后我每把一个外部组件接进 Qt 工程前都会先强制走一遍路径检查、编码检查和依赖跟踪清理再开始写业务代码。这套流程救过我太多次希望你也能少踩这些已经填平的坑把时间留给真正影响产品体验的编辑器功能希望帮到你。本文还有配套的精品资源点击获取