• UI组件
• 桌面应用

UIAvatar 是 SunnyUI 开源 WinForm 控件库中专门用于展示"头像"的控件，支持**图片（Image）、字体图标（Symbol）、文字（Text）三种内容呈现方式，并可在圆形（Circle）与方形（Square）**两种形状间自由切换，颜色随主题样式自动联动。本文以官方文档为基础，结合 UIAvatar.cs 源码与 FAvatar 示例页 的实战配置，完整讲解该控件的全部属性、图标选择流程、绘制原理与集成方式，读完即可在项目中直接落地使用。

一、UIAvatar 控件概述

UIAvatar 在 SunnyUI 中的定位是"头像"控件，常用于登录用户信息栏、联系人列表、消息页等需要展示人物头像或标识的场景。从源码看，它被声明为：

[DefaultEvent("Click")] [DefaultProperty("Symbol")] [ToolboxItem(true)] [Description("头像控件")] public sealed class UIAvatar : UIControl, ISymbol, IZoomScale

（见 UIAvatar.cs）其中：

• 默认属性为Symbol：即字体图标编码，是控件最常用的配置入口；
• 默认事件为Click：可直接在设计器中双击头像编写点击逻辑（如弹出用户菜单）；
• 实现了IZoomScale接口，支持 SunnyUI 的 DPI 缩放体系，高分屏下自动按比例缩放头像与图标尺寸。

构造时控件默认尺寸为 60×60，关闭了文字与边框的默认绘制（ShowText = false、ShowRect = false），填充色与前景色取自 Blue 主题的AvatarFillColor/AvatarForeColor（见 UIAvatar.cs）。

二、核心属性一览

官方文档给出了完整的属性列表，下表在原文基础上补充了源码确认的默认值与取值细节（默认值以 UIAvatar.cs 中的特性标注为准）：

除表格所列外，源码还提供了三组偏移与旋转细节属性（官方文档未逐条列出，但实测非常实用）：

• SymbolOffset（Point）：字体图标的偏移位置，默认 (0,0)；
• SymbolRotate（int）：字体图标旋转角度，默认 0，V3.5.1 版本新增；
• TextOffset/ImageOffset（Point）：文字与图片的偏移位置，默认 (0,0)。

相关实现见 UIAvatar.cs。

三、字体图标（Symbol）模式与图标选择器

头像最常用的内容是"字体图标"。UIAvatar 与 SunnyUI 的字体图标体系（FontAwesome、Material Icons 等，详见 symbol.md）深度集成，默认即呈现一个灰色圆形底 + 蓝色人形图标的效果：

3.1 Symbol 与 SymbolSize

• Symbol（int）：字体图标编码，直接决定显示哪个图标。编码可在设计器属性面板中设置，面板同时高亮展示当前Symbol与SymbolSize的值：

• SymbolSize（int）：图标字号，默认 45。源码在赋值时做了钳制，有效范围为16 ~ 128（UIAvatar.cs），小于 16 会按 16 处理，大于 128 按 128 处理。

3.2 可视化选择图标：内置图标选择器

无需手查编码表，UIAvatar 的Symbol属性关联了UIImagePropertyEditor类型编辑器（见 UIAvatar.cs）。在设计器中点击 Symbol 右侧的省略号按钮，即可弹出 SunnyUI 内置的字体图标选择器：

操作流程为：

1. 在图标选择器顶部的搜索框中按名称筛选，或按分类标签浏览；
2. 将鼠标移到某个图标上，悬浮提示会显示该图标对应的数字编码（Symbol 值）；
3. 点击图标即可将其设置为当前头像的Symbol。

因此即使面对数百个字体图标，也能通过"搜索 + 悬停预览 + 点击"三步快速完成配置。

3.3 Symbol 模式绘制原理

Icon = Symbol时，绘制调用的是DrawFontImage（UIAvatar.cs），图标按SymbolSize字号、以ForeColor为颜色绘制在头像矩形区域内，并支持SymbolOffset微调位置、SymbolRotate指定旋转角度：

if (Icon == UIIcon.Symbol) { e.Graphics.DrawFontImage(symbol, symbolSize, ForeColor, new Rectangle((Width - avatarSize) / 2 + 1 + SymbolOffset.X, (Width - avatarSize) / 2 + 1 + SymbolOffset.Y, avatarSize, avatarSize), 0, 0, SymbolRotate); }

注意这里图标绘制区域即avatarSize对应的正方形，与头像填充区域严格对齐，保证图标始终居中于头像内部。

四、三种显示方式：图片 / 字体图标 / 文字

通过Icon属性可切换头像内容，取值定义在UIAvatar.UIIcon枚举中（UIAvatar.cs）：

public enum UIIcon { Image, // 图像 Symbol, // 符号（字体图标） Text // 文字 }

三种方式的效果对比如下（默认均为圆形）：

4.1 图片模式（Icon = Image）

设置Image属性即可。源码在绘制时会做两项关键处理（UIAvatar.cs）：

1. 等比缩放裁剪：将图片按avatarSize比例缩放，再调用Split(size, Shape)按当前形状（圆形/方形）裁剪成头像轮廓，避免图片变形；
2. 描边：用 4px 宽的BackColor画笔沿头像边缘再绘制一圈轮廓，让图片头像与背景自然分离：

Bitmap scaleImage = ((Bitmap)Image).ResizeImage(...); Bitmap bmp = scaleImage.Split(size, Shape); e.Graphics.DrawImage(bmp, (Width - avatarSize) / 2 + 1 + ImageOffset.X, ...); using Pen pn = new Pen(BackColor, 4); // Shape == Circle : DrawEllipse // Shape == Square : DrawRoundRectangle

4.2 文字模式（Icon = Text）

设置Text与Font即可，文字使用DrawString按ContentAlignment.MiddleCenter居中绘制在头像内（UIAvatar.cs），同样支持TextOffset微调位置。适合在没有真实图片、又不想用图标的场景下展示姓名缩写，如示例页中的"Avatar"文字头像。

五、显示形状：圆形与方形

Shape属性控制头像外轮廓，枚举定义于 UImage.cs：

public enum UIShape { Circle, // 圆形 Square // 方形 }

对应的填充绘制逻辑在OnPaintFill中（UIAvatar.cs）：

Rectangle rect = new Rectangle((Width - avatarSize) / 2, (Height - avatarSize) / 2, avatarSize, avatarSize); switch (Shape) { case UIShape.Circle: g.FillEllipse(fillColor, rect); // 圆形：标准椭圆填充 break; case UIShape.Square: g.FillRoundRectangle(fillColor, rect, 5); // 方形：圆角 5px 的圆角矩形 break; }

从源码可见，所谓"方形"实际是圆角半径为 5px 的圆角矩形，观感比直角矩形更柔和。形状不仅影响背景填充，还会同步作用于图片头像的裁剪轮廓（Split(size, Shape)）与描边方式（椭圆/圆角矩形）。

六、主题样式与颜色联动

UIAvatar 的颜色体系完全建立在 SunnyUI 的主题机制之上：

• Style：选择主题样式（Blue、Orange、Purple 等），控件会调用SetStyleColor(UIBaseStyle)从当前主题刷新FillColor与ForeColor（UIAvatar.cs）；
• StyleCustomMode：置为true后脱离主题联动，可自由指定FillColor、ForeColor（即SymbolColor的实际渲染色）进行个性化配色；
• FillColor默认值为 Silver，当设置为背景色、透明色或空值时不再填充，可做纯图标/文字头像；
• ForeColor默认值为80, 160, 255，决定图标与文字的颜色。

主题侧的颜色定义在 UIStyleColor.cs 中，每个主题都提供AvatarFillColor与AvatarForeColor两个专用色板。例如 Blue 主题将其定义为Silver（填充）与PrimaryColor（前景，即主题主色，见 UIStyleColor.cs）；部分深色主题则使用SelectedColor作为填充色（见 UIStyleColor.cs）。因此切换主题后头像会自动换色，无需逐个调整。

七、其他实用属性：偏移、标签与缩放

• OffsetX / OffsetY：水平/垂直整体偏移，默认 0，被标记为Browsable(false)，主要用于运行时微调头像在布局中的视觉位置（UIAvatar.cs）；
• TagString：用于在控件上附加任意对象字符串数据，方便业务层传值；
• PaintAgain 事件：头像绘制完成后触发（PaintAgain?.Invoke(this, e)，见 UIAvatar.cs），可用于在头像上叠加自定义绘制内容；
• DPI 缩放：SetZoomScale(float scale)会基于基准值baseAvatorSize/baseSymbolSize按比例重新计算AvatarSize与SymbolSize（UIAvatar.cs），保证高分屏与窗体缩放时头像不失真。

八、Demo 实战：FAvatar 示例页

官方示例页 FAvatar.Designer.cs 一次性演示了 UIAvatar 的典型用法，共放置 6 个头像：

其中"点击头像弹出右键菜单"是最常见的业务场景（如"设置 / 更改密码 / 退出"），逻辑写在 FAvatar.cs：

private void uiAvatar4_Click(object sender, System.EventArgs e) { uiContextMenuStrip1.Show(uiAvatar4, 0, uiAvatar4.Height); }

即通过默认事件Click在头像正下方弹出UIContextMenuStrip快捷菜单，整体交互与主流桌面软件的"用户头像菜单"一致。

小结

UIAvatar 是 SunnyUI 中开箱即用的头像组件：Icon决定内容（图片/图标/文字），Shape决定轮廓（圆形/圆角方形），Style与FillColor/ForeColor决定配色并随主题联动，Symbol+ 图标选择器则解决了图标选取的效率问题。配合Click默认事件、AvatarSize缩放与Offset*微调，可以快速构建出风格统一、可适配高分屏的用户头像 UI。更完整的主题与字体图标背景知识，可进一步参考 theme.md 与 symbol.md。

• UI组件
• 桌面应用