AtomUI/docs/Desktop.Controls/Avatar/AvatarAPI.md

Avatar API 参考

命名空间

namespace AtomUI.Desktop.Controls;          // Avatar, AvatarGroup
namespace AtomUI.Controls.Commons;           // AbstractAvatar, AvatarPseudoClass
namespace AtomUI.Controls;                   // AvatarShape, CustomizableSizeType

AXAML 命名空间前缀：atom（xmlns:atom="https://atomui.net"）

---

枚举类型

AvatarShape

头像形状枚举，定义头像的外轮廓形状。

值	说明
Circle	圆形（默认），CornerRadius = Width / 2 实现完全圆角
Square	方形，带 Token 定义的圆角（BorderRadius / BorderRadiusSM / BorderRadiusLG）

CustomizableSizeType（来自 AtomUI.Controls）

可自定义的尺寸类型枚举，比标准 SizeType 多一个 Custom 值。

值	说明
Large	大号
Middle	中号（默认）
Small	小号
Custom	自定义尺寸（设置 Size 属性后自动切换）

FlyoutTriggerType（来自 AtomUI.Controls）

弹出触发类型枚举，用于 AvatarGroup 的折叠头像弹出。

值	说明
Hover	鼠标悬浮触发（默认）
Click	鼠标点击触发

---

Avatar 公共属性（StyledProperty）

属性名	类型	默认值	说明
Gap	double	4.0	文字距离左右两侧的像素间距，用于控制文字自适应缩放的留白空间
Icon	PathIcon?	null	图标内容，使用 Ant Design 图标集提供
BitmapSrc	IImage?	null	位图图片源，支持 Bitmap/CroppedBitmap 等 IImage 实现
Src	string?	null	SVG 图片路径（avares:// URI 或文件路径）
Text	string?	null	文字内容（标记了 [Content] 属性，支持 AXAML 直接嵌套文字）
SizeType	CustomizableSizeType	Middle	尺寸类型，支持预设三种尺寸及自定义。设置 Size 后自动切换为 Custom
Size	double	NaN	自定义尺寸像素值。设置为非 NaN 值时，SizeType 自动切换为 Custom
Shape	AvatarShape	Circle	头像形状（圆形或方形）
IsMotionEnabled	bool	跟随全局 Token EnableMotion	是否启用过渡动画（共享属性，通过 AddOwner 注册）

继承自 TemplatedControl 的常用属性

属性名	类型	默认值	说明
Background	IBrush?	由主题控制	背景色（Icon/Text 模式使用 AvatarBg，图片模式透明）
Foreground	IBrush?	由主题控制	前景色（图标和文字颜色，默认 AvatarColor）
BorderBrush	IBrush?	由主题控制	边框颜色（默认 GroupBorderColor）
BorderThickness	Thickness	由 Token 控制	边框粗细
CornerRadius	CornerRadius	由形状和尺寸自动计算	圆角半径（Circle 模式 = Width/2，Square 模式由 Token 控制）
Width / Height	double	由 SizeType/Size 控制	控件尺寸
FontSize	double	由 Token 控制	字体大小（影响文字头像的文字渲染）
FontFamily	FontFamily	继承	字体（影响文字缩放计算）
HorizontalAlignment	HorizontalAlignment	Left	水平对齐
VerticalAlignment	VerticalAlignment	Top	垂直对齐
IsEnabled	bool	true	是否启用

---

AvatarGroup 公共属性（StyledProperty）

属性名	类型	默认值	说明
MaxDisplayCount	int?	null	最大显示数量。超出部分折叠为 +N 计数头像，null 表示不限制
SizeType	CustomizableSizeType	Middle	统一尺寸类型，自动传递给所有子 Avatar（通过 AddOwner 共享）
Size	double	NaN	统一自定义尺寸像素值（通过 AddOwner 共享）
Shape	AvatarShape	Circle	统一形状，自动传递给所有子 Avatar（通过 AddOwner 共享）
FoldInfoAvatarBackground	IBrush?	由主题控制（AvatarBg）	折叠计数头像的背景色
FoldInfoAvatarForeground	IBrush?	由主题控制（AvatarColor）	折叠计数头像的前景色（文字颜色）
FoldAvatarFlyoutTriggerType	FlyoutTriggerType	Hover	折叠头像弹出触发方式（悬浮或点击）
IsMotionEnabled	bool	跟随全局 Token EnableMotion	是否启用过渡动画
Children	Controls	空集合	子 Avatar 控件集合（标记了 [Content]，支持 AXAML 直接嵌套子元素）

AvatarGroup 继承自 TemplatedControl 的常用属性

属性名	类型	默认值	说明
BorderThickness	Thickness	由 Token 控制（SharedToken.BorderThickness）	统一边框粗细，自动传递给所有子 Avatar
HorizontalAlignment	HorizontalAlignment	Left	水平对齐
VerticalAlignment	VerticalAlignment	Top	垂直对齐

---

伪类（Pseudo-Classes）

Avatar 支持以下伪类（定义在 AvatarPseudoClass 中），可在样式选择器中使用：

伪类	常量	触发条件
:large	AvatarPseudoClass.Large	SizeType == Large
:middle	AvatarPseudoClass.Middle	SizeType == Middle
:small	AvatarPseudoClass.Small	SizeType == Small
:custom-size	AvatarPseudoClass.Custom	SizeType == Custom（设置了 Size 属性）

注意

Avatar 的 ControlTheme 实际使用属性选择器（如 [SizeType=Large]、[ContentType=Icon]、[Shape=Square]）而非伪类来驱动样式切换。伪类常量在 AvatarPseudoClass 中定义但当前主要用于扩展场景。

继承的标准伪类

伪类	触发条件
:pointerover	鼠标悬浮
:disabled	IsEnabled == false
:focus	获得焦点
:focus-visible	通过键盘获得焦点

---

实现的接口

IMotionAwareControl（Avatar / AvatarGroup）

public bool IsMotionEnabled { get; set; }

控制是否启用过渡动画。默认跟随全局 Token EnableMotion 的值。

---

内部属性（仅供主题/扩展使用）

以下属性为 internal 可见性，主题 AXAML 中可通过 TemplateBinding 引用：

Avatar 内部属性

属性名	类型	说明
EffectiveIconSize	double	运行时计算的实际图标/文字图标尺寸
TextRenderTransform	ITransform?	文字自适应缩放变换矩阵
ContentType	AvatarContentType	当前内容类型（Icon/BitmapImage/SvgImage/Text），驱动模板内容切换

AvatarGroup 内部属性

属性名	类型	说明
GroupSpace	double	头像组子项间距（由 AvatarToken.GroupSpace 控制）
GroupOverlapping	double	头像重叠宽度（由 AvatarToken.GroupOverlapping 控制）

---

内容优先级

当同时设置多个内容属性时，按以下优先级显示：

优先级	属性	内容类型
1（最高）	Src	SVG 图片
2	BitmapSrc	位图图片
3	Text	文字
4（最低/默认）	Icon	图标