语言: HTML | XAML

快速入门:发送 Toast 通知 (XAML)

注意  不使用 C#/VB/C++?请参阅快速入门:发送 Toast 通知 (HTML)

Toast 通知是显示在屏幕上的弹出 UI,当用户在另一个应用中、在“开始”屏幕上或(对于 Windows)在桌面上时,通过 Toast 通知应用可与用户进行通信。本快速入门指导你完成定义和显示 Toast 内容的步骤。 这些操作通过本地通知演示,本地通知是要实现的最简单的通知。我们将讨论以下步骤:

  • 为通知指定模板
  • 检索模板的空白 XML 内容
  • 将文本添加到通知中
  • 向通知中添加图像
  • 设置通知的持续时间
  • 指定伴随通知的音频
  • 当应用由通知激活时提供使用的上下文信息
  • 将 Toast 作为本地通知发送
注意  在此快速入门中,你将直接通过 XML 文档对象模型 (DOM) 操作通知内容。通过 NotificationsExtensions 库可获得一种可选方法,该库将 XML 内容作为对象属性(包括 Intellisense)提供。有关详细信息,请参阅快速入门:在代码中使用 NotificationsExtensions 库。要查看此快速入门中使用 NotificationsExtenstions 表示的代码,请参阅 Toast 通知示例
注意  当通过 Microsoft Visual Studio 测试 Toast 通知代码功能时,你必须在 Windows x86、x64 或 Windows 运行时计算机上使用本地计算机或远程计算机调试设置。你无法使用 Visual Studio 模拟器调试功能选项—你的代码将在该模拟器中进行编译和运行,但不会显示 Toast。

先决条件

要理解本主题,你将需要:

  • 了解 Toast 通知术语及概念。有关详细信息,请参阅 Toast 概述
  • 了解一般通知术语及概念。有关详细信息,请参阅发送通知
  • 熟悉 Toast XML 架构,基本熟悉 XML 及其通过文档对象模型 (DOM) API 的操作。有关详细信息,请参阅 Toast 架构
  • 能够使用 Windows 运行时 API 创建使用 C#、C++ 或 Microsoft Visual Basic 的基本 Windows 应用商店应用,了解如何用这些语言为采用 Extensible Application Markup Language (XAML) 的 Windows 应用商店应用创建代码隐藏文件。有关详细信息,请参阅使用 C# 或 Visual Basic 创建你的第一个 Windows 应用商店应用

而且,你必须已经在你的应用的清单中声明该应用能够接收 Toast 通知。有关详细信息,请参阅如何接受 Toast 通知

说明

1. 添加命名空间声明

Windows.UI.Notifications 包含 Toast API。



using Windows.UI.Notifications;
using Windows.Data.Xml.Dom;

2. 为 Toast 选取一个模板并检索其 XML 内容

从系统提供的模板目录中,选择一个适合你的内容的需求的模板。有关完整的模板列表,请参阅 ToastTemplateType 枚举。请注意,你发送的每个单独的通知都可以使用一个不同的模板。

注意  Windows Phone 8.1 上仅支持 toastText02 模板的一个变体。它可接受两个文本字符串(第一个字符串以粗体文本呈现),但是它们位于同一行上,因此应该仅使用一个短字符串或两个非常短的字符串以避免串联。

此示例(适用于 Windows)使用 ToastImageAndText01 模板,该模板需要一个图像和一个文本字符串。示例如下所示:

ToastImageAndText01



ToastTemplateType toastTemplate = ToastTemplateType.ToastImageAndText01; 
XmlDocument toastXml = ToastNotificationManager.GetTemplateContent(toastTemplate);

GetTemplateContent 方法返回一个 XmlDocument。上面的代码检索以下 XML 框架,你将在后续步骤中通过标准文档对象模型 (DOM) 函数提供该内容的详细信息:



<toast>
    <visual>
        <binding template="ToastImageAndText01">
            <image id="1" src=""/>
            <text id="1"></text>
        </binding>
    </visual>
</toast>

3. 为通知提供文本内容

该示例首先检索模板中标记名称为“text”的所有元素。ToastImageAndText01 模板只包含一个代码分配的文本字符串。该字符串最多可包含三行自动换行的字符串,因此应该相应地设置该字符串的长度以避免被截断。


   
XmlNodeList toastTextElements = toastXml.GetElementsByTagName("text");
toastTextElements[0].AppendChild(toastXml.CreateTextNode("Hello World!"));

4. 为通知提供图像

此代码首先检索模板中标记名称为“image”的所有元素。Toast 模板(如 toastImageAndText01)将最多包含一个图像。请注意,并非所有 Toast 模板都包含图像;某些磁贴模板是仅文本的。


XmlNodeList toastImageAttributes = toastXml.GetElementsByTagName("image");

可以从应用的程序包、应用的本地存储或从 Web 使用图像。将针对每个图像源显示此步骤的各个版本。图像都要求大小小于 200 KB,小于 1024 x 1024 像素。有关详细信息,请参阅磁贴和 Toast 图像大小

以下代码使用应用的程序包中的本地图像。此类型的图像包含在 Visual Studio 解决方案文件中,并且作为应用的一部分封装。这些图像是通过使用“ms-appx:///”前缀进行访问的。作为一种最佳做法,我们还为辅助功能(如屏幕阅读器)分配可选 alt 文本。

要点  此处使用的图像“redWide.png”只是一个示例,并且未包含在 Microsoft Visual Studio 项目中。你需要将“redWide.png”替换为你所拥有的已添加到该项目的实际图像名称,然后再尝试发送此 Toast。


((XmlElement)toastImageAttributes[0]).SetAttribute("src", "ms-appx:///assets/redWide.png");
((XmlElement)toastImageAttributes[0]).SetAttribute("alt", "red graphic");

以下代码使用应用的本地存储中的本地图像。你的应用已将此类型的图像保存到其本地存储中。此为 Windows.Storage.ApplicationData.Current.LocalFolder 返回的位置。这些图像是通过使用“ms-appdata:///local/”前缀进行访问的。同样,我们还为辅助功能(如屏幕阅读器)分配可选 alt 文本。



((XmlElement)toastImageAttributes[0]).SetAttribute("src", "ms-appdata:///local/redWide.png");
((XmlElement)toastImageAttributes[0]).SetAttribute("alt", "red graphic");

以下代码使用 Web 图像。这些图像是通过使用“http://”协议指定图像的路径来进行访问的。你还可以使用“https://”协议。



((XmlElement)toastImageAttributes[0]).SetAttribute("src", "http://www.contoso.com/redWide.png");
((XmlElement)toastImageAttributes[0]).SetAttribute("alt", "red graphic");

你可以使用可选的 baseUri 属性来指定一个根路径(如“http://www.contoso.com/”),该路径与在任何图像的 src 属性中指定的任何相对统一资源标识符 (URI) 相结合。此属性可以在 visual 元素(以应用于整个通知)或 binding 元素(以应用于该绑定)上设置。如果同时在这两个元素上设置 baseUri,那么 binding 中的值将覆盖 visual 中的值。

如果将 baseUri 设置为“http://www.contoso.com/”,则示例代码中的此行:



((XmlElement)toastImageAttributes[0]).SetAttribute("src", "http://www.contoso.com/redWide.png");

可能缩短至此:



((XmlElement)toastImageAttributes[0]).SetAttribute("src", "redWide.png");

5. 可选:指定 Toast 持续时间

你可以选择为 Toast 设置显示持续时间。有两个值:“short”(默认值)和“long”。仅当你的通知属于来电或约会提醒之类的情形时,才使用“long”。有关详细信息,请参阅 Toast 通知概述

注意  Windows Phone 8.1 上不支持不同的持续时间;所有 Toast 的持续时间都相同。如果将此属性包含在手机 Toast 通知中,则会将其忽略。

注意  默认的持续时间是“short”,因此添加此属性只是为了将持续时间设置为“long”。


IXmlNode toastNode = toastXml.SelectSingleNode("/toast");
((XmlElement)toastNode).SetAttribute("duration", "long");

6. 可选:指定 Toast 音频

有关 Toast 音频的详细信息,请参阅 Toast 音频选项目录

默认情况下,Windows 在显示 Toast 时播放一个较短的声音。你可以选择指定系统提供的声音集中的不同的声音,也可以不指定任何声音。在 Windows Phone 8.1 上,你可以指定自定义声音。有关详细信息,请参阅 Toast 音频选项目录

通过 getTemplateContent 检索的模板不包含 audio 元素,因此你必须定义该元素并将其添加到 XML 负载。通过使用“ms-winsoundevent:”前缀或者在 Windows Phone 8.1 上通过使用“ms-appx:///”或“ms-appdata:///”前缀的路径来指定声音文件。该示例创建一个 audio 元素并选择将成为其父元素的 toast 元素。



IXmlNode toastNode = toastXml.SelectSingleNode("/toast");                        
XmlElement audio = toastXml.CreateElement("audio");

该示例指定非默认的声音。


audio.SetAttribute("src", "ms-winsoundevent:Notification.IM");

该示例指定不应该播放任何声音。


audio.SetAttribute("silent", "true");

如果是持续时间较长的 Toast 通知,则可以循环该声音而不是仅播放一次。请注意,循环音频仅对持续时间较长的 Toast 有效。指定在系统指定的声音集中包含的可用于循环的声音。该示例指定循环声音。

注意  由于它不支持持续时间较长的 Toast,因此 Windows Phone 8.1 不支持循环的音频。



((XmlElement)toastNode).SetAttribute("duration", "long");

audio.SetAttribute("src", "ms-winsoundevent:Notification.Looping.Alarm");
audio.SetAttribute("loop", "true");

定义 audio 元素之后,你必须将其附加到 Toast 的 XML 负载,作为 toast 元素的子元素,如下所示。


toastNode.AppendChild(audio);

7. 指定应用的启动参数

当用户单击你的 Toast 通知时,你的应用应当会启动,并显示与该通知的内容相关的视图。若要实现此目的,请使用 Toast 元素的 launch 属性,该属性提供一个在通过 Toast 启动应用时,从 Toast 传递到应用的字符串。此字符串没有任何特定形式,它由应用来定义。你的应用在每次被激活时必须检查作为参数形式的此字符串,并相应地调整它的视图或操作。



((XmlElement)toastNode).SetAttribute("launch", "{\"type\":\"toast\",\"param1\":\"12345\",\"param2\":\"67890\"}");

注意  在 Windows Phone Silverlight 8.1 中,启动字符串的值附加到默认启动页的 URI。例如,如果你提供启动字符串 "?conversation=71",则它将产生诸如 /MainPage.xaml?conversation=71 的 URI。因此,启动字符串还必须是有效的查询字符串;否则,将引发异常。

8. 基于已经指定的 XML 内容创建 Toast 通知。


ToastNotification toast = new ToastNotification(toastXml);

9. 发送 Toast 通知。


ToastNotificationManager.CreateToastNotifier().Show(toast);

注意  在 Windows Phone Silverlight 8.1 中,如果当前前台应用是 ToastNotifier.Show 方法的调用方,则不显示 toast。在这种情况下,toast 应该主要由后台代理程序使用。

注意:  对于 Windows 应用商店应用,应用于 Toast 通知的背景颜色就是在应用的应用清单中为其磁贴声明的背景颜色。有关详细信息,请参阅快速入门:使用 Visual Studio 清单编辑器创建默认磁贴

摘要和后续步骤

在本快速入门中,你向用户发送了本地 Toast 通知。

本快速入门将 Toast 作为本地通知发送,本地通知是要实现的最简单的通知类型,并且允许你快速查看结果。接下来,你应该探索其他 Toast 通知传递方法:计划和推送。有关详细信息,请参阅传送通知

相关主题

示例
Toast 通知示例
从桌面应用示例发送 Toast 通知
Reversi 示例功能方案:Toast 通知
概念
Toast 通知概述
Toast 模板目录
Toast 音频选项目录
说明性
快速入门:发送推送通知
如何处理来自 Toast 通知的激活
如何接受 Toast 通知
如何计划 Toast 通知
快速入门:从桌面发送 Toast 通知
如何通过 AppUserModelID 启用桌面 Toast 通知
最佳做法
Toast 通知指南和清单
参考
Toast XML 架构
ToastNotification
ToastNotificationManager
ToastNotifier

 

 

显示:
© 2015 Microsoft