共用方式為


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

注意  不是使用 JavaScript?請參閱快速入門:傳送磚更新 (XAML)

 

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

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

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

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

 

先決條件

為了解這個主題,您將需要:

指示

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

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

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

相關主題

應用程式磚和徽章範例

磚與快顯通知影像大小

磚與磚通知概觀

磚的指導方針和檢查清單

如何排程磚通知

快速入門:設定定期通知

快速入門:使用 Visual Studio 資訊清單編輯器建立預設磚

磚範本目錄

磚 XML 結構描述

Windows.UI.Notifications