syncfusion-winui-badge

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Badges in WinUI

在WinUI中实现徽章

The Syncfusion WinUI Badge control (

SfBadge

) displays notifications, counts, or status indicators overlaid on other UI elements. Use badges to show unread message counts, notification indicators, status changes, or any numeric/text overlay on buttons, icons, or controls.

Syncfusion WinUI Badge控件（

SfBadge

）可在其他UI元素上方显示通知、计数或状态指示器。你可以使用徽章在按钮、图标或控件上显示未读消息计数、通知指示器、状态变化，或任何数字/文本覆盖层。

When to Use This Skill

何时使用本技能

Use this skill when you need to:

Display notification counts on buttons, icons, or UI elements
Show unread message indicators in messaging or email interfaces
Add status badges to user avatars or profile pictures
Create notification overlays on navigation items
Implement count indicators for shopping carts or lists
Show warning, error, or success states with badges
Position badges at specific locations on controls
Customize badge appearance (colors, shapes, animations)
Work with the
```
SfBadge
```
or
```
BadgeContainer
```
components

当你需要以下功能时，可以使用本技能：

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

Component Overview

组件概述

Key Capabilities:

Multiple shapes (Oval, Rectangle, Ellipse, Custom)
Predefined color states (Accent, Success, Warning, Error, Information)
Flexible positioning and alignment
Custom content and formatting
Animation support (Scale, Opacity)
Works with or without
```
BadgeContainer
```
Complete customization (colors, fonts, strokes, rotation)

Basic Usage Pattern:

xaml

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

核心功能：

多种形状（Oval、Rectangle、Ellipse、Custom）
预定义颜色状态（Accent、Success、Warning、Error、Information）
灵活的定位与对齐
自定义内容与格式
动画支持（Scale、Opacity）
可搭配或不搭配
```
BadgeContainer
```
使用
完全自定义（颜色、字体、描边、旋转）

基本使用模式：

xaml

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

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md

When you need to:

Install and set up the Badge component
Create your first Badge implementation
Add Badge to buttons or other controls
Understand BadgeContainer usage
Set basic badge content and properties
Learn the component structure

📄 阅读： references/getting-started.md

当你需要：

安装并设置Badge组件
创建你的第一个Badge实现
为按钮或其他控件添加Badge
了解BadgeContainer的用法
设置徽章的基本内容与属性
学习组件结构

Shapes and Fill Styles

形状与填充样式

📄 Read: references/shapes-and-fills.md

When you need to:

Change badge shape (Oval, Rectangle, Ellipse)
Use predefined fill colors (Success, Warning, Error, etc.)
Understand badge color states
Create custom shapes with
```
CustomShape
```
property
Choose appropriate visual styles for different badge types

📄 阅读： references/shapes-and-fills.md

当你需要：

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

Alignment and Positioning

对齐与定位

📄 Read: references/alignment-positioning.md

When you need to:

Align badge horizontally or vertically
Position badge inside, outside, or centered on edges
Place badge at custom positions (0-1 range)
Use anchor positioning
Adjust badge content alignment
Control padding and spacing
Handle auto re-positioning

📄 阅读： references/alignment-positioning.md

当你需要：

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

Customization Options

自定义选项

📄 Read: references/customization.md

When you need to:

Set custom background and foreground colors
Create completely custom badge shapes
Customize badge UI with ContentTemplate
Add strokes and borders
Change text formatting (font, size, style)
Rotate badges
Adjust opacity
Control badge size
Hide or show badges

📄 阅读： references/customization.md

当你需要：

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

Features and Configuration

功能与配置

📄 Read: references/features.md

When you need to:

Add animations (Scale or Opacity)
Format badge content with converters
Use Badge without BadgeContainer
Implement badges in ListView or data templates
Apply advanced content formatting
Handle dynamic badge scenarios

📄 阅读： references/features.md

当你需要：

添加动画（Scale或Opacity）
使用转换器格式化徽章内容
不使用BadgeContainer来使用Badge
在ListView或数据模板中实现徽章
应用高级内容格式化
处理动态徽章场景

Quick Start

快速开始

1. Install NuGet Package

1. 安装NuGet包

powershell

Install-Package Syncfusion.Notifications.WinUI

powershell

Install-Package Syncfusion.Notifications.WinUI

2. Import Namespace

2. 导入命名空间

xaml

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

xaml

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

3. Basic Badge Implementation

3. 基本徽章实现

xaml

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

xaml

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

Common Patterns

常见模式

Pattern 1: Unread Message Count

模式1：未读消息计数

xaml

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

xaml

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

Pattern 2: Status Indicator

模式2：状态指示器

xaml

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

xaml

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

Pattern 3: Success/Warning States

模式3：成功/警告状态

xaml

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

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

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

xaml

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

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

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

Pattern 4: Custom Formatted Count

模式4：自定义格式化计数

csharp

// 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();
    }
}

xaml

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

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

csharp

// 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();
    }
}

xaml

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

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

Pattern 5: Badge in ListView

模式5：ListView中的徽章

xaml

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

xaml

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

Key Properties

核心属性

Content and Display

内容与显示

Content - Text or number to display in badge
ContentTemplate - Custom template for badge content
Visibility - Show or hide badge (Visible/Collapsed)

Content - 徽章中显示的文本或数字
ContentTemplate - 徽章内容的自定义模板
Visibility - 显示或隐藏徽章（Visible/Collapsed）

Shape and Style

形状与样式

Shape - Badge shape: Oval, Rectangle, Ellipse, None, Custom
Fill - Predefined color: Accent, Success, Warning, Error, Information, Alt, Default
CustomShape - Geometry for custom badge shapes
Background/Foreground - Custom colors

Shape - 徽章形状：Oval、Rectangle、Ellipse、None、Custom
Fill - 预定义颜色：Accent、Success、Warning、Error、Information、Alt、Default
CustomShape - 自定义徽章形状的几何图形
Background/Foreground - 自定义颜色

Positioning (with BadgeContainer)

定位（搭配BadgeContainer使用）

HorizontalAlignment - Left, Center, Right (default: Right)
VerticalAlignment - Top, Center, Bottom (default: Top)
HorizontalAnchor - Inside, Center, Outside (default: Center)
VerticalAnchor - Inside, Center, Outside (default: Center)
HorizontalPosition - 0 to 1 for custom positioning (default: 1)
VerticalPosition - 0 to 1 for custom positioning (default: 0)

HorizontalAlignment - 左对齐、居中、右对齐（默认：右对齐）
VerticalAlignment - 顶部、居中、底部（默认：顶部）
HorizontalAnchor - 内部、居中、外部（默认：居中）
VerticalAnchor - 内部、居中、外部（默认：居中）
HorizontalPosition - 自定义定位的0-1范围值（默认：1）
VerticalPosition - 自定义定位的0-1范围值（默认：0）

Appearance

外观

Width/Height - Badge dimensions (default: 40x30)
Padding - Internal content spacing
FontSize/FontFamily/FontStyle - Text formatting
Stroke/StrokeThickness - Border styling
Rotation - Rotation angle in degrees
Opacity - Transparency (0-1)

Width/Height - 徽章尺寸（默认：40x30）
Padding - 内容内部间距
FontSize/FontFamily/FontStyle - 文本格式
Stroke/StrokeThickness - 边框样式
Rotation - 旋转角度（度数）
Opacity - 透明度（0-1）

Animation

动画

AnimationType - None, Scale, Opacity (animates on content change)

AnimationType - 无、Scale、Opacity（内容变化时触发动画）

Common Use Cases

常见使用场景

Email/Messaging Apps - Unread message counts on inbox buttons
E-commerce - Item counts in shopping cart badges
Social Media - Notification counts on notification icons
Status Indicators - Online/offline/away status on avatars
Navigation Menus - New item indicators on menu items
Dashboard Widgets - Alert counts on dashboard cards
Forms - Error or warning indicators on form fields
Lists - Item counts or status on list items

邮件/消息应用 - 收件箱按钮上的未读消息计数
电商应用 - 购物车徽章中的商品数量
社交媒体 - 通知图标上的通知计数
状态指示器 - 头像上的在线/离线/离开状态
导航菜单 - 菜单项上的新内容指示器
仪表板组件 - 仪表板卡片上的警报计数
表单 - 表单字段上的错误或警告指示器
列表 - 列表项上的计数或状态

When to Use BadgeContainer vs Standalone

何时使用BadgeContainer vs 独立徽章

Use BadgeContainer when:

Badge needs to overlay another control (Button, Image, Icon)
You need automatic positioning relative to content
You want badge to follow content when resizing

Use standalone Badge when:

Badge is part of a layout (Grid, StackPanel)
You're handling positioning with layout containers
Using badges in ItemTemplates or DataTemplates
You need manual position control

使用BadgeContainer的场景：

需要在其他控件（按钮、图片、图标）上方叠加徽章
需要相对于内容自动定位
希望徽章在内容调整大小时跟随内容

使用独立徽章的场景：

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

Tips and Best Practices

技巧与最佳实践

Choose appropriate Fill colors - Use Success (green) for positive states, Warning (orange) for alerts, Error (red) for critical notifications
Keep content concise - Single digit, short text, or icon works best
Use Ellipse shape for numbers - Oval or Ellipse shapes work well for numeric counts
Format large numbers - Display "99+" for counts over 99 to avoid badge becoming too wide
Consider accessibility - Ensure sufficient color contrast between background and foreground
Animate content changes - Use Scale or Opacity animation to draw attention to updates
Hide when zero - Set Visibility to Collapsed when count is zero or null
Test different sizes - Verify badge appearance on various control sizes
Use consistent positioning - Keep badge position consistent across similar controls in your app

选择合适的Fill颜色 - 使用Success（绿色）表示积极状态，Warning（橙色）表示提醒，Error（红色）表示关键通知
保持内容简洁 - 单个数字、短文本或图标效果最佳
数字使用Ellipse形状 - Oval或Ellipse形状适合显示数字计数
格式化大数字 - 计数超过99时显示“99+”，避免徽章过宽
考虑可访问性 - 确保背景与前景色之间有足够的对比度
为内容变化添加动画 - 使用Scale或Opacity动画吸引用户注意更新
计数为0时隐藏 - 当计数为0或null时，将Visibility设置为Collapsed
测试不同尺寸 - 在各种控件尺寸上验证徽章外观
保持定位一致 - 在应用中类似控件上的徽章位置保持一致

Troubleshooting Quick Reference

故障排除快速参考

Issue	Solution
Badge not visible	Check Visibility property, ensure Content is set, verify parent container size
Position incorrect	Review HorizontalAnchor/VerticalAnchor values, check alignment properties
Content cut off	Increase Width/Height or adjust Padding
Color not applying	Background overrides Fill - use one or the other
Animation not working	Animation only triggers on Content change, verify AnimationType is set
Badge not overlapping	Ensure using BadgeContainer, not standalone Badge

For detailed implementation guidance, refer to the specific documentation files listed in the Navigation Guide above.

问题	解决方案
徽章不可见	检查Visibility属性，确保已设置Content，验证父容器尺寸
位置不正确	检查HorizontalAnchor/VerticalAnchor值，查看对齐属性
内容被截断	增加Width/Height或调整Padding
颜色未生效	Background会覆盖Fill - 只使用其中一个
动画不工作	动画仅在Content变化时触发，确认已设置AnimationType
徽章未叠加	确保使用的是BadgeContainer，而非独立徽章

如需详细的实现指导，请参考上述导航指南中列出的具体文档文件。