syncfusion-wpf-badge

实现 Syncfusion WPF 徽章（SfBadge）

何时使用此技能

在以下情况下使用此技能：

• 为 UI 元素（按钮、图标、图像）添加通知徽章
• 显示未读消息数或状态指示器
• 使用颜色、形状和动画自定义徽章外观
• 控制徽章在容器中的位置和对齐方式
• 在列表或集合中实现数据绑定的徽章内容

组件概述

Syncfusion WPF 徽章（SfBadge）是一种通知组件，用于在其他 UI 元素上显示数量、状态或提醒。常见用例包括：

• 未读消息数 — 在邮箱按钮上显示“99+”
• 状态指示器 — 使用彩色徽章显示在线/离线状态
• 提醒通知 — 使用不同颜色表示错误、警告或成功状态
• 自定义通知 — 绑定到数据属性，以实现动态更新

文档和导航指南

入门

📄 阅读： references/getting-started.md

• 安装和程序集设置
• 通过 XAML 和 C# 添加 SfBadge
• 包含按钮的基础徽章示例
• 设置显示内容
• 常见设置问题及解决方案

对齐和定位

📄 阅读： references/alignment-positioning.md

• HorizontalAlignment 和 VerticalAlignment 属性（Left、Center、Right、Stretch）
• HorizontalAnchor 和 VerticalAnchor 定位方式（Inside、Center、Outside）
• 使用 HorizontalPosition 和 VerticalPosition 精确定位（0-1 范围）
• 使用 HorizontalAnchorPosition 和 VerticalAnchorPosition 自定义对齐方式
• 在徽章边界内对齐内容

自定义

📄 阅读： references/customization.md

• 预定义颜色（Fill 属性：Accent、Success、Error、Warning、Information）
• 自定义背景色和前景色
• 预定义形状（Rectangle、Oval、Ellipse、None）
• 通过 CustomShape 属性使用自定义 SVG 形状
• 配置徽章大小

内容和动画

📄 阅读： references/content-animation.md

• Content 属性和显示格式
• 用于自定义 UI 的 ContentTemplate
• AnimationType（Scale、Opacity、None）
• 数字格式和显示约定
• 文本格式（FontFamily、FontSize、FontStyle）

外观和功能

📄 阅读： references/appearance-features.md

• 自定义 Stroke 和 StrokeThickness
• Opacity 属性和透明度
• 用于隐藏徽章的 Visibility 属性
• 直接使用徽章与使用 SfBadge.Badge 容器
• 与 ListView 和 ItemsSource 的数据绑定
• 集成模式和边缘情况

快速入门示例

<Button Width="100" Height="50" Content="Inbox">
    <notification:SfBadge.Badge>
        <notification:SfBadge 
            Content="10" 
            Fill="Success"
            Shape="Oval"
            x:Name="badge"/>
    </notification:SfBadge.Badge>
</Button>

// C# equivalent
SfBadge sfBadge = new SfBadge();
sfBadge.Name = "badge";
sfBadge.Content = "10";
sfBadge.Fill = BadgeFill.Success;
sfBadge.Shape = BadgeShape.Oval;

Button button = new Button();
button.Width = 100;
button.Height = 50;
button.Content = "Inbox";

SfBadge.SetBadge(button, sfBadge);

常见模式

模式 1：可控制位置的状态徽章

使用对齐属性将徽章放置在特定角落：

<notification:SfBadge 
    HorizontalAlignment="Right" 
    VerticalAlignment="Top" 
    Content="5"/>


<notification:SfBadge 
    HorizontalAlignment="Left" 
    VerticalAlignment="Bottom" 
    Content="3"/>

模式 2：带动画的计数更新

在徽章内容更改时启用动画：

<notification:SfBadge 
    AnimationType="Scale" 
    Content="{Binding UnreadCount}"
    Fill="Error"/>

模式 3：自定义样式徽章

结合颜色、形状和文本格式：

<notification:SfBadge 
    Fill="Information"
    Shape="Ellipse"
    FontSize="16"
    FontStyle="Italic"
    Content="NEW"/>

模式 4：数据绑定集合

在 ListView 中显示徽章，并根据条件控制其可见性：

<ListView ItemsSource="{Binding MailItems}">
    <ListView.ItemTemplate>
        <DataTemplate>
            <Grid>
                <TextBlock Text="{Binding ItemName}"/>
                <notification:SfBadge 
                    Content="{Binding UnreadCount}"
                    Visibility="{Binding HasMessages, Converter={StaticResource BoolToVisibilityConverter}}"
                    Shape="Oval"/>
            </Grid>
        </DataTemplate>
    </ListView.ItemTemplate>
</ListView>

关键属性

属性	默认值	用途
Content	null	徽章显示文本/值
Fill	Accent	预定义的颜色状态（Success、Error、Warning 等）
Shape	Oval	徽章形状（Oval、Rectangle、Ellipse、None、Custom）
HorizontalAlignment	Right	水平位置（Left、Center、Right、Stretch）
VerticalAlignment	Top	垂直位置（Top、Center、Bottom、Stretch）
HorizontalAnchor	Center	锚定模式（Inside、Center、Outside、Custom）
VerticalAnchor	Center	锚定模式（Inside、Center、Outside、Custom）
AnimationType	None	内容更改时的动画（Scale、Opacity、None）
Background	null	自定义背景颜色（覆盖 Fill）
Foreground	null	自定义文本颜色
FontSize	14	文本大小（像素）
Opacity	1	透明度（范围为 0-1）
Visibility	Visible	显示/隐藏徽章（Visible、Collapsed）

常见用例

用例 1：未读消息指示器

在收件箱按钮上显示未读消息数量徽章，并在更新时添加动画。

用例 2：在线状态指示器

在用户头像上显示小型彩色徽章（绿色表示在线，红色表示离线），并使用自定义定位。

用例 3：错误/警告提示

在表单控件上显示红色或橙色徽章，以指示验证错误或警告。

用例 4：动态通知计数器

随着通知到达，通过数据绑定更新徽章内容，并添加缩放动画效果。

用例 5：多状态状态徽章

根据应用状态或用户角色显示不同样式（颜色、形状、内容）的徽章。