New Windows 10 SDK - Toast Notification

张明云的知识共享 2018-03-21

概述

Toast Notification 在 UWP App 中有很重要的作用,能够很大程度上增强 App 和用户之间的沟通,比如运营推广活动、版本更新、提醒类任务提示等等。Toast Notification 可以通过图片、文字、按钮等创建可适配、可交互的通知。

我们在About Windows 10 SDK Preview Build 17110中对 Toast Notification 做了简单的介绍,本篇会从开发角度更更深入的解读。Toast Notification 主要分为网络内容通知和本地内容通知,本篇我们主要关注 Toast Notification 的以下新增功能的内容开发和显示,对于触发通知的源暂不细讲:

  • 图片尺寸限制
  • 进度条
  • 新增的输入选项

开发过程

NuGet 安装

为了在 UWP 中实现 Toast Notification,我们需要引入一个 SDK:Microsoft.Toolkit.Uwp.Notifications,通过 NuGet 在 Visual Studio 的Package Management 中安装:

Install-Package Microsoft.Toolkit.Uwp.Notifications -Version 2.2.0

基础实现

我们来实现一个样式比较基础的 Toast Notification,Toast 的内容主要包括以下几个部分:

  • Launch — 定义一个参数,当用户点击 Toast 时传回到应用中,允许开发者深度链接到 Toast 显示的正确内容对应的应用页面内容中;
  • Visual — Toast 的静态内容展示部分,包括文本和图像等;
  • Actions — Toast 的可交互部分,包括可点击的按钮,文本输入等;
  • Audio — 当 Toast 显示时,播放的音乐。

这里我们定义了 ToastContent 需要的基本内容:

string title = "Shaomeng sent you a picture";
string content = "Check this out!";
string image = "ms-appx:///assets/test.jpg";
string logo = "ms-appx:///assets/shaomeng.jpg";

// Construct the visuals of the toast
ToastVisual visual = new ToastVisual()
{
    BindingGeneric = new ToastBindingGeneric()
    {
        Children =
        {
            new AdaptiveText()
            {
                Text = title
            },

            new AdaptiveText()
            {
                Text = content
            },

            new AdaptiveImage()
            {
                Source = image
            }
        },

        AppLogoOverride = new ToastGenericAppLogo()
        {
            Source = logo,
            HintCrop = ToastGenericAppLogoCrop.Circle
        }
    }
};

// In a real app, these would be initialized with actual data
int conversationId = ;

// Construct the actions for the toast (inputs and buttons)
ToastActionsCustom actions = new ToastActionsCustom()
{
    Buttons =
    {
        new ToastButton("Like", new QueryString()
        {
            { "action", "like" },
            { "conversationId", conversationId.ToString() }

        }.ToString())
        {
            ActivationType = ToastActivationType.Background
        },

        new ToastButton("View", new QueryString()
        {
            { "action", "viewImage" },
            { "imageUrl", image }

        }.ToString())
    }
};

ToastAudio audio = new ToastAudio()
{
    Src = new Uri("ms-appx:///assets/test.mp3", UriKind.RelativeOrAbsolute)
};
define content for Toast Content

使用上面的内容,定义一个 ToastContent,并把它显示出来:

ToastContent toastContent = new ToastContent()
{
    Launch = "test string",
    Visual = visual,
    Actions = actions,
    Audio = audio,
};

var toast = new ToastNotification(toastContent.GetXml());
ToastNotificationManager.CreateToastNotifier().Show(toast);

图片尺寸限制

Toast Notification 中允许使用的图片来源包括:http://,ms-appx:///,ms-appdata:///

对于网络图片,图片尺寸限制的单位是单个图片尺寸。16299 以后,normal connections 的限制是 3MB,metered connections 的限制是 1MB;而之前的限制统一是 200 KB。可以看到对网络图片的尺寸限制放宽了很多,很多高清晰度的图片也可以被使用。

如果你的图片超过了这个尺寸限制,或者下载过程中失败,超时,通知会正常被显示,不过图片部分会被放弃。

我们来做一下实际的验证,上面示例中我们使用了一张 buildcast 低分辨率 jpg 截图,只有 50KB 左右,如果把上面示例中的图片替换成 >3MB 的网络原始图片:

string image = "http://192.168.1.110/buildcast.png";

buildcast.png 的尺寸是 5.63MB,看看显示结果,确实放弃了图片,只显示了其他部分:

New Windows 10 SDK - Toast Notification

而如果使用同一张图片,但是把放到工程里呢:

string image = "ms-appx:///assets/buildcast.png";

结果就是,图片可以正常显示了。这也印证了上面的结论,图片尺寸限制只针对网络图片:

New Windows 10 SDK - Toast Notification

进度条

在某些场景,例如下载或其他过程进行时,需要在通知中显示进度条,让用户可以保持对进度的关注。进度条可以是不确定的或者确定的。

Toast Content 中,使用AdaptiveProgressBar 类来实现进度条的显示和更新,如下图,它主要就以下几个属性:

  • Title — 设置和显示进度条的标题,支持 DataBinding;
  • Value — 设置和显示进度条当前进度,支持 DataBinding;默认值为 0.0,取值范围是 0.0 ~1.0;AdaptiveProgressBarValue.Indeterminate 代表不确定值,显示效果就是不断移动的三个点,表示某个不确定过程正在进行;new BindableProgressBarValue("myProgressValue") 为数值绑定的写法;
  • ValueStringOverride — 设置和显示重写当前进度数值,支持 DataBinding;书写方式为 new BindableString("progressValueString"),
  • Status — 设置和显示当前进度条状态,支持 DataBinding;如下图中的 Status 可能会有:downloading...,finished! 等;
New Windows 10 SDK - Toast Notification

接下来看一下代码示例:

  1. 我们给 ToastContent 设置了 Tag(或 Group),作为更新显示时的标识;
  2. AdaptiveProgressBar 中使用了 DataBinding 的方式来赋值,并在 Toast 第一次显示时,手动给它设置了初始值;
  3. 设置了 Toast 的 SequenceNumber,它是一个 uint 类型,在更新时,只有值大于前一次的值才会更新;所以如果你想每次都更新,初始值可以设置为 0;
// Define a tag (and optionally a group) to uniquely identify the notification, in order update the notification data later;
string tag = "demo-filelist";
string group = "downloads";

// Construct the toast content with data bound fields
ToastContent content = new ToastContent()
{
    Visual = new ToastVisual()
    {
        BindingGeneric = new ToastBindingGeneric()
        {
            Children =
            {
                new AdaptiveText()
                {
                    Text = "Downloading your demo files..."
                },

                new AdaptiveProgressBar()
                {
                    Title = "Demo Files",
                    Value = new BindableProgressBarValue("progressValue"),
                    ValueStringOverride = new BindableString("progressValueString"),
                    Status = new BindableString("progressStatus")
                }
            }
        }
    }
};

var toast = new ToastNotification(content.GetXml());
// Assign the tag and group
toast.Tag = tag;
toast.Group = group;

//Assign initial NotificationData values
toast.Data = new NotificationData();
toast.Data.Values["progressValue"] = "0.0";
toast.Data.Values["progressValueString"] = "0/10 files";
toast.Data.Values["progressStatus"] = "Downloading...";

// Provide sequence number to prevent out-of-order updates, or assign 0 to indicate "always update"
toast.Data.SequenceNumber = ;

ToastNotificationManager.CreateToastNotifier().Show(toast);

下面是进度条更新的代码:

  1. 注意 Tag 和 Group 需要和创建 Toast 时保持一致,不然更新不会生效;
  2. SequenceNumber 设置的值需要比上一次的大,不然更新也不会生效;
  3. 我们进行了两次更新,一次是进行中,一次是已经完成;
// Construct a NotificationData object;
string tag = "demo-filelist";
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 = seq_no
};

// Assign new values
if (seq_no == )
{
    data.Values["progressValue"] = "0.7";
    data.Values["progressValueString"] = "7/10 files";
}
else if (seq_no == )
{
    data.Values["progressValue"] = "1.0";
    data.Values["progressValueString"] = "10/10 files";
    data.Values["progressStatus"] = "Finished!";
}

// Update the existing notification's data by using tag/group
ToastNotificationManager.CreateToastNotifier().Update(data, tag, group);

来看看三个状态,初始值,更新1-进行中,更新2-已完成:

New Windows 10 SDK - Toast NotificationNew Windows 10 SDK - Toast NotificationNew Windows 10 SDK - Toast Notification

新增的输入选项

输入区域会出现在 Toast 中的 Actions 区域,也就是说只有 Toast 被展开的时候,输入区域才会显示出来。下面来看看几种常见的输入形式:

1. 快速回复输入

看一下输入部分的代码,添加了一个 ToastTextBox 来输入文字,添加了一个 ToastButton 来处理输入的文字,为了让按钮出现在文本框后面,ToastButton 的 TextBoxId 属性设置为 ToastTextBox 的 Id。而点击按钮后的操作,属于后台操作,不需要启动应用,也不需要关联协议启动其他应用。

// Construct the actions for the toast (inputs and buttons)
ToastActionsCustom actions = new ToastActionsCustom()
{
    Inputs =
    {
        new ToastTextBox("tbReply")
        {
            PlaceholderContent = "Type a reply"
        }
    },
    Buttons =
    {
        new ToastButton("Reply", "action=reply&convId=9318")
        {
            ActivationType = ToastActivationType.Background,

            // To place the button next to the text box,
            // reference the text box's Id and provide an image
            TextBoxId = "tbReply",
            ImageUri = "Assets/if_paperfly_701491.png"
        }
    }
};

运行效果如下图,折叠时文本框区域不显示,而输入文字点击按钮后,Toast 消失。

New Windows 10 SDK - Toast NotificationNew Windows 10 SDK - Toast Notification

2. 带按钮栏输入

带按钮栏的输入相对更通用一些,输入框后面显示操作的若干按钮,点击每个按钮会有对应的操作

// Construct the actions for the toast (inputs and buttons)
ToastActionsCustom actions = new ToastActionsCustom()
{
    Inputs =
    {
        new ToastTextBox("tbReply")
        {
            PlaceholderContent = "Type a reply"
        }
    },

    Buttons =
    {
        new ToastButton("Reply", "action=reply&threadId=9218")
        {
            ActivationType = ToastActivationType.Background
        },

        new ToastButton("Video call", "action=videocall&threadId=9218")
        {
            ActivationType = ToastActivationType.Foreground
        }
    }
};
New Windows 10 SDK - Toast Notification

3. 选择式输入

提供一个输入选项给用户,选择某个选项后,点击按钮会有对应的操作

Inputs =
{
    new ToastSelectionBox("time")
    {
        DefaultSelectionBoxItemId = "lunch",
        Items =
        {
            new ToastSelectionBoxItem("breakfast", "Breakfast"),
            new ToastSelectionBoxItem("lunch", "Lunch"),
            new ToastSelectionBoxItem("dinner", "Dinner")
        }
    }
},
New Windows 10 SDK - Toast NotificationNew Windows 10 SDK - Toast Notification

4. 提醒式输入

基本构成和上面的选择式输入一致,只不过两个 Action 按钮是系统内置的按钮类型:推迟和取消

Inputs =
{
    new ToastSelectionBox("snoozeTime")
    {
        DefaultSelectionBoxItemId = "15",
        Items =
        {
            new ToastSelectionBoxItem("5", "5 minutes"),
            new ToastSelectionBoxItem("15", "15 minutes"),
            new ToastSelectionBoxItem("60", "1 hour"),
            new ToastSelectionBoxItem("240", "4 hours"),
            new ToastSelectionBoxItem("1440", "1 day")
        }
    }
},
Buttons =
{
    new ToastButtonSnooze()
    {
        SelectionBoxId = "snoozeTime"
    },
    new ToastButtonDismiss()
}

主要看两个按钮:ToastButtonSnooze - 推迟按钮,根据上面 SelectionBox 选择的值,在指定时间后再次提醒;ToastButtonDismiss - 取消按钮,取消提醒;

New Windows 10 SDK - Toast NotificationNew Windows 10 SDK - Toast Notification

到这里就把 Windows 10 SDK 17110 中针对 Toast Notification 新增的内容介绍完了,大家如果对 Toast Notification 感兴趣,可以做更深入的研究,相信一定会对你的 UWP App 有很大帮助。

相关推荐