★ FEATURED ARTICLE 简介这份资源面向希望深入掌握 C# WinForms 自定义控件开发的开发者重点解决标准 TextBox 外观单一、难以满足圆角等个性化界面需求的问题。包内共 13 个文件以 8 个 cs 源码文件为主辅以 2 个 resx 资源文件、1 个 settings 配置、1 个 config 及 1 个 csproj 工程文件压缩包约 13KB结构紧凑涵盖自定义控件类、窗体逻辑、设计器代码与程序入口等完整模块。已有 418 人学习下载。通过继承 TextBox 并重写 OnPaint、OnResize 等绘制方法资源演示了如何借助 GDI 绘制圆角边缘并扩展圆角半径、边框颜色、文本对齐等自定义属性同时兼顾设计器支持、绘制性能与不同 DPI 下的兼容性。读者可据此理解自定义控件的封装思路并将其迁移到按钮、面板等界面元素的个性化改造中提升桌面应用的视觉表现与用户体验。1. 从“原生 TextBox 不够用”说起自定义控件到底在解决什么做过 C# Winform 的人几乎都遇到过同一个场景界面上要放一个输入框要求带圆角、带占位提示、聚焦时边框变色、内容为空时显示灰色提示文字、输入非法字符时边框变红。原生TextBox一个都不给你只能在Enter、Leave、TextChanged里堆事件堆到最后代码乱成一团换个窗体还得复制一遍。自定义控件 TextBox 要解决的就是这件事——把输入框的外观、行为、校验逻辑封装成一个可复用、可拖拽、可在设计器里调属性的控件。它适合两类人一类是被重复代码折磨、想抽公共控件的业务开发者另一类是刚接触 GDI 绘制、想找一个难度适中的切入点练手的 Winform 新手。这一章先把“为什么要自定义”讲透后面几章再落到怎么画、怎么调、怎么避坑。原生TextBox是 Windows 公共控件的一层托管包装它的边框、背景、焦点矩形都由系统主题绘制你改BackColor、BorderStyle能动的范围非常有限。BorderStyle只有None、FixedSingle、Fixed3D三个值想要圆角边框没有。想要聚焦时边框从灰变蓝没有。想要占位符.NET Framework时代没有PlaceholderText那是后来.NET Core才补上的。所以自定义控件的核心思路不是“重写一个输入框”而是“继承TextBox接管它的绘制再补上它缺的行为”。继承而不是从Control从零写是因为输入、光标、选区、输入法、剪贴板这些底层逻辑系统已经做得很稳你没必要重造重造反而容易在中文输入法下翻车。这里有个反直觉的结论大部分自定义 TextBox 的 bug不是出在绘制代码上而是出在“什么时候触发重绘”和“属性默认值怎么设”上。画一个圆角矩形本身很简单难的是让它在获得焦点、失去焦点、鼠标悬停、文本变化、只读切换这五种状态下都正确刷新并且不闪烁。新手往往把精力全花在Graphics.DrawPath上结果控件一多就闪、一改属性就卡。所以这篇笔记的路线是先讲清继承体系和绘制入口再给一套能直接抄的最小实现然后重点讲参数怎么设、状态怎么管最后用一整章讲那些只有踩过才知道的坑。2. 继承 TextBox 还是 UserControl选型与绘制入口2.1 两种继承路线的取舍自定义输入框有两条主流路线选错了后面会很难受。第一条是继承TextBox。你拿到的是一个功能完整的输入控件输入、光标、选区、右键菜单、输入法全都有你只需要重写OnPaint系列方法在系统绘制的基础上叠加自己的边框和背景。缺点是TextBox本身是“非自绘”控件它不支持SetStyle(ControlStyles.UserPaint, true)之后完全自己画——你一旦开了UserPaint系统就不再帮你画文本和光标你得自己处理文本渲染中文输入法下的候选框定位会变得很麻烦。所以继承TextBox的正确姿势是不开UserPaint而是用WM_PAINT消息或OnPaint在系统绘制之后补画边框文本交给系统。第二条是继承UserControl里面放一个BorderStyleNone的TextBox外面用Panel或自绘做边框。这条路线的优点是外观完全可控圆角、阴影、图标、清除按钮都好加缺点是你要手动同步内部TextBox的焦点、文本、事件还要处理UserControl本身能获得焦点导致焦点错乱的问题。做复杂输入框带前置图标、带清除按钮、带下拉时这条路更合适做纯文本输入时继承TextBox更省事。我一般的判断标准是只需要改边框和占位提示继承TextBox需要加图标、按钮、多状态装饰用UserControl组合。下面这套最小实现走继承TextBox路线因为它最能体现自定义控件的核心机制也最容易讲清楚绘制入口。2.2 绘制入口与双缓冲继承TextBox后绘制相关的可重写点主要有三个OnPaintBackground、OnPaint、以及响应WM_PAINT。由于TextBox默认不是UserPaintOnPaint在文本绘制之后被调用适合补画边框。但要注意TextBox的OnPaint在某些情况下不会被触发更稳的做法是重写WndProc拦截WM_PAINT先让基类处理再自己画。双缓冲是防闪烁的关键。TextBox默认开启了ControlStyles.OptimizedDoubleBuffer吗不一定取决于父容器和系统设置。稳妥做法是在构造函数里显式设置public class RoundedTextBox : TextBox { public RoundedTextBox() { // 开启双缓冲减少重绘闪烁 SetStyle(ControlStyles.OptimizedDoubleBuffer | ControlStyles.AllPaintingInWmPaint | ControlStyles.ResizeRedraw, true); // 关闭系统默认边框边框由我们自己画 BorderStyle BorderStyle.None; // 预留内边距避免文字贴边 Padding new Padding(6, 4, 6, 4); } }OptimizedDoubleBuffer让绘制先到内存缓冲再一次性输出AllPaintingInWmPaint禁止擦除背景消息单独触发ResizeRedraw保证尺寸变化时重绘。这三个一起开基本能解决大部分闪烁。BorderStyle None是为了不让系统再画一层边框否则你画的圆角边框外面会套一个直角边框非常难看。Padding在TextBox上不是所有版本都生效.NET Framework的TextBox对Padding支持有限更可靠的是用EM_SETMARGINS消息设置左右内边距这个后面避坑章会讲。2.3 用 WndProc 拦截 WM_PAINT 补画边框protected override void WndProc(ref Message m) { base.WndProc(ref m); // WM_PAINT 0x000F系统绘制完文本后我们再补画边框 if (m.Msg 0x000F) { using (Graphics g Graphics.FromHwnd(Handle)) { DrawBorder(g); } } } private void DrawBorder(Graphics g) { g.SmoothingMode System.Drawing.Drawing2D.SmoothingMode.AntiAlias; Rectangle rect new Rectangle(0, 0, Width - 1, Height - 1); int radius _cornerRadius; using (var path CreateRoundedPath(rect, radius)) using (var pen new Pen(_borderColor, _borderWidth)) { g.DrawPath(pen, path); } }WndProc先调base.WndProc让系统把文本、光标、选区都画完然后我们用Graphics.FromHwnd拿到设备上下文补画边框。这里用FromHwnd而不是CreateGraphics是因为在WM_PAINT处理中CreateGraphics可能拿不到正确的裁剪区。SmoothingMode.AntiAlias开抗锯齿圆角才不会有锯齿。CreateRoundedPath是构造圆角矩形路径的辅助方法用四段AddArc加直线拼成半径要限制在min(Width, Height) / 2以内否则路径会自交画出来是乱的。3. 把圆角、占位符、状态色一次做对3.1 圆角路径的构造与半径限制圆角矩形的本质是四条边加四个圆弧。用GraphicsPath拼private GraphicsPath CreateRoundedPath(Rectangle rect, int radius) { var path new GraphicsPath(); // 半径不能超过矩形短边的一半否则圆弧会重叠 int maxRadius Math.Min(rect.Width, rect.Height) / 2; radius Math.Max(0, Math.Min(radius, maxRadius)); if (radius 0) { path.AddRectangle(rect); return path; } int d radius * 2; path.AddArc(rect.X, rect.Y, d, d, 180, 90); // 左上 path.AddArc(rect.Right - d, rect.Y, d, d, 270, 90); // 右上 path.AddArc(rect.Right - d, rect.Bottom - d, d, d, 0, 90); // 右下 path.AddArc(rect.X, rect.Bottom - d, d, d, 90, 90); // 左下 path.CloseFigure(); return path; }AddArc的后两个参数是起始角度和扫过角度角度以 x 轴正方向为 0、顺时针为正。左上角从 180 度开始扫 90 度右上角从 270 度开始右下角从 0 度开始左下角从 90 度开始这样四段弧正好首尾相接。半径限制那两行是血泪经验如果控件高度只有 20 像素你设半径 15圆弧直径 30 超过高度路径会自交DrawPath出来的边框在角落会打结。所以一定要 clamp。3.2 占位符的绘制时机占位符要在“文本为空且没有焦点”或“文本为空”时显示具体看产品要求。常见做法是文本为空就显示聚焦后如果还是空也显示直到用户输入第一个字符才消失。绘制位置要和真实文本对齐否则一聚焦文字会跳。protected override void OnTextChanged(EventArgs e) { base.OnTextChanged(e); // 文本变化时重绘控制占位符显隐 Invalidate(); } private void DrawPlaceholder(Graphics g) { if (!string.IsNullOrEmpty(Text) || string.IsNullOrEmpty(_placeholder)) return; // 用 TextRenderer 而不是 Graphics.DrawString和 TextBox 文本渲染一致 TextRenderer.DrawText( g, _placeholder, Font, new Point(_paddingLeft, _paddingTop), _placeholderColor, TextFormatFlags.Left | TextFormatFlags.VerticalCenter); }这里有个关键点占位符要用TextRenderer.DrawText而不是Graphics.DrawString。TextBox内部用的是 GDI 的TextOut系列TextRenderer也是 GDI 封装两者字体渲染一致DrawString是 GDI字体度量不同占位符和真实文本会出现几个像素的错位聚焦瞬间文字会“跳”一下。TextFormatFlags.VerticalCenter让占位符垂直居中但要注意它居中的是整个行高和TextBox文本基线可能仍有偏差实际项目里我一般用_paddingTop手动微调这个值需要根据字体大小试。3.3 五种状态的配色与切换一个像样的输入框至少有五种状态正常、悬停、聚焦、只读、错误。每种状态对应一组边框色和背景色。用一个枚举加一个状态字段管理private enum BoxState { Normal, Hover, Focused, ReadOnly, Error } private BoxState _state BoxState.Normal; protected override void OnMouseEnter(EventArgs e) { base.OnMouseEnter(e); if (_state BoxState.Normal) { _state BoxState.Hover; Invalidate(); } } protected override void OnMouseLeave(EventArgs e) { base.OnMouseLeave(e); if (_state BoxState.Hover) { _state BoxState.Normal; Invalidate(); } } protected override void OnGotFocus(EventArgs e) { base.OnGotFocus(e); _state BoxState.Error ? BoxState.Error : BoxState.Focused; Invalidate(); } protected override void OnLostFocus(EventArgs e) { base.OnLostFocus(e); _state BoxState.Normal; Invalidate(); }状态切换的核心是每次切换都要Invalidate()否则边框颜色不会变。另一个坑是OnMouseEnter和OnMouseLeave在控件被禁用时也会触发所以状态判断里要加Enabled检查。错误状态优先级最高聚焦时如果处于错误状态边框应该保持红色而不是变蓝这个优先级顺序要在OnGotFocus里体现。3.4 可调属性的暴露与默认值自定义控件要在设计器里能调属性必须带[Category]、[Description]、[DefaultValue]。DefaultValue不只是给设计器看的它还影响ShouldSerialize逻辑和属性面板的加粗显示。[Category(自定义外观)] [Description(圆角半径0 表示直角)] [DefaultValue(6)] public int CornerRadius { get _cornerRadius; set { if (value 0) value 0; if (_cornerRadius value) return; _cornerRadius value; Invalidate(); } } [Category(自定义外观)] [Description(占位提示文字)] [DefaultValue()] public string Placeholder { get _placeholder; set { _placeholder value ?? ; Invalidate(); } }属性 setter 里三件事边界校验、相等判断、触发重绘。相等判断不能省否则设计器批量设属性时会疯狂重绘。DefaultValue要和字段初始值一致否则设计器会认为属性被改过序列化出一堆冗余代码。CornerRadius的负值要 clamp 到 0不能让调用方传负数进来。4. 避坑与排查那些让控件“看起来能用但一用就崩”的细节4.1 输入中文时占位符不消失或光标错位现象用中文输入法打字候选框还没上屏占位符已经消失或者候选框位置偏到控件外面。原因TextChanged在输入法组合期间就会触发此时Text可能已经是组合中的字符也可能还是空行为取决于输入法。解决不要只依赖TextChanged判断占位符显隐改用OnKeyPress或监听WM_IME_COMPOSITION消息在组合开始时强制隐藏占位符组合结束后再根据Text判断。光标错位通常是Padding或EM_SETMARGINS设置不当导致系统计算光标位置时用了错误的左边距。4.2 控件放到 TableLayoutPanel 里边框被裁掉现象圆角边框右边和下边少一条或者圆角被切平。原因DrawBorder用的矩形是Width - 1, Height - 1但TableLayoutPanel的单元格可能给控件留的尺寸和控件实际尺寸差 1 像素导致最外圈画到了裁剪区外。解决把绘制矩形内缩_borderWidth而不是固定 1 像素并且确保Margin至少留出边框宽度。更稳的做法是在OnResize里Invalidate()强制尺寸变化后重绘。4.3 设置 ReadOnly 后背景色不生效现象ReadOnly true时想改背景色表示不可编辑但设了BackColor没反应。原因TextBox在ReadOnly状态下系统会用Control画刷绘制背景忽略BackColor除非BackColor是Color.Empty之外的值且控件不是UserPaint。解决重写OnPaintBackground在只读时自己填充背景protected override void OnPaintBackground(PaintEventArgs e) { if (ReadOnly) { using (var brush new SolidBrush(_readOnlyBackColor)) e.Graphics.FillRectangle(brush, ClientRectangle); } else { base.OnPaintBackground(e); } }注意OnPaintBackground里不要调base之后再填否则会覆盖系统绘制。只读分支直接填非只读分支交给基类。4.4 多个自定义控件同时重绘导致界面卡顿现象一个窗体上放十几个自定义 TextBox滚动或切换标签页时明显卡顿。原因每个控件的Invalidate()都触发一次WM_PAINTGraphics.FromHwnd每次都要拿设备上下文Pen和GraphicsPath每次都在堆上分配GC 压力大。解决把Pen和GraphicsPath缓存成字段在属性变化时才重建Invalidate用Invalidate(Rectangle)限定区域而不是整个控件如果控件不需要透明背景在构造函数里设SetStyle(ControlStyles.Opaque, true)减少背景擦除。4.5 设计器里属性改了但运行时没变现象在设计器属性面板改了CornerRadius设计视图变了但运行起来还是默认值。原因属性 setter 里做了相等判断而设计器序列化时可能先设了默认值再设新值如果新值和字段当前值恰好相等就被跳过了或者DefaultValue和字段初始值不一致设计器没生成赋值代码。解决检查DefaultValue是否和字段声明时的初始值完全一致检查 setter 里的相等判断是否用了比较引用类型字符串要用string.Equals。最笨但有效的办法是在 setter 里加Console.WriteLine确认设计器到底有没有调进来。5. 进阶把校验、动画和复用做到位5.1 用 ErrorProvider 思路做内置校验自定义控件如果只画个红框校验逻辑还是散落在窗体里那封装就不彻底。更好的做法是给控件加一个ValidationRule委托属性控件自己在Validating事件里调用规则根据返回值切换错误状态。[Category(自定义行为)] [Description(校验委托返回 null 表示通过返回字符串表示错误信息)] public Funcstring, string ValidationRule { get; set; } protected override void OnValidating(System.ComponentModel.CancelEventArgs e) { base.OnValidating(e); if (ValidationRule null) return; string error ValidationRule(Text); if (error ! null) { _state BoxState.Error; _errorMessage error; Invalidate(); e.Cancel true; // 阻止焦点离开 } else { _state BoxState.Normal; _errorMessage null; Invalidate(); } }e.Cancel true会阻止焦点离开控件配合AutoValidate设置可以实现“不通过就不让走”。但要注意Cancel之后用户点关闭按钮也会被拦需要在窗体层面处理FormClosing时临时关掉校验。ValidationRule用Funcstring, string而不是接口是为了让调用方用 lambda 一行搞定降低使用成本。5.2 聚焦边框的渐变过渡直接切颜色太生硬可以做一个简单的颜色插值动画。用Timer每 15 毫秒插值一次从当前色向目标色逼近差值小于阈值就停。private Color _currentBorderColor Color.Gray; private Color _targetBorderColor Color.Gray; private Timer _animTimer; private void StartColorTransition(Color target) { _targetBorderColor target; if (_animTimer null) { _animTimer new Timer { Interval 15 }; _animTimer.Tick (s, e) { _currentBorderColor Lerp(_currentBorderColor, _targetBorderColor, 0.25f); if (ColorDistance(_currentBorderColor, _targetBorderColor) 3) { _currentBorderColor _targetBorderColor; _animTimer.Stop(); } Invalidate(); }; } _animTimer.Start(); } private static Color Lerp(Color a, Color b, float t) { return Color.FromArgb( (int)(a.R (b.R - a.R) * t), (int)(a.G (b.G - a.G) * t), (int)(a.B (b.B - a.B) * t)); }Lerp的t取 0.25 表示每次向目标靠近四分之一视觉上是先快后慢的缓出效果。ColorDistance用 RGB 欧氏距离判断是否足够接近阈值 3 是人眼基本看不出差别的范围。动画期间每次Tick都Invalidate所以控件数量多时动画要慎用或者只在聚焦状态做动画悬停不做。5.3 把控件打包成可复用的类库单个.cs文件复制来复制去不是长久之计。正确做法是建一个Class Library项目把控件编译成 DLL其他项目引用。打包时注意几点目标框架要和主项目一致.NET Framework的 Winform 控件不能直接给.NET 6用AssemblyInfo里加上[assembly: CLSCompliant(true)]保证跨语言可用如果控件用到了设计器支持要确保DesignTimeVisible和ToolboxItem特性正确否则拖不进工具箱。打包项建议值说明目标框架与主项目一致跨大版本不兼容输出类型类库不要用控制台XML 文档勾选生成属性提示能显示强名称签名按需需要放 GAC 才签工具箱图标可选用 16x16 bmp5.4 一个我反复用的调试习惯自定义控件最难查的不是崩溃是“画得不对但程序不报错”。我的习惯是在DrawBorder开头加一个条件断点式的调试开关控件上按住Ctrl右键时用g.DrawRectangle把ClientRectangle和实际绘制矩形都画出来一眼就能看出是尺寸算错还是裁剪问题。这个开关只在DEBUG编译下生效发布版自动去掉。另外Graphics的ClipBounds和VisibleClipBounds在排查裁剪问题时比看代码有用得多遇到边框被切先打印这两个值比猜快十倍。这套东西我从最早一个项目里为了统一输入框样式抽出来后来陆续加了校验、动画、图标前后改了七八版。最大的教训是别一上来就追求功能全先把“正常、聚焦、错误”三个状态的边框画对、刷新对再往上加东西。状态机没理清就加动画最后一定是各种状态互相覆盖改一个坏一个。希望帮到你。本文还有配套的精品资源点击获取
阅读完成 · 觉得有帮助？
