syncfusion-winui-avatar-view

WinUI AvatarView の実装

このスキルを使用するタイミング

次のような場合にこのスキルを使用してください。

• ユーザーのプロフィール写真やアバターを表示する
• 円形または正方形のバッジにユーザーのイニシャルを表示する
• アバター画像付きの連絡先リストを作成する
• ユーザーアバターを使ったチャットインターフェイスを実装する
• プロフィール写真付きのチームメンバーを表示する
• グループアバター（最大 3 ユーザー）を表示する
• あらかじめ定義されたアバターキャラクター画像を使用する
• あらゆる UI で視覚的なユーザー表現を作成する

ユーザーが次のいずれかに言及した場合は、必ずこのスキルを適用してください。 WinUI アプリケーションのアバター、プロフィール写真、ユーザー画像、イニシャル、連絡先画像、ユーザーアイコン、プロフィールバッジ、グループアバター。

コンポーネントの概要

SfAvatarView は Syncfusion WinUI コントロールです。カスタム画像、ユーザーのイニシャル、あらかじめ定義されたアバターキャラクター、グループ表示に対応し、ユーザー画像をグラフィカルに表現します。柔軟な形状やサイズを選択でき、幅広いカスタマイズが可能です。

名前空間： Syncfusion.UI.Xaml.Core
NuGet パッケージ： Syncfusion.Core.WinUI
プラットフォーム： WinUI 3 Desktop（.NET 5 以降、Windows App SDK 1.0 以降）

主な利点： イニシャルの自動生成、25 種類のあらかじめ定義されたアバターキャラクター、グループ表示に標準で対応しており、カスタム実装なしでアバター機能一式を利用できます。

ドキュメントとナビゲーションガイド

はじめに

📄 参照： references/getting-started.md

• インストールと NuGet パッケージのセットアップ
• 名前空間のインポートと基本的な初期化
• デフォルトのアバター動作（Avatar1、Circle、Small）
• カスタム画像用の ImageSource プロパティ
• ライセンス登録の要件
• 最初の完全なサンプル

コンテンツの種類

📄 参照： references/content-types.md

• 5 種類のコンテンツ（Default、Initials、CustomImage、AvatarCharacter、GroupView）
• イニシャルの生成（SingleCharacter、DoubleCharacter）
• 25 種類のあらかじめ定義されたアバターキャラクター
• ImageSource によるカスタム画像のサポート
• 複数ユーザー向けのグループ表示（最大 3 ユーザー）
• GroupSource とメンバーのパス設定
• 適切なコンテンツの種類の選び方

ビジュアルスタイルと形状

📄 参照： references/visual-styles.md

• AvatarShape プロパティ（Circle、Square、Custom）
• AvatarSize プロパティ（ExtraSmall、Small、Medium、Large、ExtraLarge）
• サイズの比較とガイドライン
• CornerRadius によるカスタム形状
• デザイン要件に応じた形状の選択

カスタマイズオプション

📄 参照： references/customization.md

• 境界線のカスタマイズ（BorderBrush、BorderThickness）
• Background プロパティ（単色）
• グラデーション背景（LinearGradientBrush、RadialGradientBrush）
• フォントのカスタマイズ（FontFamily、Foreground、FontSize）
• テーマとの統合
• カスタマイズの組み合わせ

クイックスタートの例

<Page
    xmlns:syncfusion="using:Syncfusion.UI.Xaml.Core">
    <Grid>
        
        <syncfusion:SfAvatarView 
            x:Name="userAvatar"
            ContentType="Initials"
            AvatarName="John Doe"
            InitialsType="DoubleCharacter"
            AvatarSize="Large"
            Background="CornflowerBlue"
            Foreground="White"
            AvatarShape="Circle"/>
    </Grid>
</Page>

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;

よくあるパターン

1. イニシャル付きのユーザープロフィールアバター

<syncfusion:SfAvatarView 
    ContentType="Initials"
    AvatarName="Sarah Johnson"
    InitialsType="DoubleCharacter"
    AvatarSize="ExtraLarge"
    AvatarShape="Circle"
    Background="#FF6A5ACD"
    Foreground="White"/>

使用する場面： ユーザープロフィール、アカウントページ、設定画面。

2. カスタム画像付きの連絡先リスト

<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. アバターキャラクター付きのチャットメッセージ

<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. グループアバター（複数ユーザー）

<syncfusion:SfAvatarView 
    ContentType="Group"
    GroupSource="{x:Bind TeamMembers}"
    ImageSourceMemberPath="ProfileImage"
    InitialsMemberPath="Name"
    BackgroundColorMemberPath="BackgroundColor"
    InitialsColorMemberPath="InitialsColor"
    AvatarSize="Large"/>

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. データの有無に応じた動的なアバター

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. アプリアイコン用の境界線付き正方形アバター

<syncfusion:SfAvatarView 
    ContentType="CustomImage"
    ImageSource="AppIcon.png"
    AvatarShape="Square"
    AvatarSize="Large"
    BorderBrush="Gray"
    BorderThickness="1"
    CornerRadius="8"/>

使用する場面： アプリアイコン、サービスロゴ、組織バッジ、正方形のプロフィール画像。

7. グラデーション背景とイニシャルのアバター

<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>

使用する場面： ブランドカラーのグラデーションを使った、モダンで視覚的に魅力的なアバター。

主なプロパティ

プロパティ	型	既定値	説明
ContentType	AvatarContentType	Default	表示するコンテンツの種類です。選択肢：Default、Initials、CustomImage、AvatarCharacter、Group。
ImageSource	ImageSource	null	CustomImage コンテンツタイプで使用するカスタム画像です。ユーザーのプロフィール画像へのパスです。
AvatarName	string	null	イニシャルの生成元となる名前です。Initials コンテンツタイプで使用します。
AvatarCharacter	AvatarCharacter	Avatar1	定義済みのアバターキャラクター（Avatar1～Avatar25）です。AvatarCharacter コンテンツタイプで使用します。
InitialsType	AvatarInitialsType	SingleCharacter	イニシャルの形式です。選択肢：SingleCharacter（最初の文字）、DoubleCharacter（2文字）。
AvatarShape	AvatarShape	Circle	見た目の形状です。選択肢：Circle、Square、Custom。
AvatarSize	AvatarSize	Small	定義済みのサイズです。選択肢：ExtraSmall、Small、Medium、Large、ExtraLarge。
GroupSource	IEnumerable	null	Group コンテンツタイプで使用するコレクションです。最大3項目に対応します。
InitialsMemberPath	string	null	GroupSource の項目でイニシャルを指定するプロパティパスです。
ImageSourceMemberPath	string	null	GroupSource の項目で画像を指定するプロパティパスです。
BackgroundColorMemberPath	string	null	GroupSource の項目で背景色を指定するプロパティパスです。
InitialsColorMemberPath	string	null	GroupSource の項目でイニシャルの色を指定するプロパティパスです。
Background	Brush	Gray	アバターの背景色またはグラデーションです。
Foreground	Brush	Black	イニシャルの文字色です。
BorderBrush	Brush	null	アバターの周囲の境界線の色です。
BorderThickness	Thickness	0	アバターの周囲の境界線の太さです。
CornerRadius	CornerRadius	Auto	Custom 形状の角の半径です。
FontFamily	FontFamily	Segoe UI	イニシャルの文字に使用するフォントです。
FontSize	double	Auto	イニシャルのフォントサイズです（AvatarSize に基づいて自動計算されます）。

一般的なユースケース

ユーザープロフィール

• ユーザーアバターを表示するプロフィールページ
• プロフィール画像を表示するアカウント設定
• ユーザーダッシュボード
• メンバープロフィール

おすすめの方法： 画像が利用できる場合は CustomImage を使い、利用できない場合はユーザー名から生成した Initials を使います。

連絡先リスト

• アバター付きの電話連絡先
• メール連絡先
• チームメンバーのディレクトリ
• 組織図

おすすめの方法： Circle 形状、Medium または Small サイズ、CustomImage または Initials を使います。

チャット／メッセージ

• ユーザーアバター付きのチャット会話
• メッセージスレッド
• コメントセクション
• フォーラム投稿

おすすめの方法： Small または Medium サイズ、Circle 形状を使い、Initials または AvatarCharacter ですばやく読み込みます。

グループ表示

• チームコラボレーション画面
• グループチャットの参加者
• プロジェクトメンバー
• 共有ドキュメントの共同編集者

おすすめの方法： Group コンテンツタイプを使うと、最大3人の参加者を表示できます。

アプリのナビゲーション

• プロフィール画像付きのユーザーメニュー
• ログイン中のユーザーを表示するナビゲーションバー
• プロフィール付きのドロワーナビゲーション
• ユーザーアバター付きのアプリバー

おすすめの方法： Small または ExtraSmall サイズ、Circle 形状を使い、すばやく表示するにはイニシャルを使います。

実装のヒント

1. イニシャルの生成：

   • SingleCharacter：AvatarName の最初の文字（「Alex」→「A」）
   • DoubleCharacter（単語が1つの場合）：最初と最後の文字（「Alex」→「AX」）
   • DoubleCharacter（単語が複数の場合）：最初の2つの単語の最初の文字（「John Doe」→「JD」）

2. アバターの文字の選択： 定義済みのアバター（Avatar1-Avatar25）が25種類あり、カスタム画像を使わずに多様な表現を実現できます。

3. グループ表示の制限： 最大3項目まで対応しています。GroupSource に3項目を超えるアイテムがある場合、最初の3項目だけが表示されます。

4. 画像の読み込み： ms-appx:/// または https:// の URI を指定して BitmapImage を使用します。読み込みエラーは適切に処理してください。

5. 背景色： ハッシュ関数を使ってユーザー名から一貫性のある色を生成し、視覚的な統一感を保ちます。

6. サイズのガイドライン：

   • ExtraSmall（32x32）：ナビゲーションバー、コンパクトなリスト
   • Small（48x48）：チャットメッセージ、密度の高いリスト
   • Medium（64x64）：標準的なリスト、カード
   • Large（96x96）：プロフィールページ、目立たせる表示
   • ExtraLarge（128x128）：大きなプロフィールヘッダー、注目領域

7. パフォーマンス： イニシャルは画像よりも速く描画されます。長いリストではイニシャルを、詳細ビューではカスタム画像を使用してください。

8. アクセシビリティ： アバター画像の AutomationProperties.Name には、スクリーンリーダーで読み上げられるよう、ユーザー名を設定してください。

9. テーマとの統合： Background に ThemeResource を使用すると、ライトテーマとダークテーマに自動的に適応します：

   Background="{ThemeResource SystemAccentColor}"
   

10. キャッシュ： アバター画像をキャッシュして、繰り返しダウンロードされないようにします。頻繁にアクセスするアバターにはローカルストレージを使用してください。

関連ドキュメント

• コンテンツの種類： コンテンツの種類のオプションについて詳しくは、references/content-types.md を参照してください
• ビジュアルスタイル： 形状とサイズの設定について詳しくは、references/visual-styles.md を参照してください
• カスタマイズ： 外観のカスタマイズオプションについて詳しくは、references/customization.md を参照してください