• Artykuł

          

Kafelki w Windows 8 - Wysyłanie aktualizacji  Udostępnij na: Facebook

Tłumaczenie na podstawie Quickstart: Sending a tile update (Windows Store apps using C#/VB/C++ and XAML): Aurelia Tokarek

Opublikowano: 2012-10-02

Kafelki rozpoczynające się jako kafelki domyślne zdefiniowane są w Twoim manifeście i wyświetlane podczas pierwszej instalacji Twojej aplikacji. Po zainstalowaniu Twojej aplikacji możesz zmienić zawartość kafelka przez powiadomienia. Ten odcinek poprowadzi Cię przez kroki definiujące zawartość, wysyłanie jej do kafelka oraz usuwanie zawartości niepotrzebnej. Te akcje demonstrowane są przez powiadomienia lokalne, czyli powiadomienia proste do zaimplementowania.

Omówimy poniższe kroki:

  • określanie szablonu dla Twojego powiadomienia,
  • pobieranie zawartości pustego szablonu XML,
  • dodawanie tekstu do powiadomienia,
  • dodawanie obrazu do powiadomienia,
  • kwadratowe i szerokie wersje opakowania powiadomienia do ładowania,
  • ustawianie czasu wygaśnięcia dla powiadomienia,
  • wysyłanie aktualizacji do kafelka jako powiadomienie lokalne.

Uwaga! W tym odcinku będziesz manipulował zawartością powiadomień bezpośrednio w XML Document Object Model (DOM). Opcjonalnie dostępna jest biblioteka NotificationsExtensions, prezentująca zawartość XML jako właściwości obiektu, zawierająca Intellisense. Więcej informacji znajdziesz w Quickstart: Using the NotificationsExtensions library in your code. Aby zobaczyć przykład użycia NotificationsExtenssions, zobacz App tiles and badges sample.

Wymagania wstępne

Aby zrozumieć ten temat potrzebujesz:

  • wiedzy praktycznej o kafelkach i warunkach powiadamiania oraz pojęć. Więcej informacji znajdziesz w Tiles, badges, and notifications,
  • znajomości schematu XML kafelka. Więcej informacji znajdziesz w Tile schema,
  • umiejętności tworzenia prostej aplikacji Windows Store przy pomocy języków: C#, C++ lub Visual Basic, używającej Windows Runtime API. Więcej informacji znajdziesz w Getting started with Windows Store apps,
  • wiadomości na temat tworzenia kodu dla aplikacji Windows Store z Extensible Application Markup Language (XAML),
  • istniejącego kafelka domyślnego dla Twojej aplikacji, zdefiniowanego w manifeście aplikacji. Więcej informacji znajdziesz w Kafelki w Windows 8 - Kafelek domyślny,
  • znajomości języka XML i jego manipulacji przez Document Object Model (DOM) API.

Instrukcje

  1. Dodanie deklaracji przestrzeni nazw.
  • Windows.UI.Notifications zawiera API kafelka:

C#

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

C++

using namespace Windows::UI::Notifications;
using namespace Windows::Data::Xml::Dom;
  1. Określenie szablonu dla kafelka oraz przygotowanie zawartości XML.

Z katalogu szablonów, dostarczonych przez system, wybierz szablon, którego układ odpowiada potrzebom Twojej zawartości. Kompletna lista szablonów znajduje się w TileTemplateType enumeration. Zauważ, że każde powiadomienie, które wysyłasz może mieć różne szablony.

W przykładzie użyliśmy szablonu TileWideImageAndText01, który wymaga jednego obrazka i jednego ciągu tekstu. Przykład przedstawiono poniżej:

C#

XmlDocument tileXml = TileUpdateManager.GetTemplateContent(TileTemplateType.TileWideImageAndText01);

C++

XmlDocument^ tileXml = TileUpdateManager::GetTemplateContent(TileTemplateType::TileWideImageAndText01);

Metoda GetTemplateContent przesyła XmlDocument. Kod przesyła poniższy szkielet XML, dla którego musisz dostarczyć szczegóły w kolejnych krokach, zmieniając DOM:

XML

<tile>
    <visual>
        <binding template="TileWideImageAndText01">
            <image id="1" src=""/>
            <text id="1"></text>
        </binding>
    </visual>
</tile>
  1. Uzupełnienie tekstu zawartości dla powiadomienia.

Ten kod najpierw przesyła wszystkie elementy w szablonie z etykietą nazwy „text”. Szablon TileWideImageAndText01 zawiera tylko pojedyncze ciągi tekstu, które następnie zostaną przypisane do kafelka. Ciąg może zajmować maksymalnie dwie linie, więc długość ciągu powinna być tak dobrana, aby uniknąć obcięcia:

C#   

XmlNodeList tileTextAttributes = tileXml.GetElementsByTagName("text");
tileTextAttributes[0].InnerText = "Hello World! My very own tile notification";

C++

XmlNodeList^ tileTextAttributes = tileXml->GetElementsByTagName("text");
tileTextAttributes->Item(0)->InnerText = "Hello World! My very own tile notification";
  1. Uzupełnienie obrazu dla powiadomienia.

Ten kod najpierw przesyła wszystkie elementy w szablonie z etykietą nazwy „image”. Szablon TheWideImageAndText01 zawiera pojedyncze obrazy. Zauważ, że nie wszystkie szablony kafelków zawierają obrazy, niektóre tylko tekst:

C#

XmlNodeList tileImageAttributes = tileXml.GetElementsByTagName("image");

C++

XmlNodeList^ tileImageAttributes = tileXml->GetElementsByTagName("image");

Obrazy mogą zostać umieszczone w paczce aplikacji, lokalnym magazynie aplikacji lub w sieci. Wersje tego kroku pokazują każde źródło obrazu. W powiadomieniu kafelka zawierającego wiele obrazów, elementy obrazu mogą używać dowolnej kombinacji tych typów źródła obrazu. Obrazy używane w szablonach powinny ważyć mniej niż 200 KB i być mniejsze niż 1024 x 1024 px. Więcej informacji znajdziesz w Tile and toast image sizes.

Poniższy kod używa lokalnego obrazka z paczki aplikacji. Ten typ obrazka zawarty jest w pliku rozwiązania Visual Studio i jest częścią Twojej aplikacji. Dostęp do tego obrazka odbywa się za pomocą przedrostka „ms-appx:///”. Dobrą praktyką jest przypisanie tekstu w celu ułatwienia dostępności dla czytników ekranu:

C#

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

C++

static_cast<XmlElement^>(tileImageAttributes->Item(0))->SetAttribute("src", "ms-appx:///images/redWide.png");                        
static_cast<XmlElement^>(tileImageAttributes->Item(0))->SetAttribute("alt", "red graphic");

Poniższy kod używa obrazka z lokalnego magazynu aplikacji. Ten typ obrazu został zapisany do lokalnego magazynu. To jest lokalizacja zwracana przez Windows.Storage.ApplicationData.Current.LocalFolder. Dostęp do obrazka odbywa się przy pomocy „ms-appdata:///local/”. Ponownie, opcjonalnie przypiszemy tekst w celu ułatwienia dostępności dla czytników ekranu:

C#

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

C++

static_cast<XmlElement^>(tileImageAttributes->Item(0))->SetAttribute("src", "ms-appx:///images/redWide.png");                        
static_cast<XmlElement^>(tileImageAttributes->Item(0))->SetAttribute("alt", "red graphic");

Poniższy kod używa obrazka z sieci. Ten obrazek jest dostępny przy użyciu protokołu „http://” lub „https://”. Zauważ, że aby obsłużyć używanie obrazów z sieci, Twoja aplikacja musi posiadać zadeklarowaną zdolność internetClient w manifeście:

C#

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

C++

static_cast<XmlElement^>(tileImageAttributes->Item(0))->SetAttribute("src", "https://www.contoso.com/redWide.png");                        
static_cast<XmlElement^>(tileImageAttributes->Item(0))->SetAttribute("alt", "red graphic");

Opcjonalnie możesz użyć atrybutu baseUri do określenia ścieżki, takiej jak https://www.contoso.com/. Jest ona połączona względem adresu URI, określonym w atrybucie src. Atrybut może być ustawiony na każdy element visual (aby zastosować do całego powiadomienia) lub element binding (aby zastosować do powiadomienia). Jeśli baseUri jest ustawiony na obu, wartość w binding nadpisuje wartość w visual.

Jeśli baseUri została ustawiona na „https://www.contoso.com/”, linia w przykładowym kodzie:

C#

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

może zostać skrócona do:

((XmlElement)tileImageAttributes[0]).SetAttribute("src", "redWide.png");
  1. Zawarcie zarówno kwadratowego, jak i szerokiego powiadomienia do ładowania.

Użytkownik może zmienić rozmiar kafelka, wybierając pomiędzy kwadratowym i szerokim, na ekranie startowym w każdej chwili. Nie istnieje żaden sposób, aby dowiedzieć się, do którego kafelka wysyłane jest powiadomienie. Jeśli rozmiar Twojego obrazka nie pasuje w Twoim powiadomieniu do szablonu kwadratowego lub szerokiego, powiadomienie nie będzie pokazywane. W związku z tym, najlepszą praktyką jest zawsze zawieranie obu wersji powiadomienia, kwadratowej i szerokiej.

Ten przykład definiuje tekst tylko kwadratowego powiadomienia, korzystający z tego samego ciągu, który używany jest w powiadomieniu szerokim:

C#

XmlDocument squareTileXml = TileUpdateManager.GetTemplateContent(TileTemplateType.TileSquareText04);

XmlNodeList squareTileTextAttributes = squareTileXml.GetElementsByTagName("text");
squareTileTextAttributes[0].AppendChild(squareTileXml.CreateTextNode("Hello World! My very own tile notification"));

C++

XmlDocument^ squareTileXml = TileUpdateManager::GetTemplateContent(TileTemplateType::TileSquareText04);

XmlNodeList^ squareTileTextAttributes = squareTileXml->GetElementsByTagName("text");
squareTileTextAttributes->Item(0)->AppendChild(squareTileXml->CreateTextNode("Hello World! My very own tile notification"));

Następnie, dodaj kwadratowy kafelek do kafelka szerokiego. Przesyłanie elementu binding, definiującego kwadratowy kafelek w ładowaniu squareTileXml, dołącza element binding jako element równorzędny do kafelka szerokiego:

C#

IXmlNode node = tileXml.ImportNode(squareTileXml.GetElementsByTagName("binding").Item(0), true);
tileXml.GetElementsByTagName("visual").Item(0).AppendChild(node);

C++

IXmlNode^ node = tileXml->ImportNode(squareTileXml->GetElementsByTagName("binding")->GetAt(0), true);
tileXml->GetElementsByTagName("visual")->Item(0)->AppendChild(node);

Wynikiem poprzedniego kroku jest umieszczenie w języku XML dwóch elementów binding, poniżej pojedynczego elementu visual:

XML

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

        <binding template="TileSquareText04">
            <text id="1">Hello World! My very own tile notification</text>
        </binding>
    </visual>
</tile>
  1. Utworzenie powiadomienia opartego o określoną zawartość XML.

C#

TileNotification tileNotification = new TileNotification(tileXml);

C++

TileNotification^ tileNotification = ref new TileNotification(tileXml);
  1. Ustawienie czasu wygaśnięcia powiadomienia.

Domyślnie, lokalne powiadomienia na kafelku i symbolu nie wygasają. Notyfikacje push, periodic i scheduled wygasają po trzech dniach. Dobrą praktyką jest ustawienie czasu wygaśnięcia, szczególnie lokalnego powiadomienia kafelka oraz symbolu, używając czasu, który ma sens w Twojej aplikacji. Zawartość Twoich kafelków powinna istnieć nie dłużej niż jest to wymagane. W tym przypadku, powiadomienia wygasną i zostaną usunięte z kafelka w ciągu dziesięciu sekund:

C#

tileNotification.ExpirationTime = DateTimeOffset.UtcNow.AddSeconds(10);

C++

int seconds = 10;
auto cal = ref new Windows::Globalization::Calendar();
cal->AddSeconds(seconds);    
tileNotification->ExpirationTime = cal->GetDateTime();
  1. Przesłanie powiadomienia do kafelka aplikacji

C#

TileUpdateManager.CreateTileUpdaterForApplication().Update(tileNotification);

C++

Windows::UI::Notifications::TileUpdateManager::CreateTileUpdaterForApplication()->Clear();
  1. Opcjonalnie: wyczyszczenie powiadomienia kafelka.

Ten przykład pokazuje, jak wyczyścić powiadomienia kafelka przez lokalne wywołanie. Zauważ, że jeżeli Twoja zawartość jest zależna od czasu, zalecamy, abyś ustawił czas wygaśnięcia powiadomienia zamiast jawnego wyczyszczenia. Poniższa linia kodu czyści bieżące powiadomienia z kafelka aplikacji:

C#

Windows.UI.Notifications.TileUpdateManager.CreateTileUpdaterForApplication().Clear();

C++

Windows::UI::Notifications::TileUpdateManager::CreateTileUpdaterForApplication()->Clear();

Dla kafelka z włączoną kolejką powiadomień i powiadomieniami w kolejce, wywołaj metodę Clear czyszczącą kolejkę.

Zauważ, że nie możesz wyczyścić powiadomień z Chmury. Lokalne wywołanie metody Clear wyczyści kafelki niezależnie od źródła powiadomień, ale powiadomienia periodic i push mogą być aktualizowane tylko poprzez nową zawartość kafelka.

Podsumowanie i następne kroki

W tym szybkim starcie zdefiniowałeś i wysłałeś nową zawartość w Twoim kafelku aplikacji przez powiadomienie, które zostało usunięte po 10 minutach. Poniższy kod podsumowuje kroki, od wyboru szablonu przez przesłanie powiadomienia. Używa obrazka z paczki aplikacji:

C#

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

TileUpdateManager.GetTemplateContent(TileTemplateType.TileWideImageAndText01);

XmlNodeList tileTextAttributes = tileXml.GetElementsByTagName("text");
tileTextAttributes[0].InnerText = "Hello World! My very own tile notification";

XmlNodeList tileImageAttributes = tileXml.GetElementsByTagName("image");
((XmlElement)tileImageAttributes[0]).SetAttribute("src", "ms-appx:///images/redWide.png");
((XmlElement)tileImageAttributes[0]).SetAttribute("alt", "red graphic");

XmlDocument squareTileXml = TileUpdateManager.GetTemplateContent(TileTemplateType.TileSquareText04);
XmlNodeList squareTileTextAttributes = squareTileXml.GetElementsByTagName("text");
squareTileTextAttributes[0].AppendChild(squareTileXml.CreateTextNode("Hello World! My very own tile notification"));
IXmlNode node = tileXml.ImportNode(squareTileXml.GetElementsByTagName("binding").Item(0), true);
tileXml.GetElementsByTagName("visual").Item(0).AppendChild(node);

TileNotification tileNotification = new TileNotification(tileXml);

tileNotification.ExpirationTime = DateTimeOffset.UtcNow.AddSeconds(10);

TileUpdateManager.CreateTileUpdaterForApplication().Update(tileNotification);

C++

using namespace Windows::UI::Notifications;
using namespace Windows::Data::Xml::Dom;
namespace WFC = Windows::Foundation::Collections;

XmlDocument^ tileXml = TileUpdateManager::GetTemplateContent(TileTemplateType::TileWideImageAndText01);

XmlNodeList^ tileTextAttributes = tileXml->GetElementsByTagName("text");
tileTextAttributes->Item(0)->InnerText = "Hello World! My very own tile notification";

XmlNodeList^ tileImageAttributes = tileXml->GetElementsByTagName("image");
static_cast<XmlElement^>(tileImageAttributes->Item(0))->SetAttribute("src", "ms-appx:///images/redWide.png");                        
static_cast<XmlElement^>(tileImageAttributes->Item(0))->SetAttribute("alt", "red graphic");

XmlDocument^ squareTileXml = TileUpdateManager::GetTemplateContent(TileTemplateType::TileSquareText04);
XmlNodeList^ squareTileTextAttributes = squareTileXml->GetElementsByTagName("text");
squareTileTextAttributes->Item(0)->AppendChild(squareTileXml->CreateTextNode("Hello World! My very own tile notification"));
IXmlNode^ node = tileXml->ImportNode(squareTileXml->GetElementsByTagName("binding")->GetAt(0), true);
tileXml->GetElementsByTagName("visual")->Item(0)->AppendChild(node);

TileNotification^ tileNotification = ref new TileNotification(tileXml);

int seconds = 10;
auto cal = ref new Windows::Globalization::Calendar();
cal->AddSeconds(seconds);    
tileNotification->ExpirationTime = cal->GetDateTime();

TileUpdateManager::CreateTileUpdaterForApplication()->Update(tileNotification);

Teraz wykonałeś swoją pierwszą aktualizację kafelka. Możesz rozszerzyć funkcjonalność kafelków, włączając kolejkę powiadomień. W tym odcinku wysyłaliśmy aktualizację poprzez powiadomienie lokalne. Możesz także wykorzystać inne metody dostarczania powiadomień: scheduled, periodic lub push. Więcej informacji znajdziesz w Delivering notifications.

W kolejnym odcinku nauczymy się przesyłać aktualizację symbolu na kafelku.