简介一款基于C11与Qt5构建的代码编辑器小部件面向需要在自有Qt应用中嵌入轻量代码编辑与查看功能的开发者。它提供自动括号、自动缩进、空格替换制表符、框选等基础能力并内置C、XML、JSON、GLSL、Lua、Python等多语言高亮与补全规则支持Qt Creator风格外观便于快速搭建定制化开发环境。压缩包共73个文件约108KB以hpp/cpp源码为主辅以xml样式、qrc资源、语法高亮规则和示例工程可直接集成或二次开发。已有816人学习下载。项目基于CMake组织既可独立构建也可作为子模块嵌入现有工程目录涵盖核心源码、示例与内嵌资源能省去从零实现语法高亮与补全的繁琐工作。1. QCodeEditor 是什么一个拿来就能嵌进 Qt5 工程的代码编辑器小部件QCodeEditor 是一个基于 QPlainTextEdit 二次封装的开源 Qt Widget 控件专门解决“引入代码编辑能力”这件事。你在 Qt 工具里做日志分析器、脚本配置台、上位机指令编辑器、甚至一个教学用 IDE 外壳都不需要从零造轮子——把它加进工程语法高亮、行号、当前行标记、括号匹配、自动补全这些基础能力就齐了。它面向的是 Qt Widgets 体系C 直接调用主流 Qt5 环境开箱即用同时兼容 Qt6 的编译路径。适合谁一句话手里有 Qt 工程、需要一块能编辑代码或结构化文本的区域又不想折腾 QScintilla 那套重依赖的人。这控件最让我认可的设计是把“语言规则”外置成了一个个独立的定义文件主题配色和语法规则都能在不动 C 代码的情况下调整。接下来的章节我按自己实际拆这个控件的顺序来写先讲怎么把它编译进工程再讲内部高亮、补全和 Designe r 插件怎么配合然后是换肤和自定义语言最后把部署时容易翻车的几个点列出来。2. 编译与接入先从 CMake 和 qmake 两条路把它跑起来2.1 先认识源码包的结构把 QCodeEditor 仓库拉到本地后不要急着往工程里拖先花五分钟把目录理一遍。这个控件的源码组织非常清爽核心结构大致如下QCodeEditor/ ├── src/ # 控件本体头文件和实现都在这 │ ├── QCodeEditor.h / QCodeEditor.cpp │ ├── QStyleSyntaxHighlighter.h / QStyleSyntaxHighlighter.cpp │ └── ... ├── resources/ # 各语言的高亮定义文件JSON 为主 │ ├── lua.json │ ├── xml.json │ ├── json.json │ └── ... ├── examples/ # 官方示例工程能独立编译运行 ├── CMakeLists.txt # CMake 构建入口 └── QCodeEditor.pri # qmake 用的工程包含文件src是你的主战场所有核心类都在里面resources是语言规则库新增语言或改配色基本不用碰 Cexamples是判断“环境是否正常”的试金石。我一般会把 examples 先编译一次确认高亮、行号、补全在示例里都正常再往自己的业务工程里接。这一步不要跳后面遇到问题你能少一半排查时间。如果你用的是 Qt 官方安装器装的 Qt5.15.2那么桌面套件MSVC 或 MinGW正常情况下都能直接打开 examples 编译。注意编译套件要和你后续业务工程一致否则后面链接阶段会冒一堆莫名字段。接下来分别说 CMake 和 qmake 两种接入方式。2.2 CMake 接入构建目标与链接参数我的主力构建系统是 CMake接入 QCodeEditor 最省心的方式是add_subdirectory让源码跟着你的工程一起编。下面是一个最小可用的 CMakeLists 配置cmake_minimum_required(VERSION 3.14) project(qce_demo LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) set(CMAKE_AUTOMOC ON) # 兼容 Qt5 / Qt6新老环境都不用改这个文件 find_package(QT NAMES Qt6 Qt5 REQUIRED COMPONENTS Widgets) find_package(Qt${QT_VERSION_MAJOR} REQUIRED COMPONENTS Widgets) # 把 QCodeEditor 放在 third_party 目录下 add_subdirectory(third_party/QCodeEditor) add_executable(demo main.cpp MainWindow.cpp MainWindow.h ) target_link_libraries(demo PRIVATE QCodeEditor Qt${QT_VERSION_MAJOR}::Widgets )这段配置里有几个点值得说明。CMAKE_AUTOMOC必须打开因为 QCodeEditor 内部有大量Q_OBJECT宏类moc 没跑链接时会出现 QCodeEditor 头文件里方法未定义的报错而且这种报错特别隐蔽第一眼都指向你业务代码身上。find_package(QT NAMES Qt6 Qt5 ...)是常见做法里最稳妥的双版本兼容写法Qt${QT_VERSION_MAJOR}会把 5 或 6 自动代进去避免硬编码 Qt5 导致以后升级麻烦。add_subdirectory之后会暴露一个库目标目标名取决于对方仓库里add_library写的名字我这里的QCodeEditor是常见命名你实际用的时候以仓库根目录 CMakeLists 里写的为准如果编不过就打开那个文件看一眼基本就是一行的事。2.3 qmake 接入一行 .pri 引入全部源码还在用 qmake 的工程一样能接而且比 CMake 更简单。QCodeEditor 提供了.pri文件qmake 的include指令可以直接把它展开进当前工程所有源文件都会被算进来QT widgets CONFIG c17 # 把源码直接编进当前工程 include($$PWD/third_party/QCodeEditor/QCodeEditor.pri) # 如果不想每次编译都重新编一遍控件也可以走预编译库 # INCLUDEPATH $$PWD/third_party/QCodeEditor/src # LIBS -L$$PWD/third_party/QCodeEditor/lib -lQCodeEditor SOURCES main.cpp HEADERS MainWindow.hinclude方式会把src下所有 .cpp 都带进你的构建流程缺点是第一次编译会久一点优点是省事、不用管库文件路径和依赖顺序。注释里的LIBS方案是给“产品化”准备的先单独出库业务工程只链库这样业务模块迭代不用每次重编控件实际部署时也更清爽。有一点要提醒qmake 在 Windows 下如果同时碰到 MSVC 构建的库和 MinGW 构建的库链接器会直接不认.lib后缀细节不一样路径对了也链不上。2.4 先跑官方示例验证环境接入前我强烈建议先把 examples 里现成的示例工程跑起来。打开 Qt Creator 直接选中 examples 目录下的 .pro 或 CMakeLists选桌面套件编译运行你应该能看到一个带行号、能高亮、输入时带补全弹出的编辑器窗口。如果这一步就跑挂了问题通常集中在三处环境变量没指向 Qt 的 bin 目录编译器套件和 Qt 安装版本不匹配或者resources目录没有被复制到运行目录。最后一个最隐蔽我遇到过直接打开示例时高亮全部失效因为程序运行时加载相对路径的 JSON 语言定义文件而工作目录并不是源码目录。顺手验证一下自己的工程写个最简单的入口#include QCodeEditor.h #include QApplication #include QVBoxLayout #include QWidget int main(int argc, char** argv) { QApplication app(argc, argv); QWidget w; auto* layout new QVBoxLayout(w); auto* editor new QCodeEditor(); editor-setPlainText(QStringLiteral( function hi()\n print(\hello\)\n end)); layout-addWidget(editor); w.resize(800, 500); w.show(); return app.exec(); }这段代码验证的是两件事第一QCodeEditor 头文件能找到且链接通过第二setPlainText 之后高亮是否立刻生效。如果文本颜色没有变化检查资源文件路径是否在你的 QCodeEditor 构造函数逻辑里被正确加载常见做法是把语言定义文件路径写成相对于应用程序运行目录的路径发布时要把整个 resources 目录一起拷走。这是在 Windows 和 Linux 上都要注意的部署细节。3. 核心机制拆解高亮、补全与 Designer 插件的协作方式3.1 类与职责知道谁在干什么QCodeEditor 不是一个大而全的上帝类它是由几个各司其职的组件拼出来的。搞清楚边界之后定制和排错才不至于瞎猜。我把主要参与者和职责列出来组件职责QCodeEditor主控件继承 QPlainTextEdit负责组装行号区、光标行高亮、括号匹配、补全交互QStyleSyntaxHighlighter继承自 QSyntaxHighlighter 的高亮器按语言定义文件逐行处理文本语言定义文件JSON 格式的规则集合描述具体语言的关键词、注释、字符串、数字等规则QCompleter 实例自动补全弹出层词表数据由使用方提供控件只负责触发和替换DesignerPlugin把控件注册进 Qt Designer 的插件方便在界面设计器里直接拖动关键点在于它选用了 QPlainTextEdit 作为基类而不是 QTextEdit。很多从 Qt 文档里入门的人会习惯性选 QTextEdit但 QTextEdit 是富文本编辑器内部保存的是带格式的文档结构处理几千行文本就开始发飘QPlainTextEdit 面向纯文本块行数多时优势明显。这也是 QCodeEditor 这类代码编辑器控件选它做基座的原因——代码编辑场景不需要富文本保住高性能比什么都重要。3.2 语法高亮是怎么组织的规则文件驱动的高亮器高亮的机制其实不复杂QStyleSyntaxHighlighter 继承 QSyntaxHighlighter后者每一行文本都会被单独送进highlightBlock处理。这个控件把规则从代码里搬出来放进了 JSON 文件这样加新语言就不用动 C。下面是一个简化的 Lua 语言定义示例真实仓库里每个语言一个文件字段命名比这个更规范但思路一致{ name: lua, global: { background: #1e1e1e, foreground: #d4d4d4 }, rules: [ { pattern: \\b(function|local|end|then)\\b, class: keyword, color: #569cd6 }, { pattern: \[^\]*\, class: string, color: #ce9178 }, { pattern: --.*$, class: comment, color: #6a9955 }, { pattern: \\d, class: number, color: #b5cea8 } ] }说几个实际使用中的门道。pattern用的是 QRegularExpression 的正则不是旧的 QRegExp所以语法上要按 Qt6 推荐的标准来写\b词边界对 ASCII 语言很可靠但对中文关键词无效。规则是逐行逐条匹配的每行可能命中多条规则后来的规则会覆盖先来的颜色所以像“ERROR”这种要突出显示的关键词我会把它放在文件靠后的位置这样即使前面有字符串规则先命中后面的规则也能盖上去。如果修改了 JSON 规则运行时不会自动热加载需要重新触发高亮常见做法是重建一个高亮器实例赋给编辑器或者对 QSyntaxHighlighter 调用重载方法。3.3 自动补全接入词表模型由你提供QCodeEditor 内部做好了补全的交互逻辑但它没有内置一套语言智能提示库词表得由使用方给。这个设计很合理因为不同业务的补全需求差别太大做脚本编辑器词表是变量名和关键字做日志工具词表是过滤指令和字段名。用 QCompleter 挂接是最常见的方式auto* completer new QCompleter(editor); completer-setCaseSensitivity(Qt::CaseInsensitive); completer-setCompletionMode(QCompleter::PopupCompletion); QStringListModel* model new QStringListModel({ function, local, require, print, table, if, then, else }, completer); completer-setModel(model); editor.setCompleter(completer);这段代码里setCaseSensitivity(Qt::CaseInsensitive)让补全在输入小写时不至于匹配不到大写关键字这个开关在代码编辑场景默认应该打开。PopupCompletion模式是输入时弹列表用户敲回车或双击选中需要说明的是这个模式不会在用户输入时抢走焦点。如果你的 QCodeEditor 版本没有暴露setCompleter就需要自己子类化加一个接口逻辑也不复杂监听 QCompleter 的 activated 信号把当前光标位置到单词边界的文本替换成选中项。另外如果工程里有 MVVM 框架这套结构天然合适——编辑器只负责视图层交互词表数据绑定在 ViewModel 上切文件时刷新模型就行。3.4 在 Qt Designer 中使用插件方式与提升方式想在 Qt Designer 里可视化地使用 QCodeEditor有两条路。第一条是编译它自带的 DesignerPlugin 目标得到一个插件动态库Windows 下是 .dllLinux 下是 .so拷到 Qt 安装路径下plugins/designer/目录重启 Qt Designer左侧控件列表里就会出现 QCodeEditor像拖 QPushButton 一样拖进窗口。这条路的坑是插件必须用当前 Qt 版本和同一编译器构建比如 Qt 5.15.2 MSVC2017 的 Designer就只认同配置编译出的插件否则 Designer 会在启动时静默忽略它错误只打印到 stderr。第二条路更省事不用编译插件在窗体上先放一个 QPlainTextEdit右键选择“提升为”类名填 QCodeEditor头文件填 QCodeEditor.h。生成的 .ui 文件里会多出这么一段customwidgets customwidget classQCodeEditor/class extendsQPlainTextEdit/extends headerQCodeEditor.h/header /customwidget /customwidgets提升方式的好处是不受插件目录和编译器匹配的约束uic 生成代码时会直接包含 QCodeEditor.h你只要保证工程里能 include 到它就行。缺点是在 Designer 画布上看不到真实渲染效果只能看到一个空白区域。我的习惯是开发期用提升方式等界面布局稳定了再决定要不要补插件毕竟插件多一次构建就多一份维护成本。4. 定制与换肤把通用控件改成你业务里的编辑器4.1 颜色主题从哪里改分清 QSS 与高亮两套体系接手一个编辑器控件第一个想改的必然是颜色。QCodeEditor 的颜色体系是分开的窗口外观边框、滚动条、背景、下拉框走 Qt 样式表 QSS文本区域的代码颜色走语言定义文件里的global和规则里的color字段。很多人在 QSS 里改了背景色发现代码区域没变就是这个原因。我一般会把两套主题统一管理用一个独立的头文件或配置文件把颜色常量抽出来。比如深色主题的窗口底和编辑区底要一致否则看起来像硬拼的控件/* 这套 QSS 管窗口外观 */ QCodeEditor { background-color: #1e1e1e; border: 1px solid #3c3c3c; } QCodeEditor QScrollBar:vertical { background: #2d2d2d; width: 10px; }而代码文本的颜色则回到对应语言 JSON 的global块去改。如果你给多个语言定义了不同的前景色切语言时视觉会跳变所以我通常会让所有语言定义共享同一套主题色只改规则里的选区颜色这样用户切语言不会觉得“亮瞎眼”。顺带提醒QSS 里写颜色就写死十六进制没必要引入额外变量机制。4.2 自定义一套语言定义文件以日志查看器为例业务里最常见的一个需求是把日志文件读进来按级别高亮。这个用 QCodeEditor 的默认 C 高亮显然不合适给它加一个自定义的日志语言定义就行。下面是我给日志场景写的一个规则文件骨架{ name: logviewer, rules: [ { pattern: ^\\[INFO\\], class: info, color: #569cd6 }, { pattern: ^\\[WARN\\], class: warning, color: #dcdcaa }, { pattern: ^\\[ERROR\\], class: error, color: #f14c4c }, { pattern: \\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}:\\d{2}, class: time, color: #6a9955 } ] }写这个文件有两条经验值得记。第一每行日志通常只有一个级别标记用^锚定行首匹配最稳但不建议对整行内容做高亮否则日志里原本的字符串内容会被冲掉第二规则顺序就是优先级顺序我会把 ERROR 那行放在最后因为它的权重最高即使前面有规则误匹配到内部文本最后也能覆盖回来。还有字符编码这个 JSON 文件如果包含中文标签必须保存为 UTF-8最好是无 BOM 的干净 UTF-8Qt 读入 QString 时是按 UTF-8 解码的一旦存成 GB2312运行时匹配都会失败还不好排查。4.3 编辑行为参数Tab 宽度、字体与光标行代码编辑器的手感很多时候取决于几个容易被忽略的小参数。Tab 宽度是第一个要调的默认值偏小尤其在中文等宽字体下会显得逼仄// Qt 5.10 使用 setTabStopDistance更老的版本用 setTabStopWidth editor-setTabStopDistance(4 * editor-fontMetrics().horizontalAdvance( )); QFont font(JetBrains Mono, 10); font.setStyleStrategy(QFont::PreferAntialias); editor-setFont(font);horizontalAdvance( )是拿到当前字体下空格的像素宽度乘以 4 就是“一个 Tab 等于 4 个空格”的宽度。这里不要直接写死数字 40因为不同字体、不同 DPI 下同样的像素值表现差距很大用字体度量算才是最稳的。字体方面Windows 下如果指定的等宽字体不存在Qt 会自动回落但中文注释的渲染会变得很难看所以我会在 setFont 之后读取一次 actualFont确认没有被替换成非等宽字体再用 QFontMetrics 重新算一遍 Tab 宽度。光标行高亮和括号匹配的颜色一般在 QCodeEditor 源码中通过QTextEdit::ExtraSelection控制这是 QPlainTextEdit 的标准机制改起来直接搜代码里 QColor 常量就行不用走 JSON。5. 常见问题排查与避坑五个部署期的真实报错5.1 部署后双击闪退事件里看到 0x0000005现象release 版在开发机上一跑就正常拷贝到同事电脑或者干净虚拟机里双击图标闪一下就没Windows 事件查看器里记录到 0x0000005 访问冲突。 原因基本离不开两个一是 Qt 的 DLL、plugins 目录没有随程序一起发布程序启动时找不到 platform 插件直接退出二是用 MSVC 构建的程序目标机器缺 VC 运行库。0x0000005 是典型的内存访问违例在 Qt 场景里八成是空插件。 解决用 windeployqt 把依赖自动打出来这是行业标准动作别再手动拷 DLL 了windeployqt --release --no-translations my_tool.exe执行完检查 my_tool.exe 同级目录是否有platforms/文件夹里面至少要有qwindows.dll。如果程序还用到了图像解码imageformats/也会一起生成。MSVC 构建的还要顺手装一下vc_redist.x64.exe或者把对应 DLL 放进去。从那以后我发布 Qt 程序一律强制跑一遍 windeployqt并且复制目录后第一时间在干净虚拟机上验证。5.2 板卡上报错qt.qpa.plugin: could not find the qt platform plugin linuxfb现象同样的程序在开发机上用 X11 正常显示交叉编译到嵌入式板卡或者树莓派上运行时报qt.qpa.plugin: could not find the qt platform plugin linuxfb程序直接退出。 原因Qt 通过插件机制加载平台层程序运行时找不到plugins/platforms/libqlinuxfb.so或者环境变量没有告诉 Qt 去哪找插件目录。常见于把开发机上编译的 Qt 库直接拷贝到板卡使用的场景。 解决先确认 Qt 库的部署目录里确实有对应的平台插件export QT_QPA_PLATFORMlinuxfb export QT_QPA_PLATFORM_PLUGIN_PATH/opt/qt/plugins ./my_tool开发机上如果只是想跑通程序逻辑不关心界面显示可以用-platform offscreen启动就能在无屏环境下验证不涉及 GUI 的逻辑。真机上板的时候还要确认 framebuffer 设备节点有读写权限否则即便插件加载成功打开/dev/fb0失败也一样白屏退出。交叉编译场景下插件路径最容易出问题我习惯在启动脚本里用$ORIGIN相对定位插件目录避免写死绝对路径。5.3 编译报错unknown module(s) in qt: webenginewidgets现象把 QCodeEditor 集成进现有工程后编译告警:-1: error: unknown module(s) in qt: webenginewidgets。 原因这个报错十有八九不是你自己的代码引起的而是工程里某个模块顺手写了QT webenginewidgets或者从别人工程拷贝来的 .pro 里带了这行。QCodeEditor 本身不依赖 WebEngine它是纯 Widgets 组件。 解决检查所有 .pro 文件把webenginewidgets依赖去掉这个模块体积大、编译重普通工具型应用根本用不到。如果业务确实需要内嵌网页再去 Qt 安装器里按当前 Qt 主版本补装 WebEngine 组件装完确认模块名与 Qt 大版本匹配Qt6 的模块路径和 Qt5 已经不一样了。集成第三方控件时遇到这种红色报错养成先看模块依赖再怀疑控件本身的习惯。5.4 链接报错cannot find -lpublic现象集成工程编译到最后链接阶段报cannot find -lpublic。 原因这行报错的意思是链接器在指定的搜索路径里找不到名为public的库文件。最常见的是工程里写了-lpublic但磁盘上库名是libpublic.so.1.2或者是复制库文件时把软链丢了其次是-L指定的目录不对指向了一个空路径。 解决对齐库文件命名是第一个排查动作ls -l /path/to/libs/*public* # 如果只有 libpublic.so.1.2 ln -s libpublic.so.1.2 libpublic.so链接器的-lpublic会严格匹配libpublic.so或libpublic.a两种形态版本号后缀不算数所以符号链接是最常用的解法。另外如果工程里同时用了-L和-l确保-L写在-l前面这在 qmake 生成的命令里顺序偶尔会被打乱。实在不想折腾符号链接直接在 LIBS 里写完整路径/path/to/libpublic.so也能绕过搜索规则代价是路径写死了换机器要改配置。5.5 MSVC 编译器下中文注释报 C2001 或高亮错位现象源文件里写了中文注释或中文字符串字面量MSVC 编译时偶尔报 C2001 常量中有换行符或者字符串莫名其妙截断更隐蔽的是某个 JSON 规则文件里的中文字段运行时怎么都匹配不上。 原因MSVC 对无 BOM 的源文件默认按本地代码页读取Windows 中文环境下就是 GBK而 Qt 的 QString 默认按 UTF-8 解读字面量两边就错位了。这个问题的排查效率极低因为它编译能过只是运行结果不对。 解决源文件统一存成 UTF-8 with BOMVisual Studio 的“文件 → 另存为 → 编码保存”里选“Unicode (UTF-8 带签名)”之后再改编码就不会再犯。语言定义 JSON 文件同理除非你确定内容全 ASCII否则一律 UTF-8 存储。Linux 和 macOS 上的 clang/gcc 没有这个坑所以很多 Linux 下写好的代码拿回 Windows 上编译就翻车不是代码逻辑问题就是编码问题。从那以后我接任何 Qt 工程第一件事先把编码规则定下来。6. 进阶小技巧动态词表补全与超大文件的防御性处理QCodeEditor 的补全能力上限取决于词表模型静态词表只适用于固定关键字场景做脚本编辑器、SQL 工具这类产品时词表应该跟着当前文档内容动态变化。常见做法是切文件或保存时扫描文档里的标识符合并进内置关键字列表void refreshCompleter(QCodeEditor* editor, QCompleter* completer) { QStringList words; // 扫描当前文档提取长度大于 2 的英文标识符 const QString text editor-toPlainText(); QRegularExpression re([A-Za-z_][A-Za-z0-9_]{2,}); QRegularExpressionMatchIterator it re.globalMatch(text); QSetQString seen; while (it.hasNext()) { const QString w it.next().captured(0); if (!seen.contains(w)) { seen.insert(w); words w; } } // 合并内置关键字关键词优先 QStringList builtIn { function, return, if, end }; words builtIn words; auto* model qobject_castQStringListModel*(completer-model()); model-setStringList(words); }这是我在业务里常用的动态补全逻辑先扫描全文提取标识符去重后和内置关键字合并。注意正则里已经限制{2,}的字符长度这样能过滤掉a、b这种无意义变量减少词表噪音。QSet的去重方案跑几万行文档也没压力不会成为性能瓶颈。如果文档很大我不会每次按键都调toPlainText而是放在文件加载完成后、或者定时器间隔几秒刷新一次用户体感会更顺。超大文件的处理思路要提前说QCodeEditor 基于 QPlainTextEdit处理 10 万行左右的日志文件仍然能保持基本流畅但如果开启了每行都跑复杂正则的高亮规则滚动时会有明显卡顿。我的做法是打开文件时先判断大小超过阈值就切一个空规则语言定义或者干脆不挂高亮器只保留行号这样滚动、跳转、搜索都保持响应。毕竟日志工具的核心诉求是“能开、能查、不崩”高亮反而是次要的。可控性和边界感才是这类控件的正确用法。从那以后我每次接入 QCodeEditor 到新工程都会强制自己先跑一遍官方示例、再确认资源部署、最后写一个 100 行的最小复现入口。这三个动作看似琐碎实际省掉了我过去一半以上的集成期排错时间。希望帮到你。本文还有配套的精品资源点击获取