syncfusion-winui-avatar-view
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseImplementing WinUI AvatarView
实现WinUI AvatarView
When to Use This Skill
何时使用本技能
Use this skill when the user needs to:
- Display user profile pictures or avatars
- Show user initials in circular or square badges
- Create contact lists with avatar images
- Implement chat interfaces with user avatars
- Display team members with profile pictures
- Show group avatars (up to 3 users)
- Use pre-defined avatar character images
- Create visual user representations in any UI
Always apply this skill when the user mentions: avatar, profile picture, user image, initials, contact image, user icon, profile badge, or group avatars in WinUI applications.
当用户需要实现以下需求时可使用本技能:
- 展示用户个人资料图片或头像
- 在圆形或方形徽章中展示用户姓名首字母
- 创建带头像的联系人列表
- 实现带用户头像的聊天界面
- 展示带个人资料图片的团队成员
- 展示群组头像(最多支持3个用户)
- 使用预定义的头像角色图片
- 在任意UI中创建可视化的用户标识
当用户提到WinUI应用中的avatar、profile picture、user image、initials、contact image、user icon、profile badge或group avatars时,请务必使用本技能。
Component Overview
组件概览
SfAvatarView is a Syncfusion WinUI control that provides a graphical representation of user images with support for custom images, user initials, pre-defined avatar characters, and group views. It offers flexible shapes, sizes, and extensive customization.
Namespace:
NuGet Package:
Platform: WinUI 3 Desktop (.NET 5+, Windows App SDK 1.0+)
Syncfusion.UI.Xaml.CoreNuGet Package:
Syncfusion.Core.WinUIPlatform: WinUI 3 Desktop (.NET 5+, Windows App SDK 1.0+)
Key Advantage: Provides a complete avatar solution with built-in support for initials generation, 25 pre-defined avatar characters, and group views without needing custom implementations.
SfAvatarView是Syncfusion提供的WinUI控件,可实现用户图片的图形化展示,支持自定义图片、用户姓名首字母、预定义头像角色和群组视图,提供灵活的形状、尺寸和丰富的自定义能力。
命名空间:
NuGet包:
支持平台: WinUI 3 Desktop (.NET 5+, Windows App SDK 1.0+)
Syncfusion.UI.Xaml.CoreNuGet包:
Syncfusion.Core.WinUI支持平台: WinUI 3 Desktop (.NET 5+, Windows App SDK 1.0+)
核心优势: 提供完整的头像解决方案,内置首字母生成能力、25个预定义头像角色和群组视图,无需额外自定义实现。
Documentation and Navigation Guide
文档与导航指南
Getting Started
入门指南
📄 Read: references/getting-started.md
- Installation and NuGet package setup
- Namespace imports and basic initialization
- Default avatar behavior (Avatar1, Circle, Small)
- ImageSource property for custom images
- License registration requirements
- First complete example
📄 阅读: references/getting-started.md
- 安装与NuGet包配置
- 命名空间导入和基础初始化
- 默认头像行为(Avatar1、圆形、小尺寸)
- 用于自定义图片的ImageSource属性
- 许可证注册要求
- 首个完整示例
Content Types
内容类型
📄 Read: references/content-types.md
- 5 content types (Default, Initials, CustomImage, AvatarCharacter, GroupView)
- Initials generation (SingleCharacter, DoubleCharacter)
- 25 pre-defined avatar characters
- Custom image support via ImageSource
- Group view for multiple users (up to 3)
- GroupSource and member path configuration
- Choosing the right content type
📄 阅读: references/content-types.md
- 5种内容类型(默认、首字母、自定义图片、头像角色、群组视图)
- 首字母生成(单字符、双字符)
- 25个预定义头像角色
- 通过ImageSource支持自定义图片
- 支持多用户的群组视图(最多3人)
- GroupSource和成员路径配置
- 如何选择合适的内容类型
Visual Styles and Shapes
视觉样式与形状
📄 Read: references/visual-styles.md
- AvatarShape property (Circle, Square, Custom)
- AvatarSize property (ExtraSmall, Small, Medium, Large, ExtraLarge)
- Size comparisons and guidelines
- Custom shapes with CornerRadius
- Shape selection based on design requirements
📄 阅读: references/visual-styles.md
- AvatarShape属性(圆形、方形、自定义)
- AvatarSize属性(超小、小、中等、大、超大)
- 尺寸对比与使用规范
- 通过CornerRadius实现自定义形状
- 根据设计需求选择形状
Customization Options
自定义选项
📄 Read: references/customization.md
- Border customization (BorderBrush, BorderThickness)
- Background property (solid colors)
- Gradient backgrounds (LinearGradientBrush, RadialGradientBrush)
- Font customization (FontFamily, Foreground, FontSize)
- Theme integration
- Combining customizations
📄 阅读: references/customization.md
- 边框自定义(BorderBrush、BorderThickness)
- Background属性(纯色)
- 渐变背景(LinearGradientBrush、RadialGradientBrush)
- 字体自定义(FontFamily、Foreground、FontSize)
- 主题集成
- 多自定义能力组合使用
Quick Start Example
快速入门示例
xaml
<Page
xmlns:syncfusion="using:Syncfusion.UI.Xaml.Core">
<Grid>
<!-- Initials avatar -->
<syncfusion:SfAvatarView
x:Name="userAvatar"
ContentType="Initials"
AvatarName="John Doe"
InitialsType="DoubleCharacter"
AvatarSize="Large"
Background="CornflowerBlue"
Foreground="White"
AvatarShape="Circle"/>
</Grid>
</Page>csharp
using Syncfusion.UI.Xaml.Core;
using Microsoft.UI;
// Create avatar with initials
SfAvatarView avatarView = new SfAvatarView
{
ContentType = AvatarContentType.Initials,
AvatarName = "John Doe",
InitialsType = AvatarInitialsType.DoubleCharacter,
AvatarSize = AvatarSize.Large,
Background = new SolidColorBrush(Colors.CornflowerBlue),
Foreground = new SolidColorBrush(Colors.White),
AvatarShape = AvatarShape.Circle
};
// Add to UI
this.Content = avatarView;xaml
<Page
xmlns:syncfusion="using:Syncfusion.UI.Xaml.Core">
<Grid>
<!-- Initials avatar -->
<syncfusion:SfAvatarView
x:Name="userAvatar"
ContentType="Initials"
AvatarName="John Doe"
InitialsType="DoubleCharacter"
AvatarSize="Large"
Background="CornflowerBlue"
Foreground="White"
AvatarShape="Circle"/>
</Grid>
</Page>csharp
using Syncfusion.UI.Xaml.Core;
using Microsoft.UI;
// Create avatar with initials
SfAvatarView avatarView = new SfAvatarView
{
ContentType = AvatarContentType.Initials,
AvatarName = "John Doe",
InitialsType = AvatarInitialsType.DoubleCharacter,
AvatarSize = AvatarSize.Large,
Background = new SolidColorBrush(Colors.CornflowerBlue),
Foreground = new SolidColorBrush(Colors.White),
AvatarShape = AvatarShape.Circle
};
// Add to UI
this.Content = avatarView;Common Patterns
常用实现模式
1. User Profile Avatar with Initials
1. 带首字母的用户资料头像
xaml
<syncfusion:SfAvatarView
ContentType="Initials"
AvatarName="Sarah Johnson"
InitialsType="DoubleCharacter"
AvatarSize="ExtraLarge"
AvatarShape="Circle"
Background="#FF6A5ACD"
Foreground="White"/>When to use: User profiles, account pages, settings screens.
xaml
<syncfusion:SfAvatarView
ContentType="Initials"
AvatarName="Sarah Johnson"
InitialsType="DoubleCharacter"
AvatarSize="ExtraLarge"
AvatarShape="Circle"
Background="#FF6A5ACD"
Foreground="White"/>适用场景: 用户资料页、账户页、设置界面。
2. Contact List with Custom Images
2. 带自定义图片的联系人列表
xaml
<ListView ItemsSource="{x:Bind Contacts}">
<ListView.ItemTemplate>
<DataTemplate x:DataType="local:Contact">
<StackPanel Orientation="Horizontal" Spacing="10">
<syncfusion:SfAvatarView
ContentType="CustomImage"
ImageSource="{x:Bind ProfileImagePath}"
AvatarSize="Medium"
AvatarShape="Circle"/>
<TextBlock Text="{x:Bind Name}" VerticalAlignment="Center"/>
</StackPanel>
</DataTemplate>
</ListView.ItemTemplate>
</ListView>When to use: Contact lists, chat contacts, team directories.
xaml
<ListView ItemsSource="{x:Bind Contacts}">
<ListView.ItemTemplate>
<DataTemplate x:DataType="local:Contact">
<StackPanel Orientation="Horizontal" Spacing="10">
<syncfusion:SfAvatarView
ContentType="CustomImage"
ImageSource="{x:Bind ProfileImagePath}"
AvatarSize="Medium"
AvatarShape="Circle"/>
<TextBlock Text="{x:Bind Name}" VerticalAlignment="Center"/>
</StackPanel>
</DataTemplate>
</ListView.ItemTemplate>
</ListView>适用场景: 联系人列表、聊天联系人、团队名录。
3. Chat Message with Avatar Character
3. 带头像角色的聊天消息
xaml
<StackPanel Orientation="Horizontal" Spacing="10">
<syncfusion:SfAvatarView
ContentType="AvatarCharacter"
AvatarCharacter="Avatar15"
AvatarSize="Small"
AvatarShape="Circle"/>
<Border Background="LightGray"
CornerRadius="8"
Padding="10">
<TextBlock Text="Hello! How are you?"/>
</Border>
</StackPanel>When to use: Chat interfaces, comment sections, messaging apps.
xaml
<StackPanel Orientation="Horizontal" Spacing="10">
<syncfusion:SfAvatarView
ContentType="AvatarCharacter"
AvatarCharacter="Avatar15"
AvatarSize="Small"
AvatarShape="Circle"/>
<Border Background="LightGray"
CornerRadius="8"
Padding="10">
<TextBlock Text="Hello! How are you?"/>
</Border>
</StackPanel>适用场景: 聊天界面、评论区、消息类应用。
4. Group Avatar (Multiple Users)
4. 群组头像(多用户)
xaml
<syncfusion:SfAvatarView
ContentType="Group"
GroupSource="{x:Bind TeamMembers}"
ImageSourceMemberPath="ProfileImage"
InitialsMemberPath="Name"
BackgroundColorMemberPath="BackgroundColor"
InitialsColorMemberPath="InitialsColor"
AvatarSize="Large"/>csharp
public class TeamMember
{
public string Name { get; set; }
public string ProfileImage { get; set; }
public Color BackgroundColor { get; set; }
public Color InitialsColor { get; set; }
}
public ObservableCollection<TeamMember> TeamMembers { get; set; } = new()
{
new TeamMember { ProfileImage = "user1.png" },
new TeamMember { Name = "Alex", BackgroundColor = Colors.LightBlue, InitialsColor = Colors.Navy },
new TeamMember { ProfileImage = "user3.png" }
};When to use: Team displays, group chats, collaborative features showing multiple participants.
xaml
<syncfusion:SfAvatarView
ContentType="Group"
GroupSource="{x:Bind TeamMembers}"
ImageSourceMemberPath="ProfileImage"
InitialsMemberPath="Name"
BackgroundColorMemberPath="BackgroundColor"
InitialsColorMemberPath="InitialsColor"
AvatarSize="Large"/>csharp
public class TeamMember
{
public string Name { get; set; }
public string ProfileImage { get; set; }
public Color BackgroundColor { get; set; }
public Color InitialsColor { get; set; }
}
public ObservableCollection<TeamMember> TeamMembers { get; set; } = new()
{
new TeamMember { ProfileImage = "user1.png" },
new TeamMember { Name = "Alex", BackgroundColor = Colors.LightBlue, InitialsColor = Colors.Navy },
new TeamMember { ProfileImage = "user3.png" }
};适用场景: 团队展示、群聊、展示多个参与者的协作功能。
5. Dynamic Avatar Based on Data Availability
5. 根据数据可用性动态切换头像
csharp
private void ConfigureAvatar(User user)
{
if (!string.IsNullOrEmpty(user.ProfileImageUrl))
{
// Use custom image if available
avatarView.ContentType = AvatarContentType.CustomImage;
avatarView.ImageSource = new BitmapImage(new Uri(user.ProfileImageUrl));
}
else if (!string.IsNullOrEmpty(user.FullName))
{
// Use initials if no image
avatarView.ContentType = AvatarContentType.Initials;
avatarView.AvatarName = user.FullName;
avatarView.InitialsType = AvatarInitialsType.DoubleCharacter;
avatarView.Background = GetColorFromName(user.FullName);
}
else
{
// Use default avatar character
avatarView.ContentType = AvatarContentType.AvatarCharacter;
avatarView.AvatarCharacter = AvatarCharacter.Avatar1;
}
}When to use: Fallback strategy when user data varies in completeness.
csharp
private void ConfigureAvatar(User user)
{
if (!string.IsNullOrEmpty(user.ProfileImageUrl))
{
// Use custom image if available
avatarView.ContentType = AvatarContentType.CustomImage;
avatarView.ImageSource = new BitmapImage(new Uri(user.ProfileImageUrl));
}
else if (!string.IsNullOrEmpty(user.FullName))
{
// Use initials if no image
avatarView.ContentType = AvatarContentType.Initials;
avatarView.AvatarName = user.FullName;
avatarView.InitialsType = AvatarInitialsType.DoubleCharacter;
avatarView.Background = GetColorFromName(user.FullName);
}
else
{
// Use default avatar character
avatarView.ContentType = AvatarContentType.AvatarCharacter;
avatarView.AvatarCharacter = AvatarCharacter.Avatar1;
}
}适用场景: 用户数据完整度不一致时的降级展示策略。
6. Square Avatar with Border for App Icons
6. 带边框的方形应用图标头像
xaml
<syncfusion:SfAvatarView
ContentType="CustomImage"
ImageSource="AppIcon.png"
AvatarShape="Square"
AvatarSize="Large"
BorderBrush="Gray"
BorderThickness="1"
CornerRadius="8"/>When to use: App icons, service logos, organization badges, square profile images.
xaml
<syncfusion:SfAvatarView
ContentType="CustomImage"
ImageSource="AppIcon.png"
AvatarShape="Square"
AvatarSize="Large"
BorderBrush="Gray"
BorderThickness="1"
CornerRadius="8"/>适用场景: 应用图标、服务标识、组织徽章、方形个人资料图片。
7. Gradient Background Avatar with Initials
7. 带首字母的渐变背景头像
xaml
<syncfusion:SfAvatarView
ContentType="Initials"
AvatarName="Emma Wilson"
InitialsType="DoubleCharacter"
AvatarSize="Large"
Foreground="White">
<syncfusion:SfAvatarView.Background>
<LinearGradientBrush StartPoint="0,0" EndPoint="1,1">
<GradientStop Color="#FF6B5ACD" Offset="0"/>
<GradientStop Color="#FF4169E1" Offset="1"/>
</LinearGradientBrush>
</syncfusion:SfAvatarView.Background>
</syncfusion:SfAvatarView>When to use: Modern, visually appealing avatars with branded gradients.
xaml
<syncfusion:SfAvatarView
ContentType="Initials"
AvatarName="Emma Wilson"
InitialsType="DoubleCharacter"
AvatarSize="Large"
Foreground="White">
<syncfusion:SfAvatarView.Background>
<LinearGradientBrush StartPoint="0,0" EndPoint="1,1">
<GradientStop Color="#FF6B5ACD" Offset="0"/>
<GradientStop Color="#FF4169E1" Offset="1"/>
</LinearGradientBrush>
</syncfusion:SfAvatarView.Background>
</syncfusion:SfAvatarView>适用场景: 现代风格、视觉效果出众的品牌化渐变头像。
Key Properties
核心属性
| Property | Type | Default | Description |
|---|---|---|---|
| AvatarContentType | Default | Type of content to display. Options: Default, Initials, CustomImage, AvatarCharacter, Group. |
| ImageSource | null | Custom image for CustomImage content type. Path to user's profile picture. |
| string | null | Name to generate initials from. Used with Initials content type. |
| AvatarCharacter | Avatar1 | Pre-defined avatar character (Avatar1-Avatar25). Used with AvatarCharacter content type. |
| AvatarInitialsType | SingleCharacter | How initials are formatted. Options: SingleCharacter (first letter), DoubleCharacter (two letters). |
| AvatarShape | Circle | Visual shape. Options: Circle, Square, Custom. |
| AvatarSize | Small | Pre-defined size. Options: ExtraSmall, Small, Medium, Large, ExtraLarge. |
| IEnumerable | null | Collection for Group content type. Supports up to 3 items. |
| string | null | Property path for initials in GroupSource items. |
| string | null | Property path for image in GroupSource items. |
| string | null | Property path for background color in GroupSource items. |
| string | null | Property path for initials color in GroupSource items. |
| Brush | Gray | Background color or gradient for the avatar. |
| Brush | Black | Text color for initials. |
| Brush | null | Border color around the avatar. |
| Thickness | 0 | Border thickness around the avatar. |
| CornerRadius | Auto | Corner radius for Custom shape. |
| FontFamily | Segoe UI | Font for initials text. |
| double | Auto | Font size for initials (auto-calculated based on AvatarSize). |
| 属性 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| AvatarContentType | Default | 要展示的内容类型,可选值:Default、Initials、CustomImage、AvatarCharacter、Group。 |
| ImageSource | null | CustomImage内容类型使用的自定义图片,对应个人资料图片的路径。 |
| string | null | 用于生成首字母的姓名,搭配Initials内容类型使用。 |
| AvatarCharacter | Avatar1 | 预定义头像角色(Avatar1到Avatar25),搭配AvatarCharacter内容类型使用。 |
| AvatarInitialsType | SingleCharacter | 首字母的格式,可选值:SingleCharacter(首字母)、DoubleCharacter(双字母)。 |
| AvatarShape | Circle | 视觉形状,可选值:Circle、Square、Custom。 |
| AvatarSize | Small | 预定义尺寸,可选值:ExtraSmall、Small、Medium、Large、ExtraLarge。 |
| IEnumerable | null | Group内容类型使用的集合,最多支持3个条目。 |
| string | null | GroupSource条目中首字母对应的属性路径。 |
| string | null | GroupSource条目中图片对应的属性路径。 |
| string | null | GroupSource条目中背景色对应的属性路径。 |
| string | null | GroupSource条目中首字母颜色对应的属性路径。 |
| Brush | Gray | 头像的背景色或渐变。 |
| Brush | Black | 首字母的文字颜色。 |
| Brush | null | 头像的边框颜色。 |
| Thickness | 0 | 头像的边框厚度。 |
| CornerRadius | Auto | 自定义形状的圆角值。 |
| FontFamily | Segoe UI | 首字母文字的字体。 |
| double | Auto | 首字母的字体大小(根据AvatarSize自动计算)。 |
Common Use Cases
常见使用场景
User Profiles
用户资料
- Profile pages with user avatars
- Account settings with profile pictures
- User dashboards
- Member profiles
Best Approach: Use CustomImage if available, fallback to Initials with user's name.
- 带头像的个人资料页
- 带个人资料图片的账户设置
- 用户仪表盘
- 成员资料页
最佳实践: 优先使用CustomImage,降级方案为基于用户名生成的首字母头像。
Contact Lists
联系人列表
- Phone contacts with avatars
- Email contacts
- Team member directories
- Organization charts
Best Approach: Circle shape, Medium or Small size, CustomImage or Initials.
- 带头像的手机联系人
- 邮箱联系人
- 团队成员名录
- 组织架构图
最佳实践: 圆形形状、中等或小尺寸、使用CustomImage或首字母头像。
Chat/Messaging
聊天/消息类应用
- Chat conversations with user avatars
- Message threads
- Comment sections
- Forum posts
Best Approach: Small or Medium size, Circle shape, quick loading with Initials or AvatarCharacter.
- 带用户头像的聊天对话
- 消息线程
- 评论区
- 论坛帖子
最佳实践: 小或中等尺寸、圆形形状、使用首字母或AvatarCharacter实现快速加载。
Group Displays
群组展示
- Team collaboration views
- Group chat participants
- Project members
- Shared document contributors
Best Approach: Use Group content type to show up to 3 participants.
- 团队协作视图
- 群聊参与者
- 项目成员
- 共享文档贡献者
最佳实践: 使用Group内容类型最多展示3名参与者。
App Navigation
应用导航
- User menu with profile picture
- Navbar with logged-in user
- Drawer navigation with profile
- App bar with user avatar
Best Approach: Small or ExtraSmall size, Circle shape, initials for quick display.
- 带个人资料图片的用户菜单
- 展示登录用户的导航栏
- 带个人资料的抽屉导航
- 带用户头像的应用栏
最佳实践: 小或超小尺寸、圆形形状、使用首字母实现快速展示。
Implementation Tips
实现提示
-
Initials Generation:
- SingleCharacter: First letter of AvatarName ("Alex" → "A")
- DoubleCharacter single word: First and last letter ("Alex" → "AX")
- DoubleCharacter multiple words: First letter of first two words ("John Doe" → "JD")
-
Avatar Character Selection: 25 pre-defined avatars (Avatar1-Avatar25) provide diverse representation without custom images.
-
Group View Limitations: Supports up to 3 items. If more items in GroupSource, only first 3 are displayed.
-
Image Loading: Use BitmapImage with ms-appx:/// or https:// URIs. Handle loading errors gracefully.
-
Background Colors: Generate consistent colors from user names using hash functions for visual consistency.
-
Size Guidelines:
- ExtraSmall (32x32): Navigation bars, compact lists
- Small (48x48): Chat messages, dense lists
- Medium (64x64): Standard lists, cards
- Large (96x96): Profile pages, prominent displays
- ExtraLarge (128x128): Large profile headers, focus areas
-
Performance: Initials render faster than images. Use initials for long lists, custom images for detail views.
-
Accessibility: Avatar images should have AutomationProperties.Name set to user's name for screen readers.
-
Theme Integration: Use ThemeResource for Background to auto-adapt to light/dark themes:xaml
Background="{ThemeResource SystemAccentColor}" -
Caching: Cache avatar images to avoid repeated downloads. Use local storage for frequently accessed avatars.
-
首字母生成规则:
- 单字符:取AvatarName的第一个字母("Alex" → "A")
- 双字符单单词:取第一个和最后一个字母("Alex" → "AX")
- 双字符多单词:取前两个单词的首字母("John Doe" → "JD")
-
头像角色选择: 25个预定义头像(Avatar1-Avatar25)可实现多样化展示,无需自定义图片。
-
群组视图限制: 最多支持3个条目,若GroupSource中条目超过3个,仅展示前3个。
-
图片加载: 使用带ms-appx:///或https:// URI的BitmapImage,优雅处理加载错误。
-
背景色: 基于用户名通过哈希函数生成一致的背景色,保证视觉一致性。
-
尺寸规范:
- 超小(32x32):导航栏、紧凑列表
- 小(48x48):聊天消息、高密度列表
- 中等(64x64):标准列表、卡片
- 大(96x96):个人资料页、突出展示区域
- 超大(128x128):大型个人资料头部、焦点区域
-
性能: 首字母渲染速度比图片更快,长列表使用首字母头像,详情页使用自定义图片。
-
无障碍: 头像图片需要设置AutomationProperties.Name为用户名,方便屏幕阅读器识别。
-
主题集成: 对Background使用ThemeResource可自动适配亮/暗主题:xaml
Background="{ThemeResource SystemAccentColor}" -
缓存: 缓存头像图片避免重复下载,常用头像存储在本地。
Related Documentation
相关文档
- Content Types: See references/content-types.md for detailed content type options
- Visual Styles: See references/visual-styles.md for shape and size configurations
- Customization: See references/customization.md for appearance customization options
- 内容类型: 查看references/content-types.md了解详细的内容类型选项
- 视觉样式: 查看references/visual-styles.md了解形状和尺寸配置
- 自定义能力: 查看references/customization.md了解外观自定义选项