徽章

Badge API 允许开发人员在主屏幕上设置应用图标锁屏提醒数字。

---

要使用 Badge API，需要满足以下先决条件：

Android

支持 Android 设备所需的其他配置。 请参阅下面的 Android 部分。

iOS/MacCatalyst

为应用授予锁屏提醒权限。 系统会自动请求它。

Tizen

向 tizen-manifest.xml 添加权限：

<privilege>http://tizen.org/privilege/notification</privilege>

语法

C#

在 C# 中使用 Badge API 的方式如下所示：

void SetCount(uint value)
{
    Badge.Default.SetCount(value);
}

方法

方法	说明
SetCount	设置锁屏提醒计数。

依赖项注册

如果要在 .NET MAUI 中使用内置依赖项注入层，则需要先在 MauiProgram 中注册 Badge 实现。 使用以下更改更新 MauiProgram.cs：

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiApp<App>()
            .UseMauiCommunityToolkit();

        builder.Services.AddSingleton<IBadge>(Badge.Default);
        return builder.Build();
    }
}

现在，可以按如下方式注入该服务：

public partial class MainPage : ContentPage
{
    private readonly IBadge badge;

    public MainPage(IBadge badge)
    {
        InitializeComponent();
        this.badge = badge;
    }

    public void SetCount(uint value)
    {
        badge.SetCount(value);
    }
}

示例

可以在 .NET MAUI 社区工具包示例应用程序中找到运行中的 Badge API 示例。

API

可以在 .NET MAUI 社区工具包 GitHub 存储库上找到 Badge API 的源代码。

Android

警告

由于 Android 设备制造商和启动器多种多样，因此请注意，应用锁屏提醒计数在不同设备上显示或不显示的方式可能会有不可预知的变化。

在 Android 环境中，几乎不存在通用的方法。 这一定律适用于设置应用程序锁屏提醒计数的工作，因为 Android 系统没有为此功能提供标准化 API。

不同的 Android 启动器选择以其独特的方式实现锁屏提醒计数。 大多数启动器，包括 Nova Launcher、Microsoft Launcher 等常用启动器，都有其处理此功能的特定方法。

因此，为了确保应用程序的锁屏提醒通知在这些不同的启动器中正确显示，必须为每个启动器编写特定的代码实现。 这意味着要根据每个启动器所独有的锁屏提醒计数指示机制的特定要求调整代码。

在实现通用应用程序体验的道路上，开发人员必须克服这一障碍。 这是因为 Android 的灵活生态系统鼓励多样性和自定义。

请务必注意，虽然可以覆盖一部分最受欢迎的 Android 启动器，但鉴于市场上提供的启动器数量之多，几乎不可能满足每一个启动器的要求。

借助社区工具包，我们提供了实现你自己的锁屏提醒计数器逻辑的方法，从而满足想要支持的提供商的要求。 可以通过以下方式完成这一工作：

1. 实现 CommunityToolkit.Maui.ApplicationModel.IBadgeProvider 接口。 请参阅 SamsungBadgeProvider 实现示例：SamsungBadgeProvider。
2. 在 Android MainApplication 构造函数中，将启动器标识符设置为你的 IBadgeProvider 实现。 例如，Samsung 启动器如下所示：

public MainApplication(IntPtr handle, JniHandleOwnership ownership)
    : base(handle, ownership)
{
    var samsungProvider = new SamsungBadgeProvider();

    BadgeFactory.SetBadgeProvider("com.sec.android.app.launcher", samsungProvider);
    BadgeFactory.SetBadgeProvider("com.sec.android.app.twlauncher", samsungProvider);
}

3. 向 AndroidManifest.xaml 添加所需的权限。 例如，Samsung 启动器如下所示：

<uses-permission android:name="com.sec.android.provider.badge.permission.READ" />
<uses-permission android:name="com.sec.android.provider.badge.permission.WRITE" />

这些更改足以让应用程序满足相应的要求，从而能够在基于 Android 的 Samsung 设备上运行并正确更新应用图标锁屏提醒数字。 它还提供了一个起点和指南，说明如何开始在应用程序中实现对其他启动器的支持。

因此，虽然我们的代码旨在提供理想的实现，但在某些情况下，Android 不会按预期方式运行。

强烈建议在各种设备和启动器上全面测试你的应用，以便最准确地评估应用锁屏提醒通知在你的特定用例中的行为方式。