徽章

Badge API 可讓開發人員在主畫面上設定應用程式圖示徽章號碼。

---

若要使用 Badge API，需要下列先決條件：

Android

支援 Android 裝置所需的其他設定。 請參閱 下方的Android一節 。

iOS/MacCatalyst

授權應用程式的徽章許可權。 系統會自動要求它。

Tizen

將權限新增至 tizen-manifest.xml：

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

語法

C#

Badge API 可在 C# 中使用，如下所示：

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

方法

方法	描述
SetCount	設定徽章計數。

相依性註冊

如果您想要在 .NET MAUI 中使用內建相依性插入層，則必須先在 內註冊 Badge 實 MauiProgram作。 使用下一個變更進行更新 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 Community Toolkit 範例應用程式中找到 API 作用中的範例Badge。

API

您可以在 .NET MAUI Community Toolkit GitHub 存放庫上找到 API 的原始程式碼Badge。

Android

警告

由於 Android 裝置製造商和啟動器的各種環境，請注意應用程式徽章計數如何顯示或未顯示在不同裝置上可能會有無法預測的變化。

在Android的世界裡，一個大小很少適合所有。 此原則適用於設定應用程式徽章計數，因為Android系統缺少此功能提供的標準化 API。

不同的 Android 啟動器選擇以獨特的方式實作徽章計數。 大多數發射機，包括 Nova Launcher、Microsoft Launcher 等熱門發射機，都有其處理此功能的特定方法。

因此，若要確保應用程式徽章通知在這些不同的啟動器中正確顯示，您必須針對每個啟動器使用程序設計特定的程式碼實作。 這表示將程式代碼調整為每個啟動器唯一徽章計數指示機制的特定需求。

將它視為開發人員必須克服的障礙，在實現通用應用程式體驗的道路上。 這是因為Android的彈性生態系統鼓勵多樣性和自定義。

請務必注意，雖然覆蓋最受歡迎的Android發射器是可行的，但鑒於市場上可用的發射機數量，幾乎不可能迎合每一個發射機。

透過 CommunityToolkit，我們提供您為想要支援的提供者實作自己的徽章計數器邏輯的方式。 這就是您可以執行此動作的方式：

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 不會如預期般運作。

強烈建議您在各種裝置和啟動器上徹底測試您的應用程式，以評估應用程式徽章通知在您的特定使用案例中的運作方式。