トーストの進行状況バーとデータ バインディングToast progress bar and data binding

トースト通知内に進行状況バーを使用すると、ダウンロード、ビデオ レンダリング、一連の作業など、長い時間を要する処理の進行状況を表示できます。Using a progress bar inside your toast notification allows you to convey the status of long-running operations to the user, like downloads, video rendering, exercise goals, and more.

重要

Creators Update と通知ライブラリの 1.4.0 必要:SDK 15063 を対象にして、15063 以上トーストで進行状況バーを使用するビルドを実行します。Requires Creators Update and 1.4.0 of Notifications library: You must target SDK 15063 and be running build 15063 or higher to use progress bars on toasts. トーストのコンテンツ内に進行状況バーを作成するには、UWP コミュニティ ツールキットの Notifications NuGet ライブラリ、バージョン 1.4.0 以上を使用する必要があります。You must use version 1.4.0 or higher of the UWP Community Toolkit Notifications NuGet library to construct the progress bar in your toast's content.

トースト内での進行状況バーできません「不確定」(特定の値はありません、アニメーション化された点を示します、操作が実行されている) または「不確定」(バーの指定したパーセントが入力されます、60% など)。A progress bar inside a toast can either be "indeterminate" (no specific value, animated dots indicate an operation is occurring) or "determinate" (a specific percent of the bar is filled, like 60%).

重要な API:NotificationData クラスToastNotifier.Update メソッドToastNotification クラスImportant APIs: NotificationData class, ToastNotifier.Update method, ToastNotification class

注意

トースト通知での進行状況バーは、デスクトップでのみサポートされています。Only Desktop supports progress bars in toast notifications. 他のデバイスでは、進行状況バーが通知から削除されます。On other devices, the progress bar will be dropped from your notification.

下の図では、確定型の進行状況バーと、それに対応するすべてのプロパティのラベルを示します。The picture below shows a determinate progress bar with all of its corresponding properties labeled.

Toast with progress bar properties labeled
プロパティProperty 種類Type 必須Required 説明Description
TitleTitle string または BindableStringstring or BindableString falsefalse タイトルの文字列 (オプション) を取得または設定します。Gets or sets an optional title string. データ バインディングをサポートしています。Supports data binding.
Value double または AdaptiveProgressBarValueBindableProgressBarValuedouble or AdaptiveProgressBarValue or BindableProgressBarValue falsefalse 進行状況バーの値を取得または設定します。Gets or sets the value of the progress bar. データ バインディングをサポートしています。Supports data binding. 既定値は 0 です。Defaults to 0. 0.0 ~ 1.0 の double 型または AdaptiveProgressBarValue.Indeterminatenew BindableProgressBarValue("myProgressValue") です。Can either be a double between 0.0 and 1.0, AdaptiveProgressBarValue.Indeterminate, or new BindableProgressBarValue("myProgressValue").
ValueStringOverrideValueStringOverride string または BindableStringstring or BindableString falsefalse 割合を示す既定の文字列に代わって表示される文字列 (オプション) を取得または設定します。Gets or sets an optional string to be displayed instead of the default percentage string. これを指定しない場合は、"70%" などの文字が表示されます。If this isn't provided, something like "70%" will be displayed.
ステータスStatus string または BindableStringstring or BindableString truetrue 進行状況バーの下の左側に表示されるステータス文字列 (必須) を取得または設定します。Gets or sets a status string (required), which is displayed underneath the progress bar on the left. この文字列は、"ダウンロード中..." や "インストール中..." などのように、操作の状態を反映する必要があります。This string should reflect the status of the operation, like "Downloading..." or "Installing..."

以下では、上に示した通知を生成する方法を示します。Here's how you would generate the notification seen above...

ToastContent content = new ToastContent()
{
    Visual = new ToastVisual()
    {
        BindingGeneric = new ToastBindingGeneric()
        {
            Children =
            {
                new AdaptiveText()
                {
                    Text = "Downloading your weekly playlist..."
                },
 
                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>

ただし、進行状況バーが実際にリアルタイムに機能するには、バーの値を動的に更新する必要があります。However, you'll need to dynamically update the values of the progress bar for it to actually be "live". これは、データ バインディングを使用してトーストを更新することで実現します。This can be done by using data binding to update the toast.

データ バインディングを使用したトーストの更新Using data binding to update a toast

データ バインディングの使用は、以下の手順で行われます。Using data binding involves the following steps...

  1. データ バインドしたフィールドを使用してトースト コンテンツを作成するConstruct toast content that utilizes data bound fields
  2. アプリの ToastNotificationTag (およびオプションで Group) を割り当てるAssign a Tag (and optionally a Group) to your ToastNotification
  3. アプリの ToastNotificationData の初期値を定義するDefine your initial Data values on your ToastNotification
  4. トースト通知を送信するSend the toast
  5. TagGroup を利用して、Data の値を新しい値に更新するUtilize Tag and Group to update the Data values with new values

以下のコード スニペットでは、これらの手順 1 ~ 4 を示します。The following code snippet shows steps 1-4. 次のスニペットは、トーストの Data の値を更新する方法を示しています。The next snippet will show how to update the toast Data values.

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 ToastContent()
    {
        Visual = new ToastVisual()
        {
            BindingGeneric = new ToastBindingGeneric()
            {
                Children =
                {
                    new AdaptiveText()
                    {
                        Text = "Downloading your weekly playlist..."
                    },
    
                    new AdaptiveProgressBar()
                    {
                        Title = "Weekly playlist",
                        Value = new BindableProgressBarValue("progressValue"),
                        ValueStringOverride = new BindableString("progressValueString"),
                        Status = new BindableString("progressStatus")
                    }
                }
            }
        }
    };
 
    // 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);
}

次に、Data の値を変更するときは、Update メソッドを使用して、トーストのペイロード全体を再作成することなく、新しいデータを提供します。Then, when you want to change your Data values, use the Update method to provide the new data without re-constructing the entire toast payload.

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 メソッドを使用することで、トースト通知がアクション センターの同じ位置に固定され、上下に移動することがなくなります。Using the Update method rather than replacing the entire toast also ensures that the toast notification stays in the same position in Action Center and doesn't move up or down. 進行状況バーが進む間、アクション センターで数秒ごとにトーストが最上位に移動すると、ユーザーに大きな混乱をもたらします。It would be quite confusing to the user if the toast kept jumping to the top of Action Center every few seconds while the progress bar filled!

Update メソッドは、列挙値 NotificationUpdateResult を返します。この列挙値により、更新が正常に完了したかどうかを確認でき、また通知が見つからなかった場合 (おそらく、ユーザーが通知を無視したためであり、その通知に対しては更新の送信を停止する必要があります) を確認できます。The Update method returns an enum, NotificationUpdateResult, which lets you know whether the update succeeded or whether the notification couldn't be found (which means the user has likely dismissed your notification and you should stop sending updates to it). 進行状況バーの操作が完了するまで (ダウンロードが完了するなど)、別のトーストを表示しないことをお勧めします。We do not recommend popping another toast until your progress operation has been completed (like when the download completes).

データ バインディングをサポートする要素Elements that support data binding

トースト通知の中で、データ バインディングをサポートする要素は次のとおりです。The following elements in toast notifications support data binding

  • AdaptiveProgress のすべてのプロパティAll properties on AdaptiveProgress
  • 最上位レベルの AdaptiveText 要素の Text プロパティThe Text property on the top-level AdaptiveText elements

通知の更新と置換Update or replace a notification

Windows 10 以降では、同じ TagGroup を使って新しいトーストを送信することで、いつでも通知を置き換えることができます。Since Windows 10, you could always replace a notification by sending a new toast with the same Tag and Group. 以下では、トーストの置換とトーストのデータの更新の違いを示します。So what's the difference between replacing the toast and updating the toast's data?

置換Replacing 更新Updating
アクション センター内の位置Position in Action Center 通知がアクション センターの一番上に移動します。Moves the notification to the top of Action Center. アクション センター内の同じ位置に通知が固定されます。Leaves the notification in place within Action Center.
コンテンツの変更Modifying content トーストのすべてのコンテンツやレイアウトを完全に変更できます。Can completely change all content/layout of the toast データ バインディングをサポートするプロパティ (進行状況バーと最上位のテキスト) のみ変更できます。Can only change properties that support data binding (progress bar and top-level text)
ポップアップの遅れReappearing as popup SuppressPopupfalse に設定したままの場合は、トースト ポップアップとして再表示できます (true に設定するとサイレント モードでアクション センターに送信されます)。Can reappear as a toast popup if you leave SuppressPopup set to false (or set to true to silently send it to Action Center) ポップアップとしては再表示されません。アクション センター内でトーストのデータがサイレント モードで更新されます。Won't reappear as a popup; the toast's data is silently updated within Action Center
閉じたユーザーUser dismissed ユーザーがそれまでの通知を無視しても、置換トーストは常に送信されます。Regardless of whether user dismissed your previous notification, your replacement toast will always be sent ユーザーがトーストを無視すると、トーストの更新は失敗します。If the user dismissed your toast, the toast update will fail

一般に、更新が便利なのは以下の場合です。In general, updating is useful for...

  • 短時間で頻繁に変更され、ユーザーに最優先で注目される必要がない情報Information that frequently changes in a short period of time and doesn't require being brought to the front of the user's attention
  • トーストのコンテンツに大きな変更がない場合 (50% ~ 65% 程度の変更率)Subtle changes to your toast content, like changing 50% to 65%

多くの場合、更新のシーケンスが完了した後 (ファイルのダウンロード後など) の最終手順では、置換の使用をお勧めします。理由は以下のとおりです。Often times, after your sequence of updates have completed (like the file has been downloaded), we recommend replacing for the final step, because...

  • 最後の通知は大幅なレイアウト変更を伴う場合が多い (進行状況バーの削除や、新しいボタンの追加など)Your final notification likely has drastic layout changes, like removal of the progress bar, addition of new buttons, etc
  • ユーザーにとってダウンロードの進行状況は重要でなく、保留中の進行状況通知を無視することがあるが、操作完了時にはポップアップ トーストによる通知を望んでいるためThe user might have dismissed your pending progress notification since they don't care about watching it download, but still want to be notified with a popup toast when the operation is completed