Toast 进度栏和数据绑定

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

重要

需要 Creators Update 和 1.4.0 通知库：必须以 SDK 15063 为目标，并运行内部版本 15063 或更高版本才能在 Toast 上使用进度栏。 必须使用 UWP 社区工具包通知 NuGet 库的版本 1.4.0 或更高版本来构造 Toast 内容中的进度栏。

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

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

注意

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

下图显示了一个确定进度栏，其中标记了所有对应的属性。

properties	类型	必需	Description
标题	字符串或 BindableString	false	获取或设置可选的标题字符串。 支持数据绑定。
值	double 或 AdaptiveProgressBarValue 或 BindableProgressBarValue	false	获取或设置进度栏的值。 支持数据绑定。 默认值为 0。 可以是介于 0.0 和 1.0 之间的双精度， AdaptiveProgressBarValue.Indeterminate也可以 new BindableProgressBarValue("myProgressValue")是。
ValueStringOverride	字符串或 BindableString	false	获取或设置要显示的可选字符串，而不是默认的百分比字符串。 如果未提供此项，将显示类似于“70%”的内容。
Status	字符串或 BindableString	是	获取或设置状态字符串（必需），该字符串显示在左侧进度栏下方。 此字符串应反映操作的状态，例如“正在下载...”或“正在安装...”

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

生成器语法

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

XML

<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>

但是，需要动态更新进度栏的值，使其实际为“实时”。 这可以通过使用数据绑定更新 Toast 来完成。

使用数据绑定更新 toast

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

1. 构造利用数据绑定字段的 Toast 内容
2. 将标记（以及（可选）分配给 ToastNotification
3. 在 ToastNotification 上定义初始数据值
4. 发送 toast
5. 利用 标记 和 组 使用新值更新 数据 值

以下代码片段显示了步骤 1-4。 下一个代码片段将演示如何更新 Toast 数据 值。

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（如下载完成后）。

支持数据绑定的元素

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

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

更新或替换通知

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

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

一般情况下， 更新对于...

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

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

• 最终通知可能具有重大布局更改，例如删除进度栏、添加新按钮等
• 用户可能已关闭挂起的进度通知，因为他们不关心监视它下载，但仍希望在操作完成时收到弹出 Toast 通知

相关主题

• GitHub 上的完整代码示例
• toast 内容文档