Toast 进度栏和数据绑定Toast progress bar and data binding

使用 Toast 通知内的进度栏可向用户传送长时运行的操作的状态,如下载、视频呈现、练习目标等。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.

重要

需要创意者更新和 1.4.0 的通知库:目标必须为 SDK 15063 并且运行版本 15063 或更高版本以使用 Toast 上的进度栏。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. 必须使用版本 1.4.0 或更高版本的 UWP 社区工具包通知 NuGet 库来构造 Toast 内容中的进度栏。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.

Toast 内的进度栏可以为 "不确定" (没有特定值,动态点指示发生了某个操作) 或者 "确定性" (填充了特定的条形百分比,如 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%).

重要 APINotificationData 类ToastNotifier.Update 方法ToastNotification 类Important APIs: NotificationData class, ToastNotifier.Update method, ToastNotification class

备注

仅桌面设备支持 Toast 通知中的进度栏。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
propertiesProperty 类型Type 必需Required 说明Description
标题Title 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 之间的双精度浮点数、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.
StatusStatus 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...

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

但是,需要动态更新进度栏的值,才能让进度栏真正处于“实时”状态。However, you'll need to dynamically update the values of the progress bar for it to actually be "live". 实现此操作的方法是使用数据绑定来更新 Toast。This can be done by using data binding to update the toast.

使用数据绑定更新 ToastUsing data binding to update a toast

使用数据绑定包括以下步骤…Using data binding involves the following steps...

  1. 构造利用数据绑定字段的 Toast 内容Construct toast content that utilizes data bound fields
  2. Tag(或 Group)分配到 ToastNotificationAssign a Tag (and optionally a Group) to your ToastNotification
  3. ToastNotification 上定义初始 DataDefine your initial Data values on your ToastNotification
  4. 发送 ToastSend the toast
  5. 利用 TagGroup,使用新值来更新 DataUtilize Tag and Group to update the Data values with new values

以下代码片段演示步骤 1-4。The following code snippet shows steps 1-4. 下一个片段演示如何更新 Toast 的 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 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);
}

然后,在想要更改 Data 值时,可使用 Update 方法提供新数据,而无需重新构造整个 Toast 负载。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 方法而不是替换整个 Toast,还可确保 Toast 通知保留在操作中心中的同一位置而不会向上或向下移动。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. 如果在进度条被填充时 Toast 每隔几秒钟就跳转到操作中心顶部,会让用户感到十分困惑!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). 在进度操作完成之前(如在下载完成前),不建议弹出另一个 Toast。We do not recommend popping another toast until your progress operation has been completed (like when the download completes).

支持数据绑定的元素Elements that support data binding

Toast 通知中的以下元素支持数据绑定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 发送新 Toast 来替换通知。Since Windows 10, you could always replace a notification by sending a new toast with the same Tag and Group. 那么替换 Toast 和更新 Toast 的数据之间有何区别?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 可彻底更改 Toast 的全部内容/布局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 如果保持 SuppressPopup 的设置为 false(或设置为 true 以自动将其发送到操作中心),则可以作为 Toast 弹出窗口重新出现Can reappear as a toast popup if you leave SuppressPopup set to false (or set to true to silently send it to Action Center) 不会作为弹出窗口重新出现;在操作中心内自动更新 Toast 的数据Won't reappear as a popup; the toast's data is silently updated within Action Center
用户已消除User dismissed 无论用户是否消除上一个通知,将始终发送用于替换的 ToastRegardless of whether user dismissed your previous notification, your replacement toast will always be sent 如果用户已消除 Toast,将无法更新 ToastIf 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
  • Toast 内容的细微更改,如将 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
  • 用户可能会消除待处理的进度通知,因为用户不一定要监视下载进程,而是希望在操作完成时通过弹出 Toast 获取通知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