做Qt开发的人早晚会遇到一个绕不开的需求给QTextEdit或者QTextDocument加上语法高亮。市面上不少现成控件确实能用但一旦牵扯到自定义语言、日志关键字、配置文件的特定规则尤其是想跟上自己工程里那套风格时还是得自己动手。我自己维护的一个跨平台小工具当初就是因为在日志面板里找不到一款能同时高亮多种格式的现成组件最后老老实实研究了一遍QSyncHighlighter的底层机制才彻底解开这个症结。这篇文章我就把Qt之自定义语法高亮规则这条路的完整走法写出来从机制原理到代码骨架、从单行关键字到跨行注释、从性能优化到常见坑位一步不落。不管你是刚接触Qt的新手还是已经写过一些工具、想通读一遍原理的老手这篇文章都能给到你实际能用的东西。1. 为什么非要自己写高亮规则而不是直接拖一个现成控件1.1 默认控件只是能打字的空白文档很多人第一次在QTextEdit里输入代码时都会有同感这玩意跟记事本差不多毫无生气。其实QTextEdit本身并不负责理解文本内容它只负责把文本按QTextDocument内部的layout规则渲染出来。你往里面塞什么它就显示什么至于关键字该变蓝、字符串该变红它根本没有这个概念。如果你尝试自己实现高亮最容易想到的思路是监听textChanged信号拿到全文然后用正则表达式把每种token的起止位置算出来再做一次setCharFormat。这个思路在大方向上是没问题的但实操起来很快会发现两个大坑——首先大文档下每一次输入都要扫描全文性能断崖式下跌其次QTextDocument的block概念你没有用起来导致光标偏移、格式错位这些毛病层出不穷。一旦文本几千行这个方案基本就废了。1.2 QSyncHighlighter的出现正是为了解决局部重刷的问题Qt对此给出的标准解法是QSyntaxHighlighter。这个类不是你自己去监听文本变化而是让它在文档布局阶段自动介入。我把这个机制理解成按需粉刷文本框中哪些block段落块需要重画高亮器才去处理那些block而绝不会从头到尾重复扫全文。这种按block增量处理的思路才是整个自定义语法高亮的灵魂。理解它之后你再去写规则思路完全不一样——你不再写一个全文扫描的函数而是针对当前这一行文本根据它自己的内容和上一行的状态决定渲染什么格式。1.3 适用场景清单在决定手写之前可以先看看你是否真的需要它。通常这几类需求非常适合自定义高亮规则日志查看器需要把ERROR、WARN、INFO按级别着色顺便高亮时间戳、IP、异常堆栈。小型代码编辑器不想引入重量级第三方编辑器组件只需要支持自己的一门DSL语言。配置文件编辑页INI、JSON、YAML虽然不是代码但合适的颜色能让用户少犯很多错。嵌入式终端/命令行面板命令、参数、输出内容需要分层显示。只要你的需求不属于这些大可不必自己折腾。但一旦属于QSyntaxHighlighter就是那个最稳的起点。2. 高亮器的运行机制它为什么是按块增量扫描2.1 从TextLayout的一次重绘说起QTextDocument不是一整张画布而是由无数个块block组成每个块对应一个段落。当你编辑文本时Qt底层会根据光标位置和文本变化范围只标记受影响的block为需要重新布局。这时QSyntaxHighlighter会收到通知逐个对这些脏块调用highlightBlock()。这里有个容易被忽略的点highlightBlock()是在布局阶段被同步调用的不是你主动触发的一次性扫描。所以你在该函数里做的setFormat操作会影响当前block内部文本的视觉样式同时不会产生额外的开销去处理无关区域。2.2 highlightBlock的输入与输出QSyntaxHighlighter的子类只需要重写一个纯虚函数highlightBlock(const QString text)。参数text就是当前块去掉换行符后的内容。你在这个函数里做所有匹配工作然后调用setFormat(start, count, format)方法告诉文档这个范围用这种格式。这里有一个极其重要的概念setFormat的坐标是相对于当前block的不是相对于整个文档。很多人第一次写时容易把全文匹配的坐标直接传进来结果格式全部错位。我一开始也掉进过这个坑后来才意识到它只认块内偏移。2.3 状态继承上一块的遗志如何传递单行内匹配关键字、字符串其实都很简单真正的难点在于跨行结构比如C风格的块注释/* ... */或者Python中三个引号包裹的跨行字符串。你想让高亮器知道当前这一行正处在多行注释内部就需要利用QSyntaxHighlighter的两个状态机制previousBlockState()上一块解析结束时留下的状态值。setCurrentBlockState(state)为当前块设置状态值传递给下一行。默认状态是0。如果上一行是普通代码当前行接收到的previousBlockState就是0如果上一行是多行注释的中间片段那么上一行结束时我们把它设为1当前行进来时就能查到我正处在一个多行注释内部。这个状态机制是整个高亮规则里最有价值的部分。它本质上是一个极简的有限状态机FSM你可以任意扩展状态值1表示在多行注释内2表示在跨行字符串内3表示在原始字符串内……只要你自己心里有数状态不冲突即可。3. 一个能跑的最小示例从关键字高亮开始3.1 三分法的代码骨架我们先写一个最简单的高亮器目标是把C风格代码里的int、return、void这些关键字着色。这个示例的意义在于先把骨架搭起来后面所有高级规则都是在这个骨架里加内容。#ifndef CUSTOMHIGHLIGHTER_H #define CUSTOMHIGHLIGHTER_H #include QSyntaxHighlighter #include QTextCharFormat #include QRegularExpression class CustomHighlighter : public QSyntaxHighlighter { public: explicit CustomHighlighter(QTextDocument *parent nullptr); protected: void highlightBlock(const QString text) override; private: struct HighlightRule { QRegularExpression pattern; QTextCharFormat format; }; QVectorHighlightRule m_rules; QTextCharFormat m_keywordFormat; }; #endif注释之外真正干活的是highlightBlock这个函数。它做的事情非常直观把当前块的文本取出来。遍历我们注册好的规则列表。每一条规则用正则匹配文本每匹配到一次就按范围应用格式。实现大概是void CustomHighlighter::highlightBlock(const QString text) { for (const HighlightRule rule : std::as_const(m_rules)) { QRegularExpressionMatchIterator it rule.pattern.globalMatch(text); while (it.hasNext()) { QRegularExpressionMatch match it.next(); setFormat(match.capturedStart(), match.capturedLength(), rule.format); } } }这里我用了正则的globalMatch一次性拿到所有匹配项。需要注意match.capturedStart()和capturedLength()是相对于当前text的起点也就是块内坐标这正好符合我们上一节说的规则。3.2 用正则匹配关键字时的两处陷阱写规则时第一个坑是正则的边界匹配。比如你要匹配int如果直接写int那么print里的int也会被匹配上最后把pr[int]染成关键字。解决办法是强制单词边界m_keywordFormat.setForeground(Qt::blue); m_keywordFormat.setFontWeight(QFont::Bold); HighlightRule rule; rule.pattern QRegularExpression(\\b(int|return|void|if|else|while)\\b); rule.format m_keywordFormat; m_rules.append(rule);\b表示单词边界保证int只匹配独立的单词。这里必须用\\b而不是\b因为字符串经过C转义\b在字符串里表示退格字符错误极隐蔽。第二个坑是正则本身的匹配效率。很多人图方便写.*对这个需求其实不是好主意。虽然短小但在高亮每一块时都可能引发大量无谓的回溯尤其行很长时性能会突然恶化。稍后我专门用一节讲性能问题这里先记住预告词尽量用更精确的约束。3.3 QTextCharFormat里到底能调什么QTextCharFormat就是你要应用的格式包。你可以设置前景色、背景色、加粗、斜体、下划线、删除线甚至字体族和大小。我最常用的几个QTextCharFormat format; format.setForeground(QBrush(QColor(0, 128, 0))); // 绿色 format.setBackground(Qt::yellow); // 黄底 format.setFontWeight(QFont::Bold); // 加粗 format.setFontItalic(true); // 斜体 format.setUnderlineStyle(QTextCharFormat::SingleUnderline);有一个小经验高亮规则里尽量不要修改字体族和大小除非你有特殊需求。因为高亮触发时区域内的字体变化会影响文本布局宽度导致行宽抖动尤其是等宽字体下更容易出问题。想给代码上色保持字体统一只在颜色与字重上做变化观感最好。3.4 把高亮器挂载到编辑器上写完类之后挂载就两行auto *textEdit new QTextEdit(this); auto *highlighter new CustomHighlighter(textEdit-document());高亮器构造时接收一个QTextDocument*它就会自动接管这个文档的高亮。你不用存储它的指针只要保证高亮器对象不提前析构就行。实际项目里我一般是把高亮器作为编辑器窗口的成员变量比如m_highlighter这样它生命周期和窗口同步。如果你之后要切换文档也可以调用highlighter-setDocument(otherDoc)。这个动作会断开旧文档、连接新文档并且自动对旧文档进行还原重刷非常省心。4. 多行规则与状态机跨块高亮是自定义高亮的精髓4.1 单行正则解决不了没有结尾的片段现在问题升级如果用户输入了/*但没有输入对应的*/我们依然希望当前行从/*开始到行尾这一段都是注释颜色。更麻烦的是下一行文本comment continues也应该整行是注释颜色直到某一行里出现*/为止。单行正则处理不了这种上一行延续下来的状态因为每一行的正则匹配都是重新从该行文本开始的你根本看不到上一行的文本。这时你就需要利用我们前面讲的状态机了。4.2 用setCurrentBlockState保存解析状态我们来做一个非常经典的多行注释规则。首先约定状态值0非注释状态1注释状态处于多行注释内部在highlightBlock开头先读取上一行的状态bool isInComment (previousBlockState() 1);如果上一行就处于注释内说明当前行是从注释中段开始的。那么我们一开始就可以把从第0个字符到行尾都设置成注释格式。在此基础上再看这一行里有没有*/。如果找到了*/那么*/之前保持注释色之后恢复为普通代码解析同时把当前块状态改为0如果没找到*/整个块都是注释当前块状态保持为1。如果上一行不是注释状态我们就用正则从该行起点去匹配/*一旦匹配到从注释开始位置到行尾都是注释格式如果这个过程中没有出现*/就把当前块状态置为1。这个逻辑画成文字版有点绕代码反而很清楚void CustomHighlighter::highlightBlock(const QString text) { // 先处理跨行注释 const QRegularExpression startExp((/\\*|\\*/)); const QRegularExpression endExp(\\*/); setCurrentBlockState(0); if (previousBlockState() 1) { // 我们正处于注释内先找结束符 QRegularExpressionMatch endMatch endExp.match(text); if (endMatch.hasMatch()) { setFormat(0, endMatch.capturedStart() 2, m_commentFormat); int startPos endMatch.capturedEnd(); applyRulesToText(text, startPos); } else { // 整个块都在注释里 setFormat(0, text.length(), m_commentFormat); setCurrentBlockState(1); } return; } // 非注释状态下寻找注释开始位置 QRegularExpressionMatchIterator beginIt startExp.globalMatch(text); if (beginIt.hasNext()) { QRegularExpressionMatch beginMatch beginIt.next(); setFormat(0, beginMatch.capturedStart(), m_commentFormat); if (beginMatch.capturedStart() beginMatch.capturedEnd()) { // 这里只是为了逻辑演示 ... } // 简化从注释开始位置到行尾按注释处理 ... } }当然我上面把逻辑简化了真实里最好把普通代码部分继续应用其他规则和注释部分应用注释格式分开处理。一个比较舒服的结构是先把文本里可能被注释覆盖的区域找出来把注释格式先应用上再在剩余的安全区间里匹配关键字和字符串。这样写出来的高亮器改动时会避免区域重叠导致的互相覆盖。4.3 一个完整的跨行字符串示例多行注释会了多行字符串基本同理。比如我们要支持Java/C风格的字符串以双引号开头并以双引号结尾但允许跨行虽然真实C不允许但在自定义DSL里很常见那么状态值可以再加一个20普通代码1处于多行注释内2处于多行字符串内在同一行文本里可能同时出现字符串和注释甚至注释里带着字符串字符串里带着奇怪的转义。简单场景下我们可以约定优先级注释优先于字符串。这样处理起来思路是清晰的先判断当前块是否处于注释内或字符串内。如果在注释内只寻找*/。如果在字符串内寻找未转义的。如果都不在从行头开始寻找下一个/*或未转义的谁是先出现的就先处理谁。写这个逻辑时要时刻注意你不要试图在正则里一次性吞掉整段注释或字符串而是把开始-结束分割成两步判断。这样做的好处是不容易出错也方便调试。4.4 状态编码技巧与状态表设计状态值本身是int你可以随意扩展。我有一次写日志高亮器同时需要支持多行JSON和多行模板字符串干脆把状态位拆成二进制位掩码比如第0位代表注释、第1位代表字符串、第2位代表多行原始数据。这样状态值可以叠加上一块可能同时处于注释内且字符串内的情况也能表达出来。不过说实话这样的叠加场景非常少见大多数情况下用几个独立的整数就够了不要过度设计。建议在类内部定一个枚举避免魔法数字enum BlockState { StateNormal 0, StateInComment, StateInString, StateInRawString, };这样可读性高很多后续维护的时候也不会忘了2代表什么。这也是我觉得QSyntaxHighlighter这种机制对大型项目友好的原因——状态机本身很轻扩展起来很有章法。5. 规则多了怎么办设计一套可维护的高亮规则体系5.1 把规则拆成格式表 正则列表当高亮规则越来越多时最忌讳的是在highlightBlock里堆砌一百行if/else和正则匹配。这会让代码完全失控。我的做法是先定义一张静态规则表把每种token类型对应的正则与格式放在一块。比如下面这种结构void CustomHighlighter::setupRules() { // 关键字 HighlightRule keywordRule; keywordRule.pattern QRegularExpression(\\b(int|float|double|char)\\b); keywordRule.format formatStyle(QColor(0, 0, 255), QFont::Bold); m_rules.append(keywordRule); // 数字 HighlightRule numberRule; numberRule.pattern QRegularExpression(\\b\\d\\.?\\d*\\b); numberRule.format formatStyle(QColor(180, 0, 0)); m_rules.append(numberRule); // 单行注释 HighlightRule singleCommentRule; singleCommentRule.pattern QRegularExpression(//[^\n]*); singleCommentRule.format formatStyle(QColor(0, 128, 0), QFont::Normal, true); m_rules.append(singleCommentRule); }我建议把规则初始化放在构造函数或初始化函数里而不是highlightBlock里重复构造否则每次高亮都会new一遍正则性能开销很大。5.2 优先级怎么控制先大范围还是先小范围高亮顺序有个隐性规则后调用的setFormat不会自动覆盖先调用的。实际上同一个位置如果被多次setFormat后写的那一次会覆盖前面设置的样式。也就是说如果你先匹配注释再匹配关键字那么注释里的关键字也会按关键字的样式显示——这显然不是我们想要的。正确的思路是先匹配并渲染小范围的、精细的token如关键字、字符串内容最后再渲染大范围的注释。这样注释这种大范围格式会把之前的内容覆盖成注释样式。换句话说你要让更大范围的规则后执行。为了减少混乱我通常会把高亮流程分成两阶段第一阶段处理跨行状态与注释范围。第二阶段在明确不是注释的区间里按照token粒度逐个应用规则。在第二阶段里不同token之间也可能有冲突比如数字和标识符。我的建议是设置一个优先级权重谁重要谁后执行。通常来说字符串内容优先级最高其次是关键字再其次是数字和普通标识符。5.3 折叠区域、代码块缩进的额外处理高亮字数不是唯一的问题有时候还需配合代码折叠或缩进。Qt高亮器本身不直接负责折叠但你可以借助它的状态值在文档布局时把折叠标记挂到对应的block上。你可以在highlightBlock里解析出当前块的缩进层级然后配合QTextBlockUserData存放额外信息比如这个块是不是函数定义开始它的折叠层级是多少。我自己是在关键字规则里一并处理了如果匹配到function关键字就把这个块的userData创建一个对象并记录层级。这样外部编辑器部件就能根据userData来绘制折叠图标。这块内容官方没有给出生动的开箱方案是需要自己补充工程设计的。5.4 性能大文件的优化经验大文件高亮一旦卡顿几乎都逃不开两个原因正则太激进或者触发了全局重扫。QSyntaxHighlighter本身是增量机制不会全文重扫剩下唯一要优化的就是每条正则的作用时间。我在一个模拟项目X里测试过一段2000行的日志文件如果每条规则都用.*或者嵌套分组高亮一次会卡在半秒甚至一秒肉眼可见的掉帧。改成精确字符类之后基本不可感知。以下几点是实战验证过的尽量少用.*尤其不要让它在长行里多次匹配。正则表达式对象尽量复用不要在highlightBlock里反复new。如果你的语言绝不支持跨行token就不要每次都去检测previousBlockState提前return能省不少事。对于行内只匹配一次的内容用QRegularExpressionMatch match re.match(text);而不是globalMatch后者会更慢。给一个直观的经验值如果单行文本有几百个字符每条规则匹配耗时超过1毫秒那几千行的文档就会非常卡。相反如果你每条规则都控制在几十微秒内2000行文档高亮也就几十毫秒到100毫秒上下属于可接受范围。6. 实战中踩过的坑与最终的调试建议6.1 正则的灾难性回溯这是个性能杀手前面说了性能优化这里要专门展开一个特别常见的坑灾难性回溯。比如你写了类似(.*)*或者(a)这种正则在一个很长的、不匹配的字符串上会造成指数级回溯Qt的QRegularExpression基于PCRE一样会踩这个雷。我自己曾经在配置项规则里写了一个匹配等号后任意内容的正则\s*(.*)$。单行很短时没感觉一旦某行配置特别长几百个字符高亮器会明显卡顿。后来排查发现这个贪婪匹配一直在回溯到行尾才结束。改成\s*([^\n\r]*)之后问题立刻消失。所以排查高亮性能问题时先看规则里有没有嵌套的量词它们是第一嫌疑人。6.2 用setDocument切换文档时别忘了重新高亮有时候你的编辑器会打开多个文件需要切换普通文本文件与代码文件。直接调用highlighter-setDocument(doc)之后Qt会帮忙做一次初始高亮但有时你动态修改了规则或者切换到的是一个应该按照新规则高亮但老状态下没有高亮的文档你可能需要显式调用rehighlight()。rehighlight()会触发所有block的重刷代价较大但它能保证一致性。如果只是某个块内容变了不要主动全局重刷让增量机制自己跑。这也是使用QSyntaxHighlighter的一个重要原则尽量信任它的增量系统而不是凡事都手动干预。6.3 中文与全角字符的匹配问题如果你高亮的语言允许中文标识符或者注释内容包含中文要特别小心正则中的.默认不匹配换行符但可能会匹配中文字符这通常没问题。比较麻烦的是全角括号、中文逗号这些混杂在token里。比如你想匹配一个逗号分隔列表\s*,只能匹配半角逗号如果用户输入了中文逗号就不会命中。我的建议是如果你确定自己的DSL面向中文用户那就把中文标点的匹配单独加到规则里如果面向通用场景保持半角标点的规则就好不要试图兼容所有Unicode变体。否则写出一个正则能匹配各种奇怪的空格和标点性能又是一层负担。6.4 IDE风格的效果主题、字体与暗色适配最后谈谈观感。高亮规则写得再好如果配色不符合场景体验也会很差。在暗色主题下深蓝色关键字几乎看不清在亮色主题下浅灰色注释又会显得过于刺眼。所以我在设计规则的时候会把所有颜色集中在一个集中的地方比如从配置加载而不是散落在各处。一个实用的做法用调色板函数根据编辑器当前主题返回一组styleQTextCharFormat styleByTheme(Theme theme, TokenType type) { if (theme DarkTheme) { switch (type) { case Keyword: return QTextCharFormat().setForeground(QColor(86, 156, 214)); case String: return QTextCharFormat().setForeground(QColor(206, 145, 120)); case Comment: return QTextCharFormat().setForeground(QColor(106, 153, 85)); ... } } ... }这样切换主题时只需要重建规则列表并调用rehighlight所有颜色都会一次性更新不会东一块西一块地漏改。代码编辑器的用户对主题非常敏感这块做好了很加分。6.5 实践下来的一些小技巧根据我个人多次在不同工具里实践有几条经验值得直接抄走高亮器对象的父子关系务必清晰。常见做法是把高亮器作为编辑器窗口类的成员而不是局部变量。在调试阶段可以在highlightBlock里加非常轻量的断言比如确保startcount不超过text长度避免setFormat越界导致崩溃。如果你要实现类似括号匹配高亮那就不能只靠QSyntaxHighlighter了它适合做静态语法着色但括号匹配涉及光标位置计算需要结合额外的事件处理。不需过度设计规则数量。我发现一个实用的编辑器往往只需要15到30条规则超过这个数量后要么是DSL过于复杂要么是规则设计不够抽象。关于调试还有一个我特别想强调的点QSyntaxHighlighter的highlightBlock是在布局阶段被调用的如果你在其中断点单步Qt的滚动与重绘行为会显得停滞这不是程序死了而是布局被阻塞。我第一次调试时误以为死循环了其实只是渐变停顿。遇到这种情况直接使用输出日志而非断点验证更高效。我个人在实际开发中始终把自定义语法高亮当成编辑器工程里可替换组件来要求自己规则表独立、状态机清晰、样式可配置。这样做的回报是当某一天文档类型从C扩展成Python或者从纯日志扩展成Markdown预览时你不需要推翻整个高亮器只需要新增一组规则、调整一下状态值的含义就能平滑切换。这份收益值得一开始就花时间去设计好。