syncfusion-winui-badge

在 WinUI 中实现徽章

Syncfusion WinUI 徽章控件（SfBadge）可在其他 UI 元素上叠加显示通知、计数或状态指示器。使用徽章显示未读消息数、通知指示器、状态更改，或叠加在按钮、图标或控件上的任意数字或文本。

何时使用此技能

在需要以下功能时使用此技能：

• 在按钮、图标或 UI 元素上显示通知计数
• 在消息或电子邮件界面中显示未读消息指示器
• 为用户头像或个人资料图片添加状态徽章
• 在导航项上创建通知叠加层
• 为购物车或列表实现计数指示器
• 使用徽章显示警告、错误或成功状态
• 在控件上的特定位置放置徽章
• 自定义徽章外观（颜色、形状、动画）
• 使用 SfBadge 或 BadgeContainer 组件

组件概述

主要功能：

• 多种形状（Oval、Rectangle、Ellipse、Custom）
• 预定义颜色状态（Accent、Success、Warning、Error、Information）
• 灵活的位置和对齐方式
• 自定义内容和格式
• 支持动画（Scale、Opacity）
• 可与 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

适用于以下需求：

• 更改徽章形状（Oval、Rectangle、Ellipse）
• 使用预定义填充颜色（Success、Warning、Error 等）
• 了解徽章颜色状态
• 使用 CustomShape 属性创建自定义形状
• 为不同类型的徽章选择合适的视觉样式

对齐和定位

📄 阅读： references/alignment-positioning.md

适用于以下需求：

• 水平或垂直对齐徽章
• 将徽章放置在边缘内侧、外侧或居中位置
• 将徽章放置在自定义位置（0-1 范围）
• 使用锚点定位
• 调整徽章内容对齐方式
• 控制内边距和间距
• 处理自动重新定位

自定义选项

📄 阅读： references/customization.md

适用于以下需求：

• 设置自定义背景色和前景色
• 创建完全自定义的徽章形状
• 使用 ContentTemplate 自定义徽章 UI
• 添加描边和边框
• 更改文本格式（字体、大小、样式）
• 旋转徽章
• 调整不透明度
• 控制徽章大小
• 隐藏或显示徽章

功能和配置

📄 阅读： references/features.md

适用于以下需求：

• 添加动画（Scale 或 Opacity）
• 使用转换器格式化徽章内容
• 不使用 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. 电子商务 - 在购物车徽章中显示商品数量
3. 社交媒体 - 在通知图标上显示通知数量
4. 状态指示器 - 在头像上显示在线/离线/离开状态
5. 导航菜单 - 在菜单项上显示新项目指示器
6. 仪表板组件 - 在仪表板卡片上显示警报数量
7. 表单 - 在表单字段上显示错误或警告指示器
8. 列表 - 在列表项上显示项目数量或状态

何时使用 BadgeContainer，何时使用独立 Badge

在以下情况使用 BadgeContainer：

• 徽章需要叠加在其他控件（Button、Image、Icon）上
• 需要相对于内容自动定位
• 希望调整大小时徽章能跟随内容移动

在以下情况使用独立 Badge：

• 徽章是布局（Grid、StackPanel）的一部分
• 通过布局容器控制位置
• 在 ItemTemplates 或 DataTemplates 中使用徽章
• 需要手动控制位置

提示和最佳实践

1. 选择合适的 Fill 颜色 - 正面状态使用 Success（绿色），警告使用 Warning（橙色），重要通知使用 Error（红色）
2. 保持内容简洁 - 单个数字、简短文本或图标效果最佳
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
徽章未叠加显示	确保使用 BadgeContainer，而非独立 Badge

有关详细的实现指南，请参阅上方导航指南中列出的相关文档文件。