快速入門：傳送磚更新 (HTML) - Windows app development

發行項
12/11/2015

[ 本文的目標對象是撰寫 Windows 執行階段 App 的 Windows 8.x 和 Windows Phone 8.x 開發人員。如果您正在開發適用於 Windows 10 的 App，請參閱最新文件 ]

磚一開始為您在資訊清單中定義的預設磚，預設磚會在您的應用程式第一次安裝時顯示。在應用程式安裝後，您可以透過通知來變更磚的內容。這個快速入門會逐步引導您定義新的磚內容、將內容傳送到磚，以及在該內容不再需要時將它移除等步驟。這些動作是透過本機通知示範的，而本機通知是實作上最簡單的通知。我們討論以下步驟：

指定通知的範本
擷取範本的空白 XML 內容
新增通知的文字
新增通知的影像
在單一承載中封裝不同磚大小的不同通知版本
設定通知的到期時間
以本機通知的形式將更新傳送到磚

如需了解此功能的運作情形，請參閱應用程式功能，從開始到完成系列: Windows 市集應用程式 UI，從開始到完成

注意在這個快速入門中，您將直接透過 XML 文件物件模型 (DOM) 來操作通知內容。另外還有透過 NotificationsExtensions 程式庫的選擇性方法，這個程式庫會以物件屬性的形式呈現 XML 內容，包含 Intellisense。如需詳細資訊，請參閱快速入門：在程式碼中使用 NotificationsExtensions 程式庫。若要查看這個快速入門中以 NotificationsExtensions 表示的程式碼，請參閱應用程式磚和徽章範例。

先決條件

為了解這個主題，您將需要：

磚與通知詞彙及概念的實用知識。如需詳細資訊，請參閱磚、徽章及通知。
熟悉磚 XML 結構描述。如需詳細資訊，請參閱磚結構描述。
能夠使用 Windows 執行階段 API 透過 JavaScript 建立基本 Windows 市集應用程式的能力。如需詳細資訊，請參閱使用 JavaScript 建立您的第一個 Windows 市集應用程式。
您應用程式現有的預設磚 (在您的應用程式資訊清單中定義)。如需詳細資訊，請參閱快速入門：使用 Microsoft Visual Studio 資訊清單編輯器建立預設磚。
熟悉 XML 和透過文件物件模型 (DOM) API 操作 XML 的方法。

指示

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");

影像的來源可以是應用程式的套件、應用程式的本機存放區或網路。針對每個影像來源，分別顯示了這個步驟的不同版本。在包含多個影像的磚通知中，影像元素可以使用那些影像來源類型的任意組合。範本中使用的影像大小都必須小於 200 KB 且小於 1024 x 1024 像素。如需詳細資訊，請參閱磚與快顯通知影像大小。

下列程式碼使用應用程式套件的本機影像。這種影像類型包含於 Visual Studio 方案檔中，而且是封裝為您應用程式的一部分。可使用 "ms-appx:///" 首碼存取這些影像。為呈現最佳做法，我們也會針對協助工具用途 (如螢幕助讀程式) 指派替代文字。


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

下列程式碼使用應用程式本機存放區的本機影像。應用程式已將此類型的影像儲存在其本機存放區中。這是由 Windows.Storage.ApplicationData.current.localFolder 傳回的位置。可使用 "ms-appdata:///local/" 首碼存取這些影像。同樣地，我們也會針對協助工具用途 (如螢幕助讀程式) 指派選擇性的替代文字。


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

下列程式碼使用網頁影像。可使用 "http://" 或 "https://" 通訊協定指定影像的路徑，以存取這些影像。請注意，您的應用程式必須在其資訊清單中宣告 internetClient 功能，才能使用網頁影像。


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);

前面的步驟使得兩個 binding 元素在 XML 承載中的單一 visual 元素之下，其結果顯示如下：


<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. 設定通知的到期時間

根據預設，本機磚和徽章通知不會到期，而推播、定期以及排程通知則會在三天後到期。特別是在本機磚和徽章通知設定到期時間是最佳的做法，請使用對您的應用程式有意義的時間。磚內容持續的時間不應超過內容的時效性。在這個案例中，通知即將到期，而且會在 10 分鐘之後從磚移除。


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);

您已經執行完第一次的磚更新，現在可以透過啟用通知佇列來擴充磚的功能。

這個快速入門將磚更新以本機通知的形式傳送。您也可以探索其他通知傳遞方法：排程、定期及推播。如需詳細資訊，請參閱傳遞通知。