通过

Toast 消息进度条和数据绑定

使用 Toast 通知中的进度栏，可以将长时间运行的作的状态传达给用户，例如下载、视频呈现、练习目标等。

重要

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

Toast 内的进度条可以是“不确定”（没有特定值，动画点表示操作正在进行）或“确定”（填充一定百分比的进度条，例如 60%%）。

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

注释

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

下图显示了一个确定的进度条，标注了它的所有相应属性。

Toast，其中标有进度栏属性
资产 类型 必选 DESCRIPTION
标题 字符串 或 BindableString 假 获取或设置可选的标题字符串。 支持数据绑定。
价值 double 或 AdaptiveProgressBarValue 或 BindableProgressBarValue 假 获取或设置进度栏的值。 支持数据绑定。 默认值为 0。 可以是介于 0.0 和 1.0、AdaptiveProgressBarValue.Indeterminate或 new BindableProgressBarValue("myProgressValue")之间的双精度值。
值字符串覆盖 字符串 或 BindableString 假 获取或设置要显示的可选字符串，而不是默认百分比字符串。 如果未提供此项，将显示“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 来完成。

使用数据绑定更新提示消息

使用数据绑定涉及以下步骤...

  1. 构造利用数据绑定字段的 Toast 内容
  2. 将 标记（以及可选的 组）分配给 ToastNotification
  3. 在您的 ToastNotification 上定义初始 Data 值
  4. 敬酒
  5. 利用 标签 和 组，将 数据 值更新为新值

以下代码片段显示了步骤 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);
}

然后，如果要更改 数据 值，请使用 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 通知中的以下元素支持数据绑定

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

更新或替换通知

由于 Windows 10，始终可以通过发送具有相同 标记 和 组的新 toast 来 替换 通知。 那么，替换 toast 对象 和 更新 toast 对象的数据 有何区别？

替换 更新
在操作中心中的位置 将通知移动到操作中心顶部。 将通知保留在操作中心内。
修改内容 可以完全更改 Toast 的所有内容/布局 只能更改支持数据绑定的属性（进度栏和顶级文本）
以弹出窗口形式重新出现 如果将 SuppressPopup 设置为 false（或者设置为 true 以静默将其发送到操作中心），则可以再次显示为一个弹出窗口。 不会作为弹出窗口重新出现;Toast 的数据在操作中心内以无提示方式更新
用户已忽略 无论用户是否关闭了您以前的通知，新的替换通知（Toast）将始终被发送。 如果用户关闭了 Toast，Toast 更新将失败

在一般情况下，更新有助于...

  • 信息在短时间内频繁更改，不需要引起用户的注意
  • 对 toast 内容进行细微的更改，例如将 50% 改为 65%

通常，在更新步骤完成后（例如已下载文件之后），我们建议在最后一步进行替换，因为...

  • 最终通知可能具有重大布局更改，例如删除进度栏、添加新按钮等
  • 用户可能已关闭待处理的进度通知，因为他们不想关注下载过程，但仍希望在操作完成时收到弹出通知。