快速入门：发送磁贴更新 (HTML) - Windows app development

项目
12/11/2015

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

磁贴始于默认磁贴，默认磁贴是在你的清单中定义的，并当第一次安装你的应用时会显示默认磁贴。在安装你的应用之后，你可以通过通知更改你的磁贴的内容。本快速入门指导你逐步完成执行以下操作所需的步骤：定义新磁贴内容、将该内容发送到你的磁贴并在该内容不再需要时将其删除。这些操作是通过本地通知演示的，本地通知是实现起来最简单的通知。我们将讨论以下步骤：

为通知指定模板
检索模板的空白 XML 内容
将文本添加到通知中
将图像添加到通知中
在单个负载中针对不同的磁贴大小打包不同的通知版本
为通知设置到期时间
将你的更新作为本地通知发送给你的磁贴

请将此操作功能视为我们的应用功能大全系列的一部分。: Windows 应用商店应用 UI 全解

注意在此快速入门中，你将直接通过 XML 文档对象模型 (DOM) 操作通知内容。通过 NotificationsExtensions 库可获得一种可选方法，该库将 XML 内容作为对象属性（包括 Intellisense）提供。有关详细信息，请参阅快速入门：在代码中使用 NotificationsExtensions 库。若要查看此快速入门中使用 NotificationsExtensions 表示的代码，请参阅应用磁贴和锁屏提醒示例。

先决条件

要理解本主题，你将需要：

了解磁贴和通知术语及概念。有关详细信息，请参阅磁贴、锁屏提醒以及通知。
熟悉磁贴 XML 架构。有关详细信息，请参阅磁贴架构。
能够使用 Windows 运行时 API 创建使用 JavaScript 的基本 Windows 应用商店应用。有关详细信息，请参阅创建第一个采用 JavaScript 的 Windows 应用商店应用。
你的应用的一个现有默认磁贴（在你的应用清单中定义）。有关详细信息，请参阅快速入门：使用 Microsoft Visual Studio 清单编辑器创建默认磁贴。
熟悉 XML 及其通过文档对象模型 (DOM) API 的操作。

说明

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

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

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


var notifications = Windows.UI.Notifications;

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

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

该示例使用 TileWide310x150ImageAndText01 模板，该模板需要一个图像和一个文本字符串。示例如下：

TileWide310x150ImageAndText01


var template = notifications.TileTemplateType.tileWide310x150ImageAndText01;                      
var tileXml = notifications.TileUpdateManager.getTemplateContent(template);

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

注意在 Windows 8 系统中调用 getTemplateContent 时，它会返回版本 1 模板。在 Windows 8.1 系统上调用此方法时，它会返回仅适用于 Windows Phone 模板的版本 2 模板或版本 3 模板。如果应用在其清单中指定了 Windows 8 兼容性，则无论 Windows 是什么版本，该方法都会返回版本 1 模板。在本主题中，我们将使用版本 2 模板。


<tile>
    <visual version="2">
        <binding template="TileWide310x150ImageAndText01" fallback="TileWideImageAndText01">
            <image id="1" src=""/>
            <text id="1"></text>
        </binding>
    </visual>
</tile>

3. 为通知提供文本内容

此代码首先检索模板中标记名称为“text”的所有元素。TileWide310x150ImageAndText01 模板仅包含单个文本字符串，代码接着将分配该字符串。此字符串最多可以在两行内自动换行，因此应该相应地设置字符串的长度以避免截断。


var tileTextAttributes = tileXml.getElementsByTagName("text");   
tileTextAttributes[0].appendChild(tileXml.createTextNode("Hello World! My very own tile notification"));

4. 为通知提供图像

此代码首先检索模板中标记名称为“image”的所有元素。TileWide310x150ImageAndText01 模板中包含单个图像。请注意，并非所有磁贴模板都包含图像；某些磁贴模板是仅文本的。

要点此处使用的图像“redWide.png”只是一个示例，并未包含在 Microsoft Visual Studio 项目中。你需要将“redWide.png”替换为你所拥有的已添加到该项目的实际图像名称，然后再尝试发送此通知。如果未执行此操作，将不会传递此通知。


var tileImageAttributes = tileXml.getElementsByTagName("image");

可以从应用的程序包、应用的本地存储或从 Web 使用图像。将针对每个图像源显示此步骤的各个版本。在包含多个图像的磁贴通知中，图像元素可以使用这些图像源类型的任意组合。模板中使用的图像都要求大小小于 200 KB，小于 1024 x 1024 像素。有关详细信息，请参阅磁贴和 Toast 图像大小。

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


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

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


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

以下代码使用了 Web 图像。这些图像是通过使用“http://”或“https://”协议指定图像的路径来进行访问的。请注意，你必须在你的应用的清单中声明 internetClient 功能才能使用 Web 图像。


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

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

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


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

可能缩短至此：


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

5. 在负载中包含针对多个磁贴大小的通知绑定

用户可以随时在“开始”屏幕上调整你的磁贴的大小，且当你发送通知时，没有任何办法了解磁贴所处的状态（小型、中型、长方形或大型）。如果调整了你的磁贴的大小，这样在你的通知中就不存在匹配的模板绑定，将不会显示该通知。因此，最佳做法是始终在负载中针对所有动态磁贴大小（中型、长方形、大型）包含通知版本，你针对这些版本在清单中提供了徽标图像。

注意从 Windows Phone 8.1 开始，大型磁贴在手机上不受支持。

此示例使用在加宽通知中使用的文本字符串定义了一个纯文本中等通知。

       
var squareTemplate = notifications.TileTemplateType.tileSquare150x150Text04;
var squareTileXml = notifications.TileUpdateManager.getTemplateContent(squareTemplate);

var squareTileTextAttributes = squareTileXml.getElementsByTagName("text");   
squareTileTextAttributes[0].appendChild(squareTileXml.createTextNode("Hello World! My very own tile notification"));

接下来，向加宽磁贴的负载添加中等磁贴。检索在 squareTileXml 负载中定义中等磁贴的 binding 元素。作为加宽磁贴的同级附加该 binding 元素。


var node = tileXml.importNode(squareTileXml.getElementsByTagName("binding").item(0), true);
tileXml.getElementsByTagName("visual").item(0).appendChild(node);

前面的步骤在 XML 负载的一个 visual 元素下产生两个 binding 元素，如下所示：


<tile>
    <visual visual="2">
        <binding template="TileWide310x150ImageAndText01" fallback="TileWideImageAndText01">
            <image id="1" src="ms-appx:///images/redWide.png"/>
            <text id="1">Hello World! My very own tile notification</text>
        </binding>

        <binding template="TileSquare150x150Text04" fallback="TileSquareText04">
            <text id="1">Hello World! My very own tile notification</text>
        </binding>
    </visual>
</tile>

6. 基于已经指定的 XML 内容创建通知


var tileNotification = new notifications.TileNotification(tileXml);

7. 为通知设置到期时间

默认情况下，本地磁贴和锁屏提醒不会过期，推送通知、定期通知、激活通知会在三天之后过期。最好通过使用一个对你的应用有意义的时间设置过期时间，对于本地磁贴和锁屏提醒通知尤其如此。磁贴内容的保留时间应不长于内容具有相关性的时间。在这种情况下，该通知将在十分钟内到期并从磁贴中删除。


var currentTime = new Date();
tileNotification.expirationTime = new Date(currentTime.getTime() + 600 * 1000);

8. 向应用磁贴发送通知。


notifications.TileUpdateManager.createTileUpdaterForApplication().update(tileNotification);

9. 可选：清除你的磁贴通知

此示例显示如何通过本地调用清除磁贴通知。请注意，如果内容有时间限制，则建议你设置通知的过期时间，而不是显式将其清除。下面的这行代码将从应用的磁贴中清除当前通知。


notifications.TileUpdateManager.createTileUpdaterForApplication().clear();

对于启用通知队列且在队列中有通知的磁贴，调用 clear 方法清空队列。

请注意，不能通过云清除通知。尽管在本地调用 clear 方法会清除磁贴而不考虑其通知的来源，但是定期通知或推送通知只能将磁贴更新为新内容。

摘要和后续步骤

在本快速入门中，你定义了新内容并通过通知将它发送到该应用的磁贴，通知会在 10 分钟之后被。下面的代码概述了上面的步骤：从选择模板到发送通知。它使用来自应用包的图像。

若要在你拥有的示例中测试此代码，请将其放置在由示例 UI 中的某个按钮触发的函数内。例如，你可以将该按钮放置在 default.html 文件中。记住替换实际图像的名称。


var notifications = Windows.UI.Notifications;

var template = notifications.TileTemplateType.tileWide310x150ImageAndText01;                      
var tileXml = notifications.TileUpdateManager.getTemplateContent(template);

var tileTextAttributes = tileXml.getElementsByTagName("text");   
tileTextAttributes[0].appendChild(tileXml.createTextNode("Hello World! My very own tile notification"));

var tileImageAttributes = tileXml.getElementsByTagName("image");
tileImageAttributes[0].setAttribute("src", "ms-appx:///assets/redWide.png");
tileImageAttributes[0].setAttribute("alt", "red graphic");

var squareTemplate = notifications.TileTemplateType.tileSquare150x150Text04;
var squareTileXml = notifications.TileUpdateManager.getTemplateContent(squareTemplate);
var squareTileTextAttributes = squareTileXml.getElementsByTagName("text");   
squareTileTextAttributes[0].appendChild(squareTileXml.createTextNode("Hello World! My very own tile notification"));

var node = tileXml.importNode(squareTileXml.getElementsByTagName("binding").item(0), true);
tileXml.getElementsByTagName("visual").item(0).appendChild(node);

var tileNotification = new notifications.TileNotification(tileXml);

var currentTime = new Date();
tileNotification.expirationTime = new Date(currentTime.getTime() + 600 * 1000);

notifications.TileUpdateManager.createTileUpdaterForApplication().update(tileNotification);

在执行了第一次磁贴更新之后，可以通过启用通知队列来扩展你的磁贴的功能。

此快速入门将磁贴更新作为本地通知发送。你还可以探索其他通知传递方法：已计划、定期和推送。有关详细信息，请参阅交付通知。

通过