Toast 进度栏和数据绑定

项目
07/05/2024

使用 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	是	获取或设置状态字符串（必需），该字符串显示在左侧进度栏下方。此字符串应反映操作的状态，例如“正在下载...”或“正在安装...”

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

生成器语法
XML

new ToastContentBuilder()
    .AddText("Downloading your weekly playlist...")
    .AddVisualChild(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>

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

使用数据绑定更新 toast

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

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

以下代码片段显示了步骤 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 通知

通过

Toast 进度栏和数据绑定

使用数据绑定更新 toast

支持数据绑定的元素

更新或替换通知

相关主题

其他资源