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

[ 本文适用于编写 Windows 运行时应用的 Windows 8.x 和 Windows Phone 8.x 开发人员。如果你要针对 Windows 10 进行开发,请参阅 最新文档 ]

注意  不使用 JavaScript?请参阅快速入门:发送 Toast 通知 (XAML)

 

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”选项必须设置为“true”(在 Visual Studio 清单编辑器中为“是”)才能发送或接收 Toast 通知。有关详细信息,请参阅如何接受 Toast 通知
  • 熟悉 XML 及其通过文档对象模型 (DOM) API 的操作。
  • 熟悉 Toast XML 架构。有关详细信息,请参阅 Toast 架构
  • 能够使用 Windows 运行时 API 创建使用 JavaScript 的基本 Windows 应用商店应用。有关详细信息,请参阅创建第一个采用 JavaScript 的 Windows 应用商店应用

说明

1. 可选:声明命名空间变量

此步骤为你提供一个短名称,用于替换完全命名空间名称。它等同于 C# 中的“using”语句或 Visual Basic 中的“Imports”语句,使用它可以简化你的代码。

注意  此快速入门中的剩余代码假定已声明此变量。

 


var notifications = Windows.UI.Notifications;

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

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

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

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

ToastImageAndText01


var template = notifications.ToastTemplateType.toastImageAndText01;
var toastXml = notifications.ToastNotificationManager.getTemplateContent(template);

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


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

3. 为通知提供文本内容

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

   
var toastTextElements = toastXml.getElementsByTagName("text");
toastTextElements[0].appendChild(toastXml.createTextNode("Hello World!"));

4. 为通知提供图像

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


var toastImageElements = toastXml.getElementsByTagName("image");

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

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

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

 


toastImageElements[0].setAttribute("src", "ms-appx:///images/redWide.png");
toastImageElements[0].setAttribute("alt", "red graphic");

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


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

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


toastImageElements[0].setAttribute("src", "https://www.microsoft.com/redWide.png");
toastImageElements[0].setAttribute("alt", "red graphic");

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

如果 baseUri 已设置为“https://www.microsoft.com/”,则示例代码中的此行如下:

toastImageElements[0].setAttribute("src", "https://www.microsoft.com/redWide.png");

可能缩短至此:

toastImageElements[0].setAttribute("src", "redWide.png");

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

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

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

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

 


var toastNode = toastXml.selectSingleNode("/toast");
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 元素。


var toastNode = toastXml.selectSingleNode("/toast");                        
var audio = toastXml.createElement("audio");

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

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

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

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

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

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


toastNode.setAttribute("duration", "long");

var audio = toastXml.createElement("audio");
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 传递到应用的字符串。此字符串没有任何特定形式,它由应用来定义。你的应用在每次被激活时必须检查作为参数形式的此字符串,并相应地调整它的视图或操作。


toastXml.selectSingleNode("/toast").setAttribute("launch", '{"type":"toast","param1":"12345","param2":"67890"}');

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

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

var toast = new notifications.ToastNotification(toastXml);

9. 发送 Toast 通知。

 
 var toastNotifier = notifications.ToastNotificationManager.createToastNotifier();
 toastNotifier.show(toast);

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

注意: 应用于 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