benxu.AppPlatform.Notification 2.0.0

benxu.AppPlatform.Notification

通知歷史管理服務 - 自動儲存與管理推播通知歷史記錄，提供已讀/未讀標記、分類、導航等功能。

特色

• 自動儲存通知：自動訂閱 FCM 事件並儲存所有推播通知
• 已讀/未讀管理：支援標記通知已讀狀態與查詢未讀數量
• 持久化儲存：使用 LiteDB 本地儲存，資料持久化保存
• 導航整合：自動解析 Deep Link 並轉換為 Blazor 路由
• 分類支援：支援通知分類（todo、system、reminder 等）
• 事件通知：提供 HistoryChanged 事件，方便 UI 自動刷新

支援平台

• ✅ Android (完整支援)
• ✅ iOS (完整支援)

安裝

1. 安裝套件：

   dotnet add package benxu.AppPlatform.Notification
   

2. 確認已安裝相依套件：

   • benxu.AppPlatform.Core
   • benxu.AppPlatform.Storage.LiteDB
   • benxu.AppPlatform.Firebase.Fcm

使用方式

1. 註冊服務

在 MauiProgram.cs 中註冊服務：

using benxu.AppPlatform.Notification.Extensions;

builder.Services.AddNotificationHistory();

注意：必須在註冊 FCM 服務之後註冊，因為通知歷史服務需要訂閱 FCM 事件。

完整範例：

builder.UseAppPlatform(options =>
{
    options.UseFirebaseFirestore(firestore => { /* ... */ });
    options.UseLocalStorage(storage => { /* ... */ });
    options.UseFcm(fcm => { /* ... */ });
});

// 在 AppPlatform 初始化後註冊
builder.Services.AddNotificationHistory();

2. 在 Blazor 頁面使用

@inject INotificationHistoryService NotificationHistory
@implements IDisposable

<h3>通知中心</h3>

@if (notifications != null)
{
    foreach (var notification in notifications)
    {
        <div class="notification-item @(notification.IsRead ? "read" : "unread")">
            <h4>@notification.Title</h4>
            <p>@notification.Body</p>
            <small>@notification.ReceivedAt.ToLocalTime()</small>

            @if (!notification.IsRead)
            {
                <button @onclick="() => MarkAsRead(notification.Id)">
                    標記為已讀
                </button>
            }

            @if (!string.IsNullOrEmpty(notification.NavigationUrl))
            {
                <button @onclick="() => NavigateTo(notification.NavigationUrl)">
                    查看詳情
                </button>
            }
        </div>
    }
}

<div class="actions">
    <button @onclick="ClearAll">清除所有通知</button>
    <p>未讀數量：@unreadCount</p>
</div>

@code {
    private IEnumerable<NotificationHistory>? notifications;
    private int unreadCount;

    protected override async Task OnInitializedAsync()
    {
        // 訂閱歷史變更事件
        NotificationHistory.HistoryChanged += OnHistoryChanged;

        await LoadNotifications();
    }

    private async Task LoadNotifications()
    {
        var result = await NotificationHistory.GetAllNotificationsAsync();
        if (result.IsSuccess)
        {
            notifications = result.Data;
        }

        var countResult = await NotificationHistory.GetUnreadCountAsync();
        if (countResult.IsSuccess)
        {
            unreadCount = countResult.Data;
        }
    }

    private async Task MarkAsRead(string notificationId)
    {
        await NotificationHistory.MarkAsReadAsync(notificationId);
    }

    private async Task ClearAll()
    {
        await NotificationHistory.ClearAllNotificationsAsync();
    }

    private void OnHistoryChanged(object? sender, EventArgs e)
    {
        // 重新載入通知
        InvokeAsync(LoadNotifications);
        StateHasChanged();
    }

    public void Dispose()
    {
        NotificationHistory.HistoryChanged -= OnHistoryChanged;
    }
}

3. 在 C# 程式碼使用

// 注入服務
private readonly INotificationHistoryService _notificationHistory;

// 取得所有通知
var result = await _notificationHistory.GetAllNotificationsAsync();
if (result.IsSuccess)
{
    var notifications = result.Data;
    foreach (var notification in notifications)
    {
        Console.WriteLine($"{notification.Title}: {notification.Body}");
    }
}

// 取得未讀數量
var countResult = await _notificationHistory.GetUnreadCountAsync();
if (countResult.IsSuccess)
{
    Console.WriteLine($"未讀通知：{countResult.Data} 則");
}

// 標記為已讀
await _notificationHistory.MarkAsReadAsync(notificationId);

// 刪除通知
await _notificationHistory.DeleteNotificationAsync(notificationId);

// 清除所有通知
await _notificationHistory.ClearAllNotificationsAsync();

API 參考

INotificationHistoryService

方法

事件

NotificationHistory 模型

自動化功能

FCM 事件自動訂閱

服務會自動訂閱以下 FCM 事件：

1. NotificationReceived（前景接收）

   • 自動儲存通知
   • 標記為未讀

2. NotificationTapped（背景/終止狀態點擊）

   • 自動儲存通知
   • 標記為已讀

Deep Link 自動轉換

支援自動將 FCM Deep Link 轉換為 Blazor 路由：

• 輸入：todoapp://todos/detail?id=123
• 輸出：/todos/detail?id=123

可透過 NavigationUrl 屬性取得轉換後的路由進行導航。

注意事項

• 服務註冊順序：必須在 FCM 服務註冊之後註冊此服務
• 事件訂閱：記得在元件 Dispose 時取消訂閱 HistoryChanged 事件
• 非同步儲存：FCM 事件處理時使用非同步儲存，不會阻塞主執行緒
• UTC 時間：所有時間戳記使用 UTC，顯示時需轉換為本地時間

依賴項目

• benxu.AppPlatform.Core
• benxu.AppPlatform.Storage.LiteDB
• benxu.AppPlatform.Firebase.Fcm

授權

MIT License - Copyright (c) 2025 benxu