简介一份面向C# WinForm开发者的自定义控件示例聚焦于创建带圆角效果的TextBox。通过继承System.Windows.Forms.TextBox利用GDI重写OnPaint绘制圆角边框并预留边框颜色、圆角半径等可调属性适合需要美化桌面应用输入框或学习控件封装的中级.NET开发者。压缩包共13个文件包含8个C#源码、2个resx资源文件以及settings、config和工程文件整体仅13KB其中cs文件涵盖程序入口、窗体逻辑与自定义控件类resx存储界面资源config与settings管理运行参数结构精简便于按模块查阅和移植。示例还兼顾了GDI绘制效率及不同DPI下的显示兼容性可直接借鉴到实际项目中。目前已有413人学习下载资源以MyTextBox.cs为核心完整展示了继承、重写、属性封装与设计器支持的实现思路并通过Form1示例演示控件的挂载和动态调整能帮助读者系统掌握WinForm自定义控件的关键开发步骤。1. 为什么要自定义TextBox从一次真实的界面需求说起先说个我自己的经历。前两年做一套工控上位机的时候客户提了一堆界面要求登录框要有灰色提示文字水印输入非法字符直接拦掉鼠标点进去边框要变色最好还能来点圆角。我打开VS拖了个原生TextBox越看越别扭——那个年代感十足的灰色边框和整体深色主题完全不搭。这时候你要么去网上找第三方控件库要么自己动手写一个。第三方库的问题在于体积大、授权不透明、样式风格不一定跟你的项目统一。而且很多时候你只需要一两个小功能为了这点功能引一个几十MB的库实在不划算。所以自己写自定义控件就成了最现实的选项这也是C# Winform开发者绕不开的一条路。这篇文章要聊的就是基于C# Winform做自定义TextBox控件的完整套路。包括继承内置TextBox还是从零自绘、怎么让水印和边框颜色真正生效、怎么限制输入内容、怎么处理圆角和设计器属性以及我实际操作中踩过的各种坑。适合刚接触Winform自定义控件的开发者也适合做上位机、管理系统、工具类软件时被界面问题恶心到的朋友。先说结果写一个带有水印、边框高亮、输入限制的自定义TextBox核心代码在一两百行左右熟练之后二十分钟就能搞定。但它牵涉到的Winform消息机制、重绘机制、设计器交互理解了之后你自己就能举一反三扩展出任何想要的效果。2. 方案选型继承、组合还是自绘2.1 三种常见做法的利弊做自定义文本框业内主要有三条路第一继承TextBox然后重绘。这种方案改动最小控件内部的消息处理、光标逻辑、选择逻辑、右键菜单全都保留你只需要在系统绘制的基础上叠加自己的绘制逻辑。我的建议是没有特殊需求时优先选这个方案。实现成本低后期维护也轻松。第二用UserControl把TextBox包起来。思路是新建一个用户控件拖一个TextBox进去外面再放Panel画边框之类的外围元素。这种方式适合做复杂组合控件比如带图标的搜索框带清除按钮的输入框。缺点也很明显内部TextBox和外部壳需要处理焦点传递、事件转发、键盘消息代码量一点不比继承少而且内部TextBox的样式细节你依然要单独设置。第三从Control基类完全自绘。理论上你可以做出任何想要的效果但代价是文本框的底层行为全部要自己实现光标闪烁、文本选择、IME输入、滚动、复制粘贴、撤销重做……工作量指数级上升。除非你要做的是一个极其特殊的输入控件否则完全不推荐。三种方案的对比我整理成了一个表格方便你选型时直接看方案实现成本功能保留适合场景维护难度继承TextBox重绘低全部保留水印、边框、输入限制、圆角低UserControl组合中需手动转发带图标、带按钮的复合输入框中Control完全自绘高全部重建特殊样式的输入控件高2.2 为什么我最终选了继承TextBox以我要做的水印边框高亮输入限制为例逐项分析的话会发现水印本质上是在文本框没有内容时多画一行文字边框高亮是在焦点事件里改变颜色并重绘输入限制是在按键事件里拦截非法字符。这三个需求全都建立在TextBox原有功能之上没有任何一个要求推翻原有行为。所以从Control自绘是典型的高射炮打蚊子。用UserControl组合呢又会引入焦点在壳上还是在内层TextBox上这种头疼问题。继承TextBox之后控件本身就是一个TextBox所有事件、属性、行为天然存在额外增加的只是你画上去的那部分内容。另外还有一个隐藏优势继承方式写出来的控件在设计器里会自动显示为TextBox类型工具箱拖拽、属性面板修改、运行时布局一切照旧。这对团队协作很重要——同事拿过去用的时候不需要额外学习任何新接口。3. 动手之前必须搞懂的三个核心机制3.1 为什么TextBox的OnPaint方法不生效这是很多初学者自定义TextBox时遇到的第一个拦路虎。你以为重写OnPaint然后画点什么就行了实际运行起来却毫无反应。原因在于TextBox底层是包装了系统原生EDIT控件它的绘制不是由OnPaint驱动的普通情况下根本不会触发OnPaint。要让OnPaint生效需要在构造函数里设置一个样式SetStyle(ControlStyles.UserPaint, true);这个标志位告诉系统这个控件要自己绘制不要再走原生绘制流程。但代价是原生TextBox的背景色、边框、选中高亮等很多行为也会一并交给你的绘制逻辑你得自己补回来。如果你只是想在水印这种附加层上做文章其实有更轻的路子重写WndProc拦截WM_PAINT消息在原生绘制完成之后追加自己的绘制。这样原生行为完全不受影响只是最后在画面上盖了一层内容。我会在下一节详细说这两种方式分别怎么写。3.2 WndProc与消息机制自定义控件的真正入口Winform控件的所有底层行为本质上都是Windows消息驱动的。鼠标点击、键盘输入、绘制请求、焦点变化全部以消息的形式穿过WndProc方法。重写WndProc相当于在消息到达系统默认处理逻辑之前或者之后插入你自己的逻辑。protected override void WndProc(ref Message m) { base.WndProc(ref m); // 在这里检查消息类型追加你的处理 }对于自定义TextBox你主要关心几类消息WM_PAINT绘制、WM_NCPAINT非客户区绘制管边框、WM_PASTE粘贴、WM_ERASEBKGND背景擦除。理解了消息机制很多用常规属性做不到的效果就有了新思路。3.3 自定义属性与设计器支持自定义控件的属性要让它出现在VS属性面板里并且支持默认值、序列化、在设计器里即时预览需要给属性加上一些特性标注[Description(水印文字)] [DefaultValue()] [Category(Custom)] public string WatermarkText { get; set; }其中DefaultValue不光是给设计器看的它还会影响代码生成的逻辑如果属性值等于默认值设计器就不会在InitializeComponent里生成赋值代码保持生成的代码干净。Category则是属性面板里的分类标签。4. 完整实战做一个带水印、边框高亮、输入限制的输入框4.1 第一步搭建基础类与属性定义新建一个类库项目或者直接在Winform项目里加一个类文件再创建如下类using System.ComponentModel; using System.Drawing; using System.Drawing.Drawing2D; using System.Runtime.InteropServices; using System.Windows.Forms; public class CustomTextBox : TextBox { private string _watermarkText 请输入内容; private Color _watermarkColor Color.Gray; private Color _borderColor Color.DarkGray; private Color _focusBorderColor Color.DodgerBlue; private int _cornerRadius 0; [Category(Custom)] [Description(水印文字)] [DefaultValue(请输入内容)] public string WatermarkText { get _watermarkText; set { _watermarkText value; Invalidate(); } } [Category(Custom)] [Description(水印颜色)] public Color WatermarkColor { get _watermarkColor; set { _watermarkColor value; Invalidate(); } } [Category(Custom)] [Description(边框颜色)] public Color BorderColor { get _borderColor; set { _borderColor value; Invalidate(); } } [Category(Custom)] [Description(焦点边框颜色)] public Color FocusBorderColor { get _focusBorderColor; set { _focusBorderColor value; Invalidate(); } } [Category(Custom)] [Description(圆角半径)] [DefaultValue(0)] public int CornerRadius { get _cornerRadius; set { _cornerRadius value; RecreateRegion(); } } }注意每个属性都是直接调用Invalidate或者RecreateRegion来触发重绘这样在设计器里修改属性时控件能立刻响应变化体验很好。4.2 第二步实现水印文字水印实现的核心思路是在控件没有文字且没有焦点或者即使有焦点但内容为空时显示一段淡色的提示文本。这里需要处理的就是之前说的绘制机制选择问题。我先说重写OnPaint的常规版本public CustomTextBox() { SetStyle(ControlStyles.UserPaint, true); SetStyle(ControlStyles.AllPaintingInWmPaint, true); SetStyle(ControlStyles.OptimizedDoubleBuffer, true); SetStyle(ControlStyles.ResizeRedraw, true); } protected override void OnPaint(PaintEventArgs e) { base.OnPaint(e); if (string.IsNullOrEmpty(Text) !string.IsNullOrEmpty(WatermarkText)) { var g e.Graphics; var drawRect new Rectangle(ClientRectangle.X 3, ClientRectangle.Y 3, ClientRectangle.Width - 6, ClientRectangle.Height - 6); TextRenderer.DrawText(g, WatermarkText, Font, drawRect, WatermarkColor, TextFormatFlags.VerticalCenter | TextFormatFlags.Left); } }开启UserPaint之后TextBox的默认边框也没了需要自己画。所以OnPaint里要在画水印之前先把边框画上protected override void OnPaint(PaintEventArgs e) { base.OnPaint(e); var borderColor Focused ? FocusBorderColor : BorderColor; using (var pen new Pen(borderColor, 1)) { var rect new Rectangle(0, 0, Width - 1, Height - 1); if (_cornerRadius 0) { using (var path GetRoundedPath(rect, _cornerRadius)) { e.Graphics.SmoothingMode SmoothingMode.AntiAlias; e.Graphics.DrawPath(pen, path); } } else { e.Graphics.DrawRectangle(pen, rect); } } if (string.IsNullOrEmpty(Text) !string.IsNullOrEmpty(WatermarkText)) { // 画水印 } }但要注意UserPaint方案有一个绕不开的副作用选中文字的高亮、右键菜单的默认外观都会变得不太好。如果你的水印需求优先级很高而且UI风格本来就是要彻底自绘那这个方案没毛病。但如果只是想加个水印又想完全保留TextBox原生外观更稳妥的是用WndProc做附加绘制。不过说句实话我实际项目里大部分是直接UserPaint方案因为一旦要做边框颜色和圆角原生的外观本来就要让位给自己的绘制逻辑统一接管反而更好控制。4.3 第三步实现焦点变化和边框颜色边框颜色要随焦点变化最直接的方式是重写OnEnter和OnLeave事件然后触发重绘protected override void OnEnter(EventArgs e) { base.OnEnter(e); Invalidate(); } protected override void OnLeave(EventArgs e) { base.OnLeave(e); Invalidate(); }这里有个细节OnEnter和OnLeave已经是最底层的焦点回调比GotFocus/LostFocus事件更早触发。在自绘方案里用OnEnter/OnLeave配合Invalidate能保证边框颜色变化发生在重绘之前视觉上不会闪过旧颜色。如果你用的是WndProc方案也可以拦截WM_SETFOCUS和WM_KILLFOCUS消息来做同样的事。两种方式结果一致看个人习惯。4.4 第四步限制输入内容限制输入分两道防线第一道防线OnKeyPress拦截按键输入。这是最常用的一种方式在用户按下字符键时判断是否合法public enum TextInputType { Any, DigitOnly, LetterOnly, LetterAndDigit } [Category(Custom)] [DefaultValue(TextInputType.Any)] public TextInputType InputType { get; set; } TextInputType.Any; protected override void OnKeyPress(KeyPressEventArgs e) { base.OnKeyPress(e); if (InputType TextInputType.Any) return; bool isValid true; if (InputType TextInputType.DigitOnly) isValid char.IsDigit(e.KeyChar) || char.IsControl(e.KeyChar); else if (InputType TextInputType.LetterOnly) isValid char.IsLetter(e.KeyChar) || char.IsControl(e.KeyChar); else if (InputType TextInputType.LetterAndDigit) isValid char.IsLetterOrDigit(e.KeyChar) || char.IsControl(e.KeyChar); e.Handled !isValid; }char.IsControl的判断必须要加不然退格键、删除键、方向键全都被拦掉用户会直接原地崩溃。第二道防线拦截粘贴操作。OnKeyPress只能挡键盘输入拦不住右键粘贴或者CtrlV。如果要彻底限制得在WndProc里拦截WM_PASTE消息protected override void WndProc(ref Message m) { if (m.Msg 0x0302) // WM_PASTE { if (!IsPastedTextValid()) { return; } } base.WndProc(ref m); } private bool IsPastedTextValid() { var text Clipboard.GetText(); if (string.IsNullOrEmpty(text)) return true; if (InputType TextInputType.DigitOnly) return text.All(char.IsDigit); if (InputType TextInputType.LetterOnly) return text.All(char.IsLetter); if (InputType TextInputType.LetterAndDigit) return text.All(char.IsLetterOrDigit); return true; }4.5 第五步扩展圆角和清除按钮圆角可以通过设置Region来实现Region是一个裁剪区域的概念把它设置成圆角矩形路径控件显示时超出区域的部分就会被裁掉private GraphicsPath GetRoundedPath(Rectangle rect, int radius) { int d radius * 2; var path new GraphicsPath(); 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; } private void RecreateRegion() { if (_cornerRadius 0) { Region null; return; } using (var path GetRoundedPath(ClientRectangle, _cornerRadius)) { Region new Region(path); } }再配合OnResize时重新创建Regionprotected override void OnResize(EventArgs e) { base.OnResize(e); RecreateRegion(); }圆角方案有个我认为需要坦率说明的局限Region不支持抗锯齿在低分辨率屏幕上边缘会有明显的锯齿感。如果老板反复盯着圆角边缘说怎么像狗啃的要么接受这个现实要么走完全自绘的路子配合SmoothingMode.AntiAlias要么就去选带圆角的高级UI框架。我自己的经验是圆角半径在6到10之间视觉上最舒服超过10就会显得很圆润很消费级工控界面里一般不太合适。想做清除按钮就是QQ搜索框里那个一键清空的X的话可以用UserControl组合方案或者在里面放一个无边框的PictureBox/Button通过移动和显隐来控制。这个扩展有点超纲先不展开。5. 常见问题与排查技巧实录我在做自定义TextBox的过程中遇到过一些比较典型的问题这里整理成速查表遇到可以直接对号入座问题表现原因解决方法水印不显示设置了WatermarkText但运行后空白OnPaint没触发构造函数里SetStyle设置UserPainttrue控件疯狂闪烁每次重绘都闪得厉害缺少双缓冲加上OptimizedDoubleBuffer和AllPaintingInWmPaint边框颜色不生效改了BorderColor没反应自定义边框没画或者被原生边框盖住确认UserPaint已经接管绘制且绘制顺序在base.OnPaint之后只能输数字但仍能粘贴字母OnKeyPress拦不住右键粘贴没处理WM_PASTE在WndProc里拦WM_PASTE并对粘贴内容做校验退格键也被限制了输入框里删不了字判断时没加char.IsControl把char.IsControl(e.KeyChar)作为允许条件之一圆角边缘有锯齿圆角矩形边缘不光滑Region不支持抗锯齿改自绘方案用GDI的DrawPath配合SmoothingMode设计器里修改属性不动VS属性面板改了值界面不刷新属性setter里没调用Invalidatesetter里调用Invalidate()或RecreateRegion()另外还有两个容易被忽视的坑。第一个坑是IME中文输入状态下拦截KeyPress会导致输入异常。如果你做了一个只能输入字母数字的输入框用户在中文输入法下打字拼音窗口可能弹不出来或者候选词无法上屏。严格来说用OnKeyPress做输入限制在IME场景下并不完美。如果要处理中文输入法的兼容需要处理WM_IME_COMPOSITION等复杂消息。我的建议是如果是工控或后台系统就明确告知用户需要切换到英文输入法如果是正式面向外部用户的产品还是需要更完整的输入过滤方案。第二个坑是Enter键在KeyUp事件里还会触发MessageBox回车回调。有网友遇到过在KeyUp里弹MessageBoxMessageBox一开Enter键的KeyUp事件再次触发导致消息框反复弹出。这属于典型的键盘事件递归问题。解法是在KeyDown里判断Enter键时设置SuppressKeyPress为true或者不在KeyUp里弹窗改用按钮触发逻辑。protected override void OnKeyDown(KeyEventArgs e) { base.OnKeyDown(e); if (e.KeyCode Keys.Enter) { e.SuppressKeyPress true; // 防止Enter的KeyUp再次触发 // 在这里统一触发搜索/确认逻辑 } }这两类问题在CSDN和知乎上被问过无数次看起来都是很小的点但实际排查起来如果不知道底层机制真的很浪费时间。写在最后的一些个人经验自定义控件这条路我前前后后走了不少弯路。刚开始的时候我习惯到处找第三方库后来被版权、体积、维护问题坑了几次之后才痛下决心自己写。其实Winform自定义控件没那么神秘本质就是继承 消息 重绘三件套把这三样吃透市面上90%的控件美化需求你都能搞定。最后再分享一个小技巧做自定义控件的时候一定要把属性面板的设计期体验做好Category、Description、DefaultValue这些特性标注别偷懒。好的设计期体验能让你在开发时省下一半的时间因为你可以直接在设计器里拖控件、改属性、看效果而不是改一次代码编译一次。如果你需要做的功能更复杂比如带下拉选择的组合输入框、带历史记录的智能输入框思路也是一样的先继承再在原有基础上加行为实在搞不定再换UserControl组合。从简单到复杂一步步来Winform的上限其实比很多人想象中要高得多。本文还有配套的精品资源点击获取
