Toast 进度栏和数据绑定

  • 项目

使用 Toast 通知内的进度栏可向用户传送长时运行的操作的状态，如下载、视频呈现、练习目标等。

重要

需要创意者更新和通知库的 1.4.0：必须面向 SDK 15063 并运行内部版本 15063 或更高版本，才能在 Toast 上使用进度栏。 必须使用 1.4.0 或更高版本的 UWP 社区工具包通知 NuGet 库 来构造 Toast 内容中的进度栏。

Toast 内的进度栏可为“不确定的”（没有特定值，动态点指示有操作正在发生）或“确定的”（在栏中填充了特定百分比，如 60%）。

重要 API：NotificationData 类，ToastNotifier.Update 方法，ToastNotification 类

注意

仅桌面设备支持 Toast 通知中的进度栏。 其他设备会从通知中删除进度栏。

以下图片显示一个确定的进度栏，其所有相应的属性已标记。

标记为进度栏属性的 Toast
属性 类型 必需 说明
标题 字符串或 BindableString false 获取或设置可选标题字符串。 支持数据绑定。
值 Double 或 AdaptiveProgressBarValue 或 BindableProgressBarValue false 获取或设置进度栏的值。 支持数据绑定。 默认值为 0。 可以为 0.0 和 1.0 之间的双精度浮点数、AdaptiveProgressBarValue.Indeterminate 或 new BindableProgressBarValue("myProgressValue")。
ValueStringOverride 字符串或 BindableString false 获取或设置要显示的可选字符串，而不是默认百分比字符串。 如果未提供，会显示诸如“70%”的内容。
状态 字符串或 BindableString 是 获取或设置状态字符串（必需），它显示在左侧进度栏下方。 此字符串应反映操作的状态，如“正在下载...”或“正在安装...”

下面介绍如何生成上面看到的通知...

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

但是，需要动态更新进度栏的值，才能让进度栏真正处于“实时”状态。 实现此操作的方法是使用数据绑定来更新 Toast。

使用数据绑定更新 Toast

使用数据绑定包括以下步骤…

  1. 构造利用数据绑定字段的 Toast 内容
  2. 将 Tag（或 Group）分配到 ToastNotification
  3. 在 ToastNotification 上定义初始 Data 值
  4. 发送 Toast
  5. 利用 Tag 和 Group，使用新值来更新 Data 值

以下代码片段演示步骤 1-4。 下一个片段演示如何更新 Toast 的 Data 值。

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 负载。

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 通知保留在操作中心中的同一位置而不会向上或向下移动。 如果在进度条被填充时 Toast 每隔几秒钟就跳转到操作中心顶部，会让用户感到十分困惑！

Update 方法返回枚举 NotificationUpdateResult，用于告知是更新成功还是找不到通知（这意味着用户可能已消除通知，应停止向其发送更新）。 在进度操作完成之前（如在下载完成前），不建议弹出另一个 Toast。

支持数据绑定的元素

Toast 通知中的以下元素支持数据绑定

  • AdaptiveProgress 上的所有属性
  • 顶级 AdaptiveText 元素上的 Text 属性

更新或替换通知

从 Windows 10 开始，始终可以通过使用相同的 Tag 和 Group 发送新 Toast 来替换通知。 那么替换 Toast 和更新 Toast 的数据之间有何区别？

替换 更新
在操作中心中的位置 将通知移动到操作中心的顶部。 将通知就地保留在操作中心内。
修改内容 可彻底更改 Toast 的全部内容/布局 仅可更改支持数据绑定的属性（进度栏和顶级文本）
作为弹出窗口重新出现 如果保持 SuppressPopup 的设置为 false（或设置为 true 以自动将其发送到操作中心），则可以作为 Toast 弹出窗口重新出现 不会作为弹出窗口重新出现；在操作中心内自动更新 Toast 的数据
用户已消除 无论用户是否消除上一个通知，将始终发送用于替换的 Toast 如果用户已消除 Toast，将无法更新 Toast

一般情况下，更新可用于…

  • 在短时间内经常更改且不需要引起用户注意的信息
  • Toast 内容的细微更改，如将 50% 更改为 65%

通常情况下，更新序列完成（如文件已下载）之后，建议替换最后一步，因为…

  • 最终的通知很可能会有较大的布局更改，如删除进度栏、添加新按钮等
  • 用户可能会消除待处理的进度通知，因为用户不一定要监视下载进程，而是希望在操作完成时通过弹出 Toast 获取通知