Windows应用的徽章通知

通知徽章传达特定应用的摘要或状态信息。它们可以是数字（1-99）或一组系统提供的标志符号之一。最好通过徽章传达的信息示例包括在线游戏中的网络连接状态、消息应用中的用户状态、邮件应用中的未读邮件数以及社交媒体应用中的新帖子数。

无论应用是否正在运行，通知徽章都会显示在应用的任务栏图标上及其开始屏幕磁贴的右下角。徽章可以显示在任意大小的磁贴上。

Note

无法提供自己的锁屏提醒图像;只能使用系统提供的锁屏提醒图像。

数字徽章

Value	Badge	XML
从 1 到 99 的数字。值 0 等效于字形值“无”，并将清除徽章。		`<badge value="1"/>`
任何大于 99 的数字。		`<badge value="100"/>`

图标徽章

徽章可以显示一组不可扩展的状态图标，而不是数字。

Status	Glyph	XML
none	（未显示徽章。）	`<badge value="none"/>`
活动	用于标识“活动”状态的徽章。	`<badge value="activity"/>`
alarm		`<badge value="alarm"/>`
警报		`<badge value="alert"/>`
attention		`<badge value="attention"/>`
available		`<badge value="available"/>`
away		`<badge value="away"/>`
busy		`<badge value="busy"/>`
错误		`<badge value="error"/>`
newMessage	表示“newMessage”状态的图标徽章。	`<badge value="newMessage"/>`
paused		`<badge value="paused"/>`
playing		`<badge value="playing"/>`
unavailable		`<badge value="unavailable"/>`

在 Windows 应用 SDK 应用中设置徽章

从 Windows 应用 SDK 1.7 开始，使用命名空间中的 Microsoft.Windows.BadgeNotifications 类来设置和清除徽章。这是 Windows 应用 SDK 应用推荐的方法。无需生成 XML 有效负载，而是调用方法并传递数字或 BadgeNotificationGlyph 值。

重要 API： BadgeNotificationManager 类、 BadgeNotificationGlyph 枚举

打开 WinUI 3 库应用并查看 BadgeNotificationManager 的实际效果

WinUI 3 示例库应用包含 WinUI 控件和功能的交互式示例。从 Microsoft Store 或浏览 GitHub 上的源代码获取应用。

Important

BadgeNotificationManager 需要包标识。如果你的应用没有包标识，例如，如果它是未打包的，调用 SetBadgeAsCount、SetBadgeAsGlyph 和 ClearBadge 会引发异常。有关详细信息，请参阅Windows应用中的包标识概述。

标记显示在应用的任务栏图标上。如果应用固定到任务栏，即使应用未运行，也会显示徽章。若要获取你的应用的 BadgeNotificationManager 实例，请使用 Current 属性。

以下示例基于 WinUI 3 Gallery 示例。若要使用它们，请将 using Microsoft.Windows.BadgeNotifications; 指令添加到代码文件中。

设置数字角标

调用 SetBadgeAsCount 并传递要显示的数字。如果数字大于 99，则角标显示“99+”。

private void SetBadgeCountButton_Click(object sender, RoutedEventArgs e)
{
    // Show the number 5 on the app's taskbar icon.
    BadgeNotificationManager.Current.SetBadgeAsCount(5);
}

设置图标徽章

调用 SetBadgeAsGlyph 并传递一个 BadgeNotificationGlyph 值。枚举值对应于 Glyph 标记表中的字形。

private void SetBadgeGlyphButton_Click(object sender, RoutedEventArgs e)
{
    // Show the alert glyph on the app's taskbar icon.
    BadgeNotificationManager.Current.SetBadgeAsGlyph(BadgeNotificationGlyph.Alert);
}

清除角标

调用 ClearBadge 以删除徽章。将计数设置为 0 或使用 BadgeNotificationGlyph.None 字形也会清除徽章。

private void ClearBadgeButton_Click(object sender, RoutedEventArgs e)
{
    BadgeNotificationManager.Current.ClearBadge();
}

使用 UWP BadgeUpdateManager API 创建徽章

这些示例使用 Windows 运行时命名空间中的 Windows.UI.Notifications 类，这是 UWP 应用的徽章 API。使用前面表中的值将徽章构建为 XML 有效负载。如果应用使用 Windows 应用 SDK 1.7 或更高版本，请改用 BadgeNotificationManager。

创建数字徽章

private void setBadgeNumber(int num)
{

    // Get the blank badge XML payload for a badge number
    XmlDocument badgeXml = 
        BadgeUpdateManager.GetTemplateContent(BadgeTemplateType.BadgeNumber);

    // Set the value of the badge in the XML to our number
    XmlElement badgeElement = badgeXml.SelectSingleNode("/badge") as XmlElement;
    badgeElement.SetAttribute("value", num.ToString());

    // Create the badge notification
    BadgeNotification badge = new BadgeNotification(badgeXml);

    // Create the badge updater for the application
    BadgeUpdater badgeUpdater = 
        BadgeUpdateManager.CreateBadgeUpdaterForApplication();

    // And update the badge
    badgeUpdater.Update(badge);

}

创建字形徽章

private void updateBadgeGlyph()
{
    string badgeGlyphValue = "alert";

    // Get the blank badge XML payload for a badge glyph
    XmlDocument badgeXml = 
        BadgeUpdateManager.GetTemplateContent(BadgeTemplateType.BadgeGlyph);

    // Set the value of the badge in the XML to our glyph value
    Windows.Data.Xml.Dom.XmlElement badgeElement = 
        badgeXml.SelectSingleNode("/badge") as Windows.Data.Xml.Dom.XmlElement;
    badgeElement.SetAttribute("value", badgeGlyphValue);

    // Create the badge notification
    BadgeNotification badge = new BadgeNotification(badgeXml);

    // Create the badge updater for the application
    BadgeUpdater badgeUpdater = 
        BadgeUpdateManager.CreateBadgeUpdaterForApplication();

    // And update the badge
    badgeUpdater.Update(badge);

}

清除徽章

private void clearBadge()
{
    BadgeUpdateManager.CreateBadgeUpdaterForApplication().Clear();
}

获取示例代码

Windows 应用 SDK 通知示例
演示如何发送应用通知和徽章更新。

反馈

此页面是否有帮助？

上次更新时间为 2026-10-20