トースト進行状況バーとデータ バインディング

トースト通知内の進行状況バーを使用すると、ダウンロード、ビデオ レンダリング、演習の目標など、実行時間の長い操作の状態をユーザーに伝えます。

トースト内の進行状況バーは、"不確定" (特定の値がなく、アニメーション化されたドットは操作が発生したことを示します) または "確定" (60%など、バーの特定の割合が塗りつぶされます) のいずれかです。

重要な API: NotificationData クラス、 ToastNotifier.Update メソッド、 ToastNotification クラス

以下の画像は、関連するすべてのプロパティにラベルが付けられた確定進行バーを示しています。

上記の通知を生成する方法を次に示します。...

new ToastContentBuilder()
    .AddText("Downloading your weekly playlist...")
    .AddVisualChild(new AdaptiveProgressBar()
    {
        Title = "Weekly playlist",
        Value = 0.6,
        ValueStringOverride = "15/26 songs",
        Status = "Downloading..."
    });

<toast>
    <visual>
        <binding template="ToastGeneric">
            <text>Downloading your weekly playlist...</text>
            <progress
                title="Weekly playlist"
                value="0.6"
                valueStringOverride="15/26 songs"
                status="Downloading..."/>
        </binding>
    </visual>
</toast>

ただし、進行状況バーの値を動的に更新して、実際に "ライブ" にする必要があります。 これを行うには、データ バインディングを使用してトーストを更新します。

データ バインディングを使用してトーストを更新する

データ バインディングの使用には、次の手順が含まれます。...

1. データ バインド フィールドを利用するトースト コンテンツを作成する
2. タグ（および必要に応じて グループ）を の ToastNotification に割り当てます
3. ToastNotification で初期データ値を定義する
4. トーストを送信する
5. タグとグループを使用して新しい値でデータ値を更新する

次のコード スニペットは、手順 1 から 4 を示しています。 次のスニペットでは、トースト のデータ値 を更新する方法を示します。

using Windows.UI.Notifications;
using Microsoft.Toolkit.Uwp.Notifications;
 
public void SendUpdatableToastWithProgress()
{
    // Define a tag (and optionally a group) to uniquely identify the notification, in order update the notification data later;
    string tag = "weekly-playlist";
    string group = "downloads";
 
    // Construct the toast content with data bound fields
    var content = new ToastContentBuilder()
        .AddText("Downloading your weekly playlist...")
        .AddVisualChild(new AdaptiveProgressBar()
        {
            Title = "Weekly playlist",
            Value = new BindableProgressBarValue("progressValue"),
            ValueStringOverride = new BindableString("progressValueString"),
            Status = new BindableString("progressStatus")
        })
        .GetToastContent();
 
    // Generate the toast notification
    var toast = new ToastNotification(content.GetXml());
 
    // Assign the tag and group
    toast.Tag = tag;
    toast.Group = group;
 
    // Assign initial NotificationData values
    // Values must be of type string
    toast.Data = new NotificationData();
    toast.Data.Values["progressValue"] = "0.6";
    toast.Data.Values["progressValueString"] = "15/26 songs";
    toast.Data.Values["progressStatus"] = "Downloading...";
 
    // Provide sequence number to prevent out-of-order updates, or assign 0 to indicate "always update"
    toast.Data.SequenceNumber = 1;
 
    // Show the toast notification to the user
    ToastNotificationManager.CreateToastNotifier().Show(toast);
}

次に、 データ 値を変更する場合は、 Update メソッドを使用して、トースト ペイロード全体を再作成せずに新しいデータを提供します。

using Windows.UI.Notifications;
 
public void UpdateProgress()
{
    // Construct a NotificationData object;
    string tag = "weekly-playlist";
    string group = "downloads";
 
    // Create NotificationData and make sure the sequence number is incremented
    // since last update, or assign 0 for updating regardless of order
    var data = new NotificationData
    {
        SequenceNumber = 2
    };

    // Assign new values
    // Note that you only need to assign values that changed. In this example
    // we don't assign progressStatus since we don't need to change it
    data.Values["progressValue"] = "0.7";
    data.Values["progressValueString"] = "18/26 songs";

    // Update the existing notification's data by using tag/group
    ToastNotificationManager.CreateToastNotifier().Update(data, tag, group);
}

トースト全体を置き換える代わりに Update メソッドを使用すると、トースト通知がアクション センターの同じ位置に留まらず、上下に移動することもできなくなります。 進行状況バーがいっぱいになる間に、トーストが数秒ごとにアクション センターの上部にジャンプし続けた場合、ユーザーは非常に混乱します。

Update メソッドは列挙型 NotificationUpdateResult を返します。これにより、更新が成功したかどうか、または通知が見つからなかったかどうかを確認できます (これは、ユーザーが通知を無視した可能性が高く、通知への更新の送信を停止する必要があることを意味します)。 進行状況の操作が完了するまで (ダウンロードが完了したときなど)、別のトーストをポップすることはお勧めしません。

データ バインディングをサポートする要素

トースト通知の次の要素は、データ バインディングをサポートしています

• AdaptiveProgress のすべてのプロパティ
• 最上位の AdaptiveText 要素の Text プロパティ

通知を更新または置換する

Windows 10 以降では、同じ タグ と グループで新しいトーストを送信することで、通知 を常に 置き換えることができます。 トーストを置き換えることと、トーストのデータを更新することの違いは何ですか?

一般に、更新は役立ちます…

• 短時間で頻繁に変更され、ユーザーの注意を引く必要がない情報
• トースト コンテンツの微妙な変更 (50% から 65% への変更など)

多くの場合、一連の更新が完了した後 (ファイルがダウンロードされた場合など)、最後の手順に置き換えることをお勧めします。...

• 最終的な通知には、進行状況バーの削除、新しいボタンの追加など、レイアウトが大幅に変更される可能性があります。
• ユーザーはダウンロードの進行状況に興味がないため、保留中の進行状況通知を無視した可能性があります。しかし、操作が完了したときには、ポップアップトーストで通知を受け取りたいと思っています。

関連トピック

• GitHubで完全なコードサンプルを参照してください
• トーストコンテンツ ドキュメンテーション