syncfusion-wpf-avatar-view

实现 SfAvatarView（WPF）

何时使用此技能

当用户需要以下功能时，请使用此技能：

• 显示用户头像、姓名首字母或头像角色
• 使用纯色背景显示姓名首字母（单字符或双字符）
• 使用预置头像角色（Avatar1–Avatar25）
• 根据数据集合构建群组头像视图
• 自定义头像形状（Circle、Square、Custom）和大小
• 为头像应用边框、背景、渐变或字体样式
• 为头像附加徽章（状态指示器）

组件： SfAvatarView 程序集： Syncfusion.Shared.WPF XAML 命名空间： xmlns:syncfusion="http://schemas.syncfusion.com/wpf"

---

组件概述

SfAvatarView 通过以下五种内容模式之一显示用户头像：

ContentType	显示内容
Default	内置的 Avatar1 角色，无需设置
Initials	从 AvatarName 提取的姓名首字母
CustomImage	通过 ImageSource 提供的用户图片
AvatarCharacter	25 种预置头像角色图片之一
Group	通过绑定集合显示多个头像

形状由 AvatarShape（Circle / Square / Custom）控制，大小由 AvatarSize（ExtraSmall → ExtraLarge）控制。

---

文档和导航指南

入门

📄 阅读： references/getting-started.md

• NuGet 包和程序集设置
• XAML 命名空间声明
• 最简可运行示例（Default 类型）
• 快速入门：ImageSource
• 必需的 CSS/主题导入

内容类型

📄 阅读： references/content-types.md

• Default — 零配置头像角色
• Initials — AvatarName + InitialsType（Single/Double）
• CustomImage — 使用 pack:// URI 的 ImageSource
• AvatarCharacter — Avatar1–Avatar25 枚举
• Group 视图 — GroupSource + 成员路径属性 + ViewModel 模式
• ContentTemplate — 完全自定义的 DataTemplate 渲染

视觉样式

📄 阅读： references/visual-styles.md

• AvatarShape：Circle（默认）、Square、Custom
• AvatarSize：ExtraSmall、Small、Medium、Large、ExtraLarge
• 自定义形状 — 显式设置 Height、Width、CornerRadius、FontSize
• 通过 WPF ResourceDictionary 复用样式

自定义

📄 阅读： references/customization.md

• BorderBrush 和 BorderThickness
• Background — 纯色
• 渐变背景 — LinearGradientBrush / RadialGradientBrush
• 用于姓名首字母文本的 FontFamily、FontSize、Foreground

徽章集成

📄 阅读： references/badge-integration.md

• 将 SfBadge 附加到 SfAvatarView
• 使用 HorizontalPosition / VerticalPosition 定位徽章
• 状态指示器模式（在线/离线圆点）

---

快速入门示例

xmlns:syncfusion="http://schemas.syncfusion.com/wpf"

显示姓名首字母：

<syncfusion:SfAvatarView ContentType="Initials"
                         AvatarName="Alex"
                         InitialsType="DoubleCharacter"
                         AvatarShape="Circle"
                         AvatarSize="Large" />

显示自定义图片：

<syncfusion:SfAvatarView ContentType="CustomImage"
                         AvatarShape="Circle"
                         AvatarSize="Large"
                         ImageSource="pack://application:,,,/Assets/profile.png" />

显示预置角色：

<syncfusion:SfAvatarView ContentType="AvatarCharacter"
                         AvatarCharacter="Avatar5"
                         AvatarShape="Circle"
                         AvatarSize="Medium" />

---

常见模式

模式 1 — 根据可用数据选择内容类型：

• 有头像图片 URL → ContentType="CustomImage" + ImageSource
• 有姓名字符串 → ContentType="Initials" + AvatarName
• 需要占位头像 → ContentType="AvatarCharacter" + 选择 Avatar1–Avatar25
• 需要在头像内显示完全自定义的 UI → 使用 DataTemplate 设置 ContentTemplate

模式 2 — 根据列表显示群组头像：

• 绑定集合 → ContentType="Group" + GroupSource
• 映射成员路径：InitialsMemberPath、ImageSourceMemberPath、BackgroundColorMemberPath、InitialsColorMemberPath

模式 3 — 选择形状和大小：

• 带圆形头像的个人资料卡片 → AvatarShape="Circle" + AvatarSize 枚举
• 方形头像磁贴 → AvatarShape="Square" + AvatarSize 枚举
• 完全自定义尺寸 → AvatarShape="Custom" + 显式设置 Height/Width/CornerRadius

---

关键属性参考

属性	类型	用途
ContentType	AvatarContentType	选择渲染模式
AvatarName	string	提取姓名首字母的来源
InitialsType	AvatarInitialsType	单字符或双字符首字母
ImageSource	ImageSource	CustomImage 模式下的图像 URI
AvatarCharacter	AvatarCharacter	预置角色枚举（Avatar1–Avatar25）
AvatarShape	AvatarShape	圆形 / 方形 / 自定义
AvatarSize	AvatarSize	超小 / 小 / 中 / 大 / 超大
GroupSource	IEnumerable	Group 模式的数据集合
ContentTemplate	DataTemplate	头像内容的自定义模板
BorderBrush	Brush	边框颜色
BorderThickness	Thickness	边框宽度
Background	Brush	背景填充（纯色或渐变）
CornerRadius	CornerRadius	自定义形状的圆角