syncfusion-winui-badge

WinUI でのバッジの実装

Syncfusion WinUI バッジコントロール（SfBadge）は、ほかの UI 要素に重ねて通知、カウント、ステータスインジケーターを表示します。未読メッセージ数、通知インジケーター、ステータスの変更、またはボタン、アイコン、コントロール上に重ねる数値やテキストの表示にバッジを使用します。

このスキルを使用する場面

次のような場合に、このスキルを使用します。

• ボタン、アイコン、UI 要素に通知数を表示する
• メッセージングやメールのインターフェイスに未読メッセージのインジケーターを表示する
• ユーザーアバターやプロフィール画像にステータスバッジを追加する
• ナビゲーション項目に通知を重ねて表示する
• ショッピングカートやリストにカウントインジケーターを実装する
• バッジで警告、エラー、成功の状態を表示する
• コントロール上の特定の位置にバッジを配置する
• バッジの外観（色、形状、アニメーション）をカスタマイズする
• SfBadge または BadgeContainer コンポーネントを使用する

コンポーネントの概要

主な機能：

• 複数の形状（楕円、長方形、楕円形、カスタム）
• 定義済みの色の状態（アクセント、成功、警告、エラー、情報）
• 柔軟な配置と位置揃え
• コンテンツと書式のカスタマイズ
• アニメーションのサポート（スケール、不透明度）
• BadgeContainer の有無にかかわらず使用可能
• 完全なカスタマイズ（色、フォント、線、回転）

基本的な使用パターン：

<notification:BadgeContainer>
    <notification:BadgeContainer.Content>
        <Button Content="Inbox"/>
    </notification:BadgeContainer.Content>
    <notification:BadgeContainer.Badge>
        <notification:SfBadge Content="10" Fill="Success"/>
    </notification:BadgeContainer.Badge>
</notification:BadgeContainer>

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

はじめに

📄 参照： references/getting-started.md

次のような場合に参照します。

• Badge コンポーネントをインストールして設定する
• 最初の Badge 実装を作成する
• ボタンやほかのコントロールに Badge を追加する
• BadgeContainer の使用方法を理解する
• 基本的なバッジのコンテンツとプロパティを設定する
• コンポーネントの構造を確認する

形状と塗りつぶしスタイル

📄 参照： references/shapes-and-fills.md

次のような場合に参照します。

• バッジの形状を変更する（楕円、長方形、楕円形）
• 定義済みの塗りつぶし色を使用する（成功、警告、エラーなど）
• バッジの色の状態を理解する
• CustomShape プロパティでカスタム形状を作成する
• さまざまな種類のバッジに適したビジュアルスタイルを選択する

位置揃えと配置

📄 参照： references/alignment-positioning.md

次のような場合に参照します。

• バッジを水平方向または垂直方向に揃える
• バッジをコントロールの内側、外側、または端の中央に配置する
• カスタム位置（0～1 の範囲）にバッジを配置する
• アンカー配置を使用する
• バッジコンテンツの位置揃えを調整する
• パディングと間隔を調整する
• 自動再配置を処理する

カスタマイズオプション

📄 参照： references/customization.md

次のような場合に参照します。

• カスタムの背景色と前景色を設定する
• 完全にカスタムのバッジ形状を作成する
• ContentTemplate でバッジ UI をカスタマイズする
• 線と境界線を追加する
• テキストの書式（フォント、サイズ、スタイル）を変更する
• バッジを回転する
• 不透明度を調整する
• バッジのサイズを制御する
• バッジを表示または非表示にする

機能と設定

📄 参照： references/features.md

次のような場合に参照します。

• アニメーション（スケールまたは不透明度）を追加する
• コンバーターでバッジコンテンツを書式設定する
• BadgeContainer なしで Badge を使用する
• ListView またはデータテンプレートにバッジを実装する
• 高度なコンテンツ書式を適用する
• 動的なバッジのシナリオに対応する

クイックスタート

1. NuGet パッケージをインストールする

Install-Package Syncfusion.Notifications.WinUI

2. 名前空間をインポートする

xmlns:notification="using:Syncfusion.UI.Xaml.Notifications"

3. 基本的なバッジを実装する

<notification:BadgeContainer>
    <notification:BadgeContainer.Content>
        <Button Content="Notifications" Width="120" Height="40"/>
    </notification:BadgeContainer.Content>
    <notification:BadgeContainer.Badge>
        <notification:SfBadge Content="5" Fill="Error"/>
    </notification:BadgeContainer.Badge>
</notification:BadgeContainer>

よくあるパターン

パターン 1：未読メッセージ数

<notification:BadgeContainer>
    <notification:BadgeContainer.Content>
        <Button Content="Messages" FontSize="16"/>
    </notification:BadgeContainer.Content>
    <notification:BadgeContainer.Badge>
        <notification:SfBadge Content="{x:Bind UnreadCount, Mode=OneWay}"
                             Fill="Error"
                             Shape="Ellipse"/>
    </notification:BadgeContainer.Badge>
</notification:BadgeContainer>

パターン 2：ステータスインジケーター

<notification:BadgeContainer>
    <notification:BadgeContainer.Content>
        <PersonPicture Width="60" Height="60" ProfilePicture="/Assets/user.png"/>
    </notification:BadgeContainer.Content>
    <notification:BadgeContainer.Badge>
        <notification:SfBadge Shape="None"
                             HorizontalPosition="0.85"
                             VerticalPosition="0.85">
            <Ellipse Width="16" Height="16" Fill="LimeGreen"/>
        </notification:SfBadge>
    </notification:BadgeContainer.Badge>
</notification:BadgeContainer>

パターン 3：成功／警告の状態

<notification:SfBadge Content="Verified" 
                     Fill="Success" 
                     Shape="Rectangle"/>


<notification:SfBadge Content="!" 
                     Fill="Warning" 
                     Shape="Ellipse"/>


<notification:SfBadge Content="Error" 
                     Fill="Error" 
                     Shape="Oval"/>

パターン 4：書式設定されたカスタムカウント

// Converter to format large numbers
public class CountFormatConverter : IValueConverter
{
    public object Convert(object value, Type targetType, object parameter, string language)
    {
        if (int.TryParse(value?.ToString(), out int count))
        {
            if (count <= 99) return count.ToString();
            if (count <= 999) return "99+";
            if (count < 99999) return (count / 1000).ToString("0.#") + "K";
            return (count / 1000000).ToString("0.#") + "M";
        }
        return value;
    }
    
    public object ConvertBack(object value, Type targetType, object parameter, string language)
    {
        throw new NotImplementedException();
    }
}

<Page.Resources>
    <local:CountFormatConverter x:Key="countFormatter"/>
</Page.Resources>

<notification:SfBadge Content="{x:Bind Count, Mode=OneWay, Converter={StaticResource countFormatter}}"
                     Background="Red"
                     Foreground="White"/>

パターン 5：ListView 内のバッジ

<ListView ItemsSource="{x:Bind MailItems}">
    <ListView.ItemTemplate>
        <DataTemplate x:DataType="local:MailItem">
            <Grid>
                <Grid.ColumnDefinitions>
                    <ColumnDefinition Width="*"/>
                    <ColumnDefinition Width="Auto"/>
                </Grid.ColumnDefinitions>
                
                <TextBlock Text="{x:Bind FolderName}" 
                          VerticalAlignment="Center"/>
                
                <notification:SfBadge Grid.Column="1"
                                     Content="{x:Bind UnreadCount}"
                                     Fill="Warning"
                                     Shape="Oval"
                                     Visibility="{x:Bind HasUnread}"/>
            </Grid>
        </DataTemplate>
    </ListView.ItemTemplate>
</ListView>

主なプロパティ

コンテンツと表示

• Content - バッジに表示するテキストまたは数値
• ContentTemplate - バッジコンテンツ用のカスタムテンプレート
• Visibility - バッジを表示または非表示にする（Visible/Collapsed）

形状とスタイル

• Shape - バッジの形状：Oval、Rectangle、Ellipse、None、Custom
• Fill - 定義済みの色：Accent、Success、Warning、Error、Information、Alt、Default
• CustomShape - カスタムバッジ形状のジオメトリ
• Background/Foreground - カスタムカラー

位置設定（BadgeContainer を使用）

• HorizontalAlignment - Left、Center、Right（デフォルト：Right）
• VerticalAlignment - Top、Center、Bottom（デフォルト：Top）
• HorizontalAnchor - Inside、Center、Outside（デフォルト：Center）
• VerticalAnchor - Inside、Center、Outside（デフォルト：Center）
• HorizontalPosition - カスタム位置設定用の 0～1 の値（デフォルト：1）
• VerticalPosition - カスタム位置設定用の 0～1 の値（デフォルト：0）

外観

• Width/Height - バッジの寸法（デフォルト：40x30）
• Padding - コンテンツの内側の余白
• FontSize/FontFamily/FontStyle - テキストの書式設定
• Stroke/StrokeThickness - 枠線のスタイル設定
• Rotation - 度数による回転角度
• Opacity - 不透明度（0～1）

アニメーション

• AnimationType - None、Scale、Opacity（コンテンツの変更時にアニメーション）

よくある使用例

1. メール／メッセージアプリ - 受信トレイのボタンに未読メッセージ数を表示
2. Eコマース - ショッピングカートのバッジに商品数を表示
3. ソーシャルメディア - 通知アイコンに通知数を表示
4. ステータスインジケーター - アバターにオンライン／オフライン／離席中のステータスを表示
5. ナビゲーションメニュー - メニュー項目に新着項目のインジケーターを表示
6. ダッシュボードウィジェット - ダッシュボードのカードにアラート数を表示
7. フォーム - フォームフィールドにエラーまたは警告のインジケーターを表示
8. リスト - リスト項目に項目数またはステータスを表示

BadgeContainer と単独の Badge の使い分け

BadgeContainer を使用する場合：

• バッジを別のコントロール（Button、Image、Icon）に重ねる必要がある
• コンテンツに対する位置を自動的に設定したい
• サイズ変更時にバッジをコンテンツに追従させたい

単独の Badge を使用する場合：

• バッジがレイアウト（Grid、StackPanel）の一部である
• レイアウトコンテナーで位置を管理する
• ItemTemplates または DataTemplates でバッジを使用する
• 位置を手動で制御する必要がある

ヒントとベストプラクティス

1. 適切な Fill の色を選ぶ - 肯定的な状態には Success（緑）、アラートには Warning（オレンジ）、重要な通知には Error（赤）を使用します
2. コンテンツは簡潔にする - 1桁の数字、短いテキスト、またはアイコンが最適です
3. 数字には Ellipse 形状を使用する - 数値の表示には Oval または Ellipse 形状が適しています
4. 大きな数値を整形する - バッジが横に広がりすぎないよう、99 を超える数には「99+」と表示します
5. アクセシビリティを考慮する - 背景色と前景色のコントラストを十分に確保します
6. コンテンツの変更をアニメーション化する - Scale または Opacity アニメーションを使用して、更新を目立たせます
7. 値がゼロの場合は非表示にする - 数がゼロまたは null の場合は、Visibility を Collapsed に設定します
8. さまざまなサイズでテストする - 各種コントロールサイズでバッジの外観を確認します
9. 位置を統一する - アプリ内の類似するコントロールでバッジの位置を統一します

トラブルシューティング早見表

問題	解決策
バッジが表示されない	Visibility プロパティを確認し、Content が設定されていることと、親コンテナーのサイズを確認します
位置が正しくない	HorizontalAnchor/VerticalAnchor の値を見直し、配置プロパティを確認します
コンテンツが切れている	Width/Height を大きくするか、Padding を調整します
色が適用されない	Background は Fill を上書きします。どちらか一方を使用してください
アニメーションが動作しない	アニメーションは Content の変更時にのみ実行されます。AnimationType が設定されていることを確認します
バッジが重ならない	単独の Badge ではなく、BadgeContainer を使用していることを確認します

詳しい実装方法については、上記のナビゲーションガイドに記載されている各ドキュメントファイルを参照してください。