• UI组件
• 桌面应用

UIMarkLabel 是 SunnyUI.NET 控件库（基于 .NET Framework 4.0+、.NET6、.NET8、.NET9 的 C# WinForm UI 开源控件库）中用于在文本旁侧绘制一条颜色标签（Mark）的标签控件，常用于列表项、表单分组、状态标题等场景的强调与视觉引导。阅读本文后，你将掌握 UIMarkLabel 的全部公开属性与默认值、四种标签方向的切换规则，以及它与 SunnyUI 主题配色系统之间的联动实现细节，并能在设计器或代码中直接落地使用。

控件定位：UIMarkLabel 是什么

UIMarkLabel 是"带颜色标签"的标签控件：它在传统文本标签的基础上，沿控件边缘绘制一条与主题色一致的色条，从而在不引入额外图形元素的情况下实现文本强调。从源码结构看，UIMarkLabel.cs 直接继承自 UILabel.cs，因此它天然具备 SunnyUI 标签家族的文本显示、主题换肤（IStyleInterface）、窗体缩放（IZoomScale）与多语言翻译（IFormTranslator）能力，同时通过重写绘图（OnPaint）叠加了独特的色条效果。

• 默认属性：Text（[DefaultProperty("Text")]）
• 默认事件：Click（[DefaultEvent("Click")]）

控件在属性面板中的描述为"带颜色标签控件"（见 UIMarkLabel.cs），可直接从工具箱拖入 WinForm 设计器使用。

属性列表：核心公开属性与默认值

下表完整列出 UIMarkLabel 的公开属性及其默认值（与官方文档一致，并补充了源码中的实现细节）：

其中几项属性值得展开说明其底层行为：

• MarkSize：色条在左/右方向时的宽度、在上/下方向时的高度，源码默认值为3，通过[DefaultValue(3)]声明（UIMarkLabel.cs）。改变该值会触发Invalidate()立即重绘。
• MarkColor：色条填充颜色。属性默认值声明为"80, 160, 255"（RGB），与 SunnyUI 蓝色主题的主色一致；构造函数中实际取UIStyles.Blue.MarkLabelForeColor作为初始值（UIMarkLabel.cs）。
• TagString / Version：TagString用于携带与控件关联的任意字符串数据，Version来自UIGlobal.Version，两者均在基类 UILabel 中定义（UILabel.cs），并向下继承给 UIMarkLabel。

标签位置：四个方向的切换与自动 Padding

UIMarkLabel 的色条支持四个显示位置：左（Left）、右（Right）、下（Bottom）、上（Top），对应控件内部定义的枚举UIMarkPos（UIMarkLabel.cs）：

public enum UIMarkPos { Left, Top, Right, Bottom }

官方文档给出的四方向效果如下图所示：

位置切换如何影响布局

MarkPos属性在赋值时不仅触发重绘，还会自动改写控件的Padding，为色条预留出MarkSize + 2像素的空间，保证文本不会被色条遮挡（UIMarkLabel.cs）：

• Left：Padding = new Padding(MarkSize + 2, 0, 0, 0)（左侧留白）
• Right：Padding = new Padding(0, 0, MarkSize + 2, 0)（右侧留白）
• Top：Padding = new Padding(0, MarkSize + 2, 0, 0)（上方留白）
• Bottom：Padding = new Padding(0, 0, 0, MarkSize + 2)（下方留白）

这一设计与 Demo 工程 FLabel.Designer.cs 中的四个示例控件完全吻合——uiMarkLabel1（Left）的 Padding 为(5, 0, 0, 0)、uiMarkLabel3（Right）为(0, 0, 5, 0)、uiMarkLabel2（Bottom）为(0, 0, 0, 5)、uiMarkLabel4（Top）为(0, 5, 0, 0)，即在 MarkSize=3 时统一留出 5 像素。

绘图原理：色条是如何画出来的

UIMarkLabel 的视觉效果完全由重写的OnPaint方法实现（UIMarkLabel.cs），核心逻辑分两步：

1. 自动尺寸计算：当AutoSize = true且未停靠（Dock == DockStyle.None）时，先用TextRenderer.MeasureText测量文本尺寸，再根据标签方向累加MarkSize + 2得出控件宽高并同步赋值：
   • 左/右方向时：Width = 文本宽 + MarkSize + 2，高度保持文本高；
   • 上/下方向时：Height = 文本高 + MarkSize + 2，宽度保持文本宽。
2. 色条绘制：根据MarkPos用FillRectangle填充一个细长矩形（UIMarkLabel.cs）：
   • Left：在(0, 0)处填充MarkSize × Height的竖条；
   • Right：在(Width - MarkSize, 0)处填充竖条；
   • Top：在(0, 0)处填充Width × MarkSize的横条；
   • Bottom：在(0, Height - MarkSize)处填充横条。

可以看到色条总是紧贴控件边缘贯通整个宽/高，这正是"带颜色标签"视觉风格的关键。

主题联动：MarkColor 跟随 Style 自动换色

UIMarkLabel 是典型的主题驱动控件：当切换 SunnyUI 主题样式时，色条颜色会自动跟随主题主色变化。其机制位于SetStyleColor(UIBaseStyle uiColor)方法中（UIMarkLabel.cs）：

public override void SetStyleColor(UIBaseStyle uiColor) { base.SetStyleColor(uiColor); markColor = uiColor.MarkLabelForeColor; }

而MarkLabelForeColor由主题配色类统一提供（UIStyleColor.cs），在主题初始化时被赋值为该主题的PrimaryColor（UIStyleColor.cs）。这意味着：

• 默认（Style = Blue）时，色条为蓝色主题主色80, 160, 255；
• 切换到其他内置主题（如 Green、Orange、Purple 等）时，色条自动变为对应主题色；
• 若将StyleCustomMode设为true进入自定义风格模式，则可绕过主题机制，直接通过MarkColor指定任意颜色。

如需查阅各主题下MarkLabelForeColor的具体取值，可参考主题配色定义文件 UIStyleColor.cs，并可通过 UIForm.cs 中的UIStyleManager相关接口在运行时动态切换主题。

实战：在代码中创建与配置 UIMarkLabel

除了在设计器中拖拽配置，也可以完全通过代码创建，示例如下：

using Sunny.UI; // 创建一个左侧色条的状态标签 UIMarkLabel markLabel = new UIMarkLabel { Text = "核心模块", AutoSize = true, MarkSize = 4, // 色条宽度 4 像素 MarkPos = UIMarkLabel.UIMarkPos.Left, // 默认即为 Left Font = UIStyles.Font() // 使用 SunnyUI 默认字体 }; // 让色条颜色跟随当前主题 markLabel.Style = UIStyle.Blue; // 或者在自定义风格模式下指定任意颜色 // markLabel.StyleCustomMode = true; // markLabel.MarkColor = Color.FromArgb(255, 128, 0);

需要注意的几点：

• 构造函数会自动设置Padding为(MarkSize + 2, 0, 0, 0)，因此代码中无需手动处理色条占位；
• MarkPos每次赋值都会重新计算 Padding，建议先设置MarkSize再设置MarkPos，以确保留白宽度正确；
• AutoSize = true时控件尺寸由文本与色条共同决定，适合独立放置；若需固定尺寸，将AutoSize置为false并手动指定Size即可。

验证与延伸阅读

SunnyUI.Demo 演示工程在标签页 FLabel.Designer.cs 中一次性展示了 Left / Right / Bottom / Top 四种标签方向的标准配置，运行 SunnyUI.Demo.sln 中的 FLabel 页面即可直观对比各方向效果。UIMarkLabel 因其简洁的"文本 + 主题色条"组合，非常适合作为分组标题、数据条目前缀标识和导航强调元素，配合 UIForm.cs 与 UIStyleManager.cs 的主题切换能力，可以轻松实现全界面视觉风格的一致性。

• UI组件
• 桌面应用