简介这是FastColoredTextBox开源高亮代码文本框的中文修正版V2面向需要在C#、HTML等场景下使用代码高亮与自定义显示模式的中文.NET开发者。原版组件在中文双字节字符显示、光标定位以及多个Style叠加显示时存在明显错位本版将其集中修复并附上完整源码方便做二次集成或排错研究。压缩包共463个文件核心是125个C#源文件配合61个resx资源文件、40个vb文件以及dll、png、gif等编译产物与界面素材整体大小约17.01MB工程内包含Tester示例、配置文件和说明文档结构清晰适合直接打开对照学习。目前已有1763人学习下载对已经使用或打算引入FastColoredTextBox来开发中文文本编辑器、代码高亮界面的项目而言这份修正版既能提供可运行的控件实现也能作为排查中文显示异常与样式重叠问题的参考方案实用性很强。1. FastColoredTextBox 中文修正版V2为什么一个开源编辑器控件值得动手改三处源码做 WinForms 工具链的开发者大概率都遇到过这个场景项目里需要一个轻量的代码编辑器要语法高亮、要自动缩进、要行号但又不想拖一个几十 MB 的 IDE 组件进来。FastColoredTextBox 是这个场景里最常见的答案——一个开源、底层基于 RTBRichTextBox高度封装的编辑器控件一个 DLL 拖进去就能用高亮、自动完成、折叠、书签全都自带。但真正把中文文本贴进去之后问题就接踵而至中文显示发虚、光标点到第二行结果落在第三行、折叠区域的样式渲染成一团黑块。这不是控件坏了而是它内部默认按等宽西文字符的模型处理每个字符CJK 字符的宽度、光标映射、样式区间在默认代码里根本没有被正确对待。这个“中文修正版V2”要解决的正是这三件事修复中文显示、修复光标位置、修复样式错位。V1 版本能跑通基础的中文高亮但 IME 输入状态下的光标漂移和换行后的缩进错位仍然存在V2 的改动集中在这三个点上。本文不适合只想“下载替换 DLL”的调用方适合需要自己编译、自己维护控件源码的开发者——你要改的不只是几个 if 判断而是理解这个控件从字符索引到屏幕坐标的整套换算逻辑然后才能在你自己的项目里把这些修复用对。2. 先搞清楚这个控件的中文问题根源字符宽度、行高、像素偏移2.1 为什么默认版本里中文显示看起来“虚”且错位FastColoredTextBox 的渲染核心在Range和TextSelection这套体系里最终绘制走的是 GDI 的Graphics.DrawString。默认的字符宽度算法是拿每个字符的CharWidth去累计行宽而这个 CharWidth 的缓存是基于FontCharSet和当前字体算出来的。英文字符每个 7 像素、等宽字体里每个 14 像素这一套在纯西文下没问题但中文字符在该控件的默认字体设置里往往走的是系统字体回退实际宽度和缓存值不一致于是出现两个现象字符之间重叠或间距过大、行末换行位置提前或延后。另一个更隐蔽的问题是行高。控件默认把行高设定为字体高度的 1.2 倍左右英文行高够用但中文字符在多数字体下的实际占用高度接近甚至超过这个倍数于是滚动到文本中部时会出现“行内容被截断、下一行内容漏出”的显示错位。修正版的第一个核心改动就是给 CJK 字符单独走一次宽度测量并在行高计算里叠加 CJK 字符的上下留白。// 修正版 V2 中的字符宽度取法优先走 TextRenderer而不是 GDI 的 MeasureString protected int GetCharWidth(char c, Font font) { if (c 0x2E80 || (c 0x9FFF c 0xF900)) // 非 CJK 区间走原有缓存 return base.GetCharWidth(c, font); // CJK 字符按东亚宽字符处理实际测量一次 string s c.ToString(); Size sz TextRenderer.MeasureText( s, font, new Size(int.MaxValue, int.MaxValue), TextFormatFlags.NoPadding | TextFormatFlags.SingleLine ); return sz.Width; }注意这里用TextRenderer.MeasureText换掉了默认的MeasureString。原因很简单MeasureString是 GDI 的 API返回的宽度包含字体内边距internal leading算出来的值偏大而TextRenderer走 GDI 的DrawText逻辑更贴近屏幕实际像素。它这个NoPadding标志位很关键去掉它依然会有微小的多出偏差叠加在几百个字符的行里就变成肉眼可见的右边界错位。2.2 行高方案从固定倍数到动态测高修正版对行高的处理不是单纯加常量而是按行内最大字符高度动态算。控件默认的LineInterval是一个固定值由服务端配置或构造参数指定一个整数值。中文文本行里如果夹杂了全角符号或生僻字这个固定值就不够用。// 修正版 V2 的 LineHeight 计算 protected internal int CalcLineHeight(Font font, int lineInterval) { int baseHeight Math.Max(font.Height, 16); if (IsCjkLine) { // 中文行统一加高避免底部贴边 baseHeight 2; } return baseHeight lineInterval * 2; }IsCjkLine这个标志是修正版新加的在InsertText和ReplaceLine时扫描一遍行内字符只要命中了 CJK 统一的区段就置位。这个做法的代价是插入大段文本时多了一次 O(n) 扫描但对 UX 的提升很明显——滚动时不再出现文字被半个半个截断的情况。2.3 选型提醒什么场景才需要动源码不是所有用 FastColoredTextBox 的项目都有必要升级到修正版。如果你的编辑器只是输入英文代码、偶尔在注释里有一两个中文官方原版的表现是可以接受的。但如果你做的是一个面向国内用户的 SQL 编辑器、模板配置编辑器、脚本调试面板中文是主要输入内容那么这三个修复宽度、行高、光标映射不做产品在用户手里就是“看起来不太对”的廉价感。另外提醒一句FastColoredTextBox 不是唯一选择像 AvalonEdit 这类基于 WPF 的控件在中文支持上天然好一些但如果你被 WinForms 技术栈锁住或者有大量既有业务代码绑定在 FastColoredTextBox 的Range、TextChanged事件模型上迁移成本会比你做三处源码修改的成本高得多。这个修正版 V2 的价值就在这里——不迁移框架只修正核心算法。3. 修复光标位置CharToPos 与 PosToChar 的中文双宽改造3.1 光标漂移的本质是索引到坐标的双向映射失效FastColoredTextBox 内部处理文本位置时统一走Place结构行和列但鼠标点击、光标移动时要做CharToPos字符索引转像素坐标和PosToChar像素坐标转字符索引两个转换。原版这两个方法的实现基于“每个字符等宽”的假设用charIndex * charWidth做线性映射。对双宽的中文字符这种线性映射必然出错点在第 10 个字符的位置可能实际落点在第 12 个字符因为前 9 个字符里有 3 个中文各自走了两个字符位宽而像素宽度却按单字符累加。修正版 V2 的做法是把这两处映射全部替换成“逐字符累加”并且对中文按双宽步进对英文按单宽步进。// CharToPos 修正逐字符累加CJK 按双宽步进 public Point CharToPos(int charIndex) { int x 0; int y 0; string lineText GetLineText(CurrentLine); int posInLine charIndex; for (int i 0; i posInLine; i) { if (i lineText.Length) break; char ch lineText[i]; x IsCjkChar(ch) ? GetCharWidth(ch, Font) * 2 : GetCharWidth(ch, Font); } return new Point(x, y); }这段代码取消了原版的乘法公式charIndex * charWidth换成循环累加。性能上弱一些但正确性上彻底解决了中英混排时的落点偏移。注意这里IsCjkChar判定的区段不能只收窄到常用汉字还要覆盖全角标点U3000 到 U303F 区间内的《》「」【】等CJK 兼容/扩展现UF900 到 UFAFF、U20000 以上全角数字和字母UFF01 到 UFF5E漏掉任意一类都会在对应字符处产生半个字符宽度的偏移。3.2 PosToChar 修正反向映射和二分查找PosToChar是鼠标点击定位的反向操作用户点击行内某个像素位置控件需要算出点击的是第几个字符。原版用pixelX / charWidth取整修正版改成累加比较// PosToChar 修正累加比较光标停在中文字符的中间偏左 public int PosToChar(Point point) { string lineText GetLineText(CurrentLine); int x 0; for (int i 0; i lineText.Length; i) { char ch lineText[i]; int w IsCjkChar(ch) ? GetCharWidth(ch, Font) * 2 : GetCharWidth(ch, Font); if (point.X x w / 2) return i; x w; } return lineText.Length; }注意这里用了point.X x w/2做中分判断点击位置落在字符左半部分时定位到当前字符落在右半部分时定位到下一个字符。对中文字符双宽字符的横向范围大这个中分判断比原版的“过一半就算下一个字符”更符合用户直觉。实测下来用户在中文行内点击选词的成功率明显高于原版。还有一个容易忽略的坑PosToChar在很多地方被用于计算“行尾点击行为”——用户点击行尾右侧空白时原版会定位到最后一个字符修正版需要判断point.X 行累加总宽度时直接返回lineText.Length否则点击行尾后光标会停在最后一个字符前面。3.3 光标绘制位移ImeMode 与字符宽度状态光标漂移的第二类问题是 IME 输入时组合字符串composition string的显示位置和光标位置不一致。WinForms 的 IME 组合窗口默认跟随光标坐标而中文输入法的候选框若出现在错误位置本质原因是控件上报给 IME 的COMPOSITIONSTRING位置不对。修正版的做法是重写OnGotFocus和WndProc中的WM_IME_STARTCOMPOSITION和WM_IME_COMPOSITION消息处理在 IME 组合期间强制设置候选框位置到当前CharToPos计算出的插入符坐标并同步修改IMContext的字体避免组合字符串在控件的字体渲染下显示成方块。// 修正版 V2 的 IME 光标跟随 protected override void WndProc(ref Message m) { if (m.Msg 0x010D) // WM_IME_STARTCOMPOSITION { Point caretPos CharToPos(Selection.Start.CharIndex); IntPtr hIMC ImmGetContext(Handle); COMPOSITIONFORM cf new COMPOSITIONFORM(); cf.dwStyle CFS_POINT; cf.ptCurrentPos new POINT(caretPos.X, caretPos.Y); ImmSetCompositionWindow(hIMC, ref cf); ImmReleaseContext(Handle, hIMC); } base.WndProc(ref m); }这里ImmGetContext、ImmSetCompositionWindow是从imm32.dll导入的 Win32 API。原版控件没有做这一步导致中文输入法在控件内的候选框总是显示在屏幕左上角或上一行位置。V2 里这段代码配合前面的CharToPos修正一起工作IME 组合窗口的位置跟随实际插入符不再出现输入到第 20 行但候选框飘在第一行的怪象。3.4 翻车记录修改后光标不闪烁了我在某个拿到 V2 修改版的模拟项目里遇到一个副作用光标变成“点击后闪一下就不再闪”的状态。排查后是WndProc里拦截WM_IME_STARTCOMPOSITION后没有调用base的Focus相关消息转发导致控件的内部定时器负责光标闪烁的Timer被中断。解决方法是在WndProc里拦截 IME 消息时先base.WndProc(ref m)再处理 IME 逻辑而不是直接吞掉消息。这个顺序问题在官方文档查不到只能靠断点一个一个试出来。4. 修复样式错位折叠区块、语法高亮与自动换行的三类错位4.1 高亮样式错位的第一个来源折叠区块的字符索引偏移样式错位最明显的表现是折叠某个代码块后下一段文本的高亮颜色“串”到了不该着色的地方。根因在于折叠功能实现的基础是Foldings列表里存了Start和End的Place索引而折叠后控件显示的是“替换文本”通常是一个带下划线的...或符号。原版在计算折叠替换文本的样式时直接用了被替换区间的起始字符样式如果这个起始位置刚好落在一个双宽中文区域内替换文本的宽度就按单字符算显示出来就是半个字符宽的占位符以及后续高亮整体偏移若干像素。修正版 V2 在折叠区块的 text replacement 逻辑里对End索引做了一次字符宽度校准折叠替换文本的实际像素宽度 被折叠范围内所有字符的累加像素宽度而不是按替换文本字符数乘默认字宽。// 折叠替换文本的宽度校准 internal int GetFoldedBlockWidth(Range foldedRange) { Line lineStart foldedRange.Start.iLine; Line lineEnd foldedRange.End.iLine; int totalWidth 0; for (int li lineStart; li lineEnd; li) { string lineText GetLineText(li); foreach (char ch in lineText) { totalWidth IsCjkChar(ch) ? GetCharWidth(ch, Font) * 2 : GetCharWidth(ch, Font); } } return totalWidth; }这段代码的代价是每次折叠渲染都要遍历一遍折叠区间内的所有字符折叠大段代码时会有一个肉眼可感知的卡顿。我一般会在GetFoldedBlockWidth外面套一层缓存按折叠区块的起始位置哈希TextChanged或Foldings变更时自动失效。这样极端情况下也不会在每次Paint时都遍历一次几百行的代码区间。4.2 高亮样式错位的第二个来源Style 索引丢失FastColoredTextBox 的语法高亮核心是SyntaxHighlighter通过正则表达式或词法分析给Range设置样式索引。原版的样式范围Range.SetStyle(StyleIndex)是基于字符索引推进的如果StyleIndex应用区间内遇到中文字符样式推进的步长和文本索引的步长不一致就会出现“高亮区域少一个字符”或“多高亮一个字符”。修正版 V2 在这里的定义是所有样式范围的计算基准统一改为Place结构即(iLine, iChar)的二元组而不是(iChar)的纯索引。理由是Place天然能承载“行 列”双重信息在跨行高亮时不会把上一行的末尾字符算进下一行开头。// 样式区间基于 Place 推进中文双宽不影响区间边界 public static bool InRange(Place pos, Place start, Place end) { if (pos.iLine start.iLine || pos.iLine end.iLine) return false; if (pos.iLine start.iLine pos.iChar start.iChar) return false; if (pos.iLine end.iLine pos.iChar end.iChar) return false; return true; }这个InRange方法被Range.GetStyleIndex调用负责判断某个字符是否在一段高亮区间内。原版用的是charIndex startChar charIndex endChar的线性判断遇到折叠产生的新文本比如折叠替换符...就会串位。改为Place判断后折叠替换符可以作为一个独立的Place存在不再干扰被折叠区域的字符索引。4.3 自动换行后样式“断片”换行符与 CJK 宽度耦合自动换行WrapMode在中文长文本里几乎必开但开了换行之后样式错位的概率陡增。原因是换行的断点算法基于CharToPos的像素宽度累加当 CJK 字符宽度被正确放大后同一行能容纳的字符数变少换行点前移。如果此时高亮区间已经按旧宽度算好换行后的第二行第一个字符可能被错误的高亮区间命中或漏掉。修正版 V2 的换行断点算法必须和样式推进共享同一个宽度缓存否则两边宽度口径不一致样式必然错位。具体做法是换行断点计算时一律查GetCharWidth缓存修正版新增并且断点只在空格或标点处优先断开不在 CJK 字符中间截断。// 换行断点优先在空格/全角标点处断行避免从 CJK 字符中间截断 int BreakLine(Line line, int maxWidth) { int width 0; int lastSafeBreak -1; for (int i 0; i line.Text.Length; i) { char ch line.Text[i]; int w IsCjkChar(ch) ? GetCharWidth(ch, Font) * 2 : GetCharWidth(ch, Font); if (width w maxWidth) { if (lastSafeBreak 0) return lastSafeBreak; return i 0 ? i - 1 : 0; } width w; if (char.IsWhiteSpace(ch) || IsCjkPunctuation(ch)) lastSafeBreak i; } return line.Text.Length; }这里的lastSafeBreak记录最近一个安全的断点位置空格或全角标点后。如果行尾即将超出maxWidth优先回到这个安全断点能够避免“一个汉字被拦腰截成两半”的渲染局面。翻车经验不要把char.IsWhiteSpace换成ch 否则全角空格U3000会被忽略中文缩进场景下换行点全部无效。4.4 样式错位的经典现象中文注释吃掉后面的代码高亮修正版 V2 拿到的第一个典型 issue 是某开发者贴入一段带中文注释的配置文本注释后面的字符串高亮全部失效。排查代码后发现问题不在高亮逻辑而在Comment样式的StyleIndex在TextChanged增量更新时ChangedRange包含了中文注释后SyntaxHighlighter重新解析的Range在字符索引上比实际少了 2两个中文注释符导致后续所有SetStyle的区间整体前移。修正版 V2 的HighlightingChanged事件里对ChangedRange.Start做了 Place 对齐如果Start落在 CJK 字符的第二个半宽位置上自动回退一格保证后续高亮区间起步正确。5. 避坑与常见问题排查V2 修改后容易踩的五个坑5.1 中文双宽导致光标跳到行尾但点击选择又正常现象光标定位不准按键盘左右键时光标直接跳到行尾或行首但鼠标点击选择文本却是正确的。原因左右键移动逻辑走的是Place步进Place的iChar按字符索引 1 步进这没问题但方向键处理后的滚动逻辑走了CharToPos而某个地方的CharToPos调用没有走修正版的重写还在用原来的等宽乘法。解决全局检索项目里所有调用CharToPos和PosToChar的地方确认全部走修正版的方法。FastColoredTextBox 内部有好几处对这两个方法的直接调用如果只改了核心类而漏掉了某些TextSource或Line相关类里的调用点就会出现“部分正确、部分错误”的诡异现象。5.2 中文字符在行内显示宽度正常但复制出去粘贴到记事本宽度不对现象编辑器内显示排列整齐但把一段中英混排文本复制到外部编辑器后对不齐了。原因修正版改的是渲染层的宽度计算Copy操作复制的是Text纯字符串不含任何宽度信息。外部编辑器按自己的字体和宽度算法渲染必然对不齐。解决这不是 bug不用改。如果确实需要复制保留对齐的格式用Copy时带上每个字符的CharWidth元数据生成等宽空格填充。但大多数场景下用户期望的是“复制纯文本”不要自作主张加入额外空格。5.3 大文件滚动预览卡顿定位到某一行时延迟明显现象修改 V2 后打开一个几千行的中文日志文件滚动到底部时 PC 风扇狂转滚动停滞后才定位。原因CharToPos改成逐字符累加后每次调用都是 O(n)滚动时每帧要调用几十次累积下来占用显著。解决给逐字符累加加缓存。在Line类里存一个widthCache数组记录每一行的累计宽度前缀当Text或Style变更时清除该行缓存。这样CharToPos的复杂度从 O(n) 降到 O(1)查前缀和数组。// 行前缀宽度缓存减少重复累加计算 int[] widthPrefix; public void InvalidateWidthCache() { widthPrefix null; } int GetCharX(int charIndex) { if (widthPrefix null) { widthPrefix new int[Text.Length 1]; for (int i 0; i Text.Length; i) { char ch Text[i]; widthPrefix[i 1] widthPrefix[i] (IsCjkChar(ch) ? GetCharWidth(ch, Font) * 2 : GetCharWidth(ch, Font)); } } return widthPrefix[charIndex]; }5.4 中文缩进用全角空格行首看起来没对齐现象用户在编辑器里用中文输入法打出全角空格来缩进V2 修正版里行首显示时左边有一段空白但看起来比半角空格缩进的对齐位置偏左。原因全角空格的像素宽度按双宽处理了但很多用户预期的“全角空格”在视觉上和两个半角空格对齐。修正版的双宽算法下全角空格宽度 2 × 半角空格宽度理论上是对的但系统回退字体里全角空格可能实际渲染宽度略小于两个半角空格拼合。解决在全角空格的特殊处理里GetCharWidth后额外加 1 像素补偿。这不是通用方案建议在设置里提供“全角空格对齐模式”开关让用户按自己屏幕字体微调。5.5 IME 候选框位置正确了但候选框内中文显示成方块现象V2 修复了候选框跟随光标的位置但候选框内的中文文字是方块豆腐块无法正常显示。原因IME 候选框的字体由ImmSetCompositionFont控制默认继承控件的字体设置。如果控件的字体设置成了某款不含中文的等宽字体比如 Courier NewIME 候选框里的中文字符就会因字体缺字而显示成方块。解决在WM_IME_STARTCOMPOSITION处理时同时调用ImmSetCompositionFont将字体改成包含中文回退的字体列表。LOGFONT lf new LOGFONT(); lf.lfCharSet DEFAULT_CHARSET; lf.lfFaceName Microsoft YaHei; // 微软雅黑包含完整中文字形 ImmSetCompositionFont(hIMC, ref lf);注意lfFaceName不能设置成空字符串否则 IME 会使用系统默认字体在某些精简系统上依然没有中文字形。最稳妥的是直接用SystemFonts.MessageBoxFont的字体名这个字体在绝大多数 Windows 系统上都能正确显示中文。6. 验证修正效果一个最小自动化测试与三个手动验证场景对这类 UI 控件的修正自动化测试只能验证“索引映射”和“宽度缓存”这类纯逻辑真正的外观一致性还是需要手动验证。我会在每次修改后跑一遍下面这个最小基线测试把回归风险控制在半小时内。// 修正版基线测试验证中文双宽的宽度累加结果 [TestMethod] public void ChineseCharWidth_Accumulation_ShouldMatchManualCalcuation() { var editor new FastColoredTextBox(); editor.Text a中b; editor.Font new Font(Microsoft YaHei, 10f); int widthA editor.CharToPos(1).X - editor.CharToPos(0).X; int widthCN editor.CharToPos(2).X - editor.CharToPos(1).X; int widthB editor.CharToPos(3).X - editor.CharToPos(2).X; Assert.IsTrue(widthA 0, 英文字符宽度必须大于0); Assert.IsTrue(widthCN widthA * 2, 中文字符宽度必须近似等于两个英文字符宽度); Assert.IsTrue(widthB 0, 后跟英文字符宽度必须大于0); }这个测试断言的核心是“中文宽度 2 × 英文宽度”它验证的不是某个具体像素值而是双宽模型的正确性。如果某次修改把GetCharWidth或IsCjkChar的判定区间弄错了这个断言会立刻失败。三个手动验证场景第一个是 IME 输入定位。新建一个编辑器实例输入 5 行中文将光标定位在第 4 行第 10 个字符打开中文输入法输入两个汉字确认候选框出现在光标附近而不是屏幕左上角。输入完成后光标必须停留在最后一个输入字符的右侧。这个场景专门验证WndProc里的 IME 消息处理和CharToPos的实时性。第二个是混合文本点击定位。粘贴一段中英混排的代码比如中文字符串里的 SQL 语句连续点击不同位置观察光标是否总是在字符间隙处。用鼠标拖动选择时选中区域的起点和终点是否与视觉一致。这个场景验证PosToChar的中分判断是否顺手——如果边缘位置出现光标落点偏差半个字符多半是w / 2的取整方向问题。第三个是折叠与展开回归。先折叠一个包含中文注释的函数再展开检查折叠替换文本的占位符是否对齐、展开后高亮颜色是否恢复到折叠前。这个场景验证GetFoldedBlockWidth和InRange的Place判断是否破坏了原有折叠状态。我的个人习惯是每次编译完修正版 DLL 后先用这个测试脚本跑两遍再开一个 WinForms Demo 手动过三个场景。全部过了才往项目里集成。这套流程走下来最耗时的其实不是改代码而是排查“改了 A 处导致 B 处隐性失效”的连锁反应——比如给CharToPos加了缓存后忘了在TextChanged里InvalidateWidthCache结果只在输入新文本时报错滚动和点击都正常。这类问题靠自动化测试发现不了只能靠系统性的手动验证。我把这个经验固化成了修正版 V2 的四个字每次只改一个点改完立即验证一条链路不要一次性动三处再慢慢排查。希望帮到你。本文还有配套的精品资源点击获取