Schnellstart: Senden eines Kachelupdates (HTML)

  • Artikel

[ Dieser Artikel richtet sich an Windows 8.x- und Windows Phone 8.x-Entwickler, die Windows-Runtime-Apps schreiben. Wenn Sie für Windows 10 entwickeln, finden Sie weitere Informationen unter neueste Dokumentation]

Hinweis  Sie verwenden nicht JavaScript? Weitere Informationen hierzu finden Sie unter Schnellstart: Senden eines Kachelupdates (XAML).

 

Den Anfang einer Kachel bildet eine Standardkachel, die Sie im Manifest definieren und die bei der erstmaligen Installation Ihrer App angezeigt wird. Nach der Installation der App können Sie den Inhalt der Kachel mithilfe von Benachrichtigungen ändern.Diese Schnellstartanleitung führt Sie durch die Schritte, die notwendig sind, um neue Kachelinhalte zu definieren, die Inhalte an eine Kachel zu senden und die Inhalte zu entfernen, sobald sie nicht mehr benötigt werden. Diese Aktionen werden mithilfe einer lokalen Benachrichtigung veranschaulicht, da dies die am einfachsten zu implementierende Form einer Benachrichtigung ist. Die folgende Schritte werden erläutert:

  • Angeben einer Vorlage für die Benachrichtigung
  • Abrufen des leeren XML-Inhalts der Vorlage
  • Hinzufügen von Text zur Benachrichtigung
  • Hinzufügen eines Bilds zur Benachrichtigung
  • Verpacken unterschiedlicher Benachrichtigungsversionen für verschiedene Kachelgrößen in einer einzigen Nutzlast
  • Festlegen einer Ablaufzeit für die Benachrichtigung
  • Senden des Updates als lokale Benachrichtigung an die Kachel

Sehen Sie dieses Feature in unserer Reihe App-Features von A bis Z in Aktion.: Windows Store-App-Benutzeroberfläche von A bis Z

Hinweis  In dieser Anleitung wird der Benachrichtigungsinhalt direkt über das XML-DOM (Dokumentobjektmodell) gesteuert. Über die NotificationsExtensions-Bibliothek steht ein optionaler Ansatz zur Verfügung, bei dem der XML-Inhalt in Form von Objekteigenschaften dargestellt wird, wobei Sie u. a. IntelliSense nutzen können. Weitere Informationen finden Sie unter Schnellstart: Verwenden der NotificationsExtensions-Bibliothek im Code. Die NotificationsExtensions-Variante des Codes in dieser Schnellstartanleitung finden Sie unter Beispiel für App-Kacheln und Signale.

 

Voraussetzungen

Die Ausführungen in diesem Thema setzen Folgendes voraus:

Anweisungen

1. Optional: Deklarieren einer Namespacevariablen

In diesem Schritt wird Ihnen ein Kurzname zur Verfügung gestellt, den Sie anstelle des vollständigen Namespacenamens verwenden können. Dies ist das Äquivalent zur "using"-Anweisung in C# oder der "Imports"-Anweisung in Visual Basic. So können Sie den Code vereinfachen.

Hinweis  Im verbleibenden Teil des Codes in diesem Schnellstart wird davon ausgegangen, dass diese Variable deklariert wurde.

 


var notifications = Windows.UI.Notifications;

2. Auswählen einer Vorlage für die Kachel und Abrufen der XML-Inhalte

Wählen Sie aus dem vom System bereitgestellten Vorlagenkatalog eine Vorlage aus, die die Layoutanforderungen der gewünschten Inhalte am besten erfüllt. Die vollständige Vorlagenliste finden Sie in der TileTemplateType-Enumeration. Beachten Sie, dass für jede separate Benachrichtigung, die gesendet wird, eine andere Vorlage verwendet werden kann.

In diesem Beispiel wird die TileWide310x150ImageAndText01-Vorlage verwendet, für die ein Bild und eine Textzeichenfolge erforderlich sind. Hier sehen Sie ein Beispiel:

TileWide310x150ImageAndText01


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

Die GetTemplateContent-Methode gibt ein XmlDocument zurück. Der obige Code ruft das folgende XML-Skelett ab, dessen Details Sie in den folgenden Schritten mithilfe standardmäßiger DOM (Document Object Model)-Funktionen bereitstellen.

Hinweis  Wenn getTemplateContent in einem System unter Windows 8 aufgerufen wird, wird eine Version 1-Vorlage zurückgegeben. Wenn diese Methode auf einem System unter Windows 8.1 aufgerufen wird, wird eine Version 2-Vorlage oder bei nur für Windows Phone vorgesehenen Vorlagen eine Version 3-Vorlage zurückgegeben. Wenn im Manifest einer App die Kompatibilität mit Windows 8 angegeben ist, gibt diese Methode unabhängig von der Windows-Version eine Version 1-Vorlage zurück. In diesem Thema wird eine Version 2-Vorlage verwendet.

 


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

3. Angeben des Textinhalts für die Benachrichtigung

Dieser Code ruft zuerst alle Elemente in der Vorlage mit dem Tagnamen "text" ab. Die TileWide310x150ImageAndText01-Vorlage enthält nur eine einzige Textzeichenfolge, die der Code anschließend zuweist. Diese Zeichenfolge kann über maximal zwei Zeilen umgebrochen werden. Die Länge der Zeichenfolge sollte daher entsprechend festgelegt werden, um zu vermeiden, dass Text abgeschnitten wird.


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

4. Angeben eines Bilds für die Benachrichtigung

Dieser Code ruft zuerst alle Elemente in der Vorlage mit dem Tagnamen "image" ab. Die TileWide310x150ImageAndText01-Vorlage enthält nur ein Bild. Beachten Sie, dass nicht alle Kachelvorlagen Bilder enthalten. Einige enthalten ausschließlich Text.

Wichtig  Das hier verwendete Bild "redWide.png" dient nur als Beispiel und ist nicht in einem Microsoft Visual Studio-Projekt enthalten. Sie müssen "redWide.png" durch den Namen eines eigenen Bilds ersetzen, das Sie dem Projekt vor dem Senden dieser Benachrichtigung hinzugefügt haben. Andernfalls wird die Benachrichtigung nicht gesendet.

 


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

Die verwendeten Bilder können aus dem App-Paket, dem lokalen Speicher der App oder aus dem Web stammen. Für jede Bildquelle wird eine eigene Version dieses Schritts gezeigt. In einer Kachelbenachrichtigung, die mehrere Bilder enthält, können die Bildelemente jede beliebige Kombination dieser Bildquellenarten verwenden. Bilder, die in Vorlagen verwendet werden, müssen kleiner als 200 KB sein und müssen weniger als 1024 x 1024 Pixel aufweisen. Weitere Informationen finden Sie unter Größe von Kachel- und Popupbildern.

Der folgende Code verwendet ein lokales Bild aus dem App-Paket. Dieser Bildtyp ist in Ihrer Visual Studio-Projektmappendatei enthalten und wird als Teil Ihrer App verpackt. Der Zugriff auf diese Bilder erfolgt mit dem Präfix "ms-appx:///". Aus Gründen der Barrierefreiheit, beispielsweise zur Unterstützung eines Bildschirmleseprogramms, wird außerdem alternativer Text zugewiesen.


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

Der folgende Code verwendet ein lokales Bild aus dem lokalen Speicher der App. Dieser Bildtyp wurde von Ihrer App in ihrem lokalen Speicher gespeichert. Es handelt sich dabei um den von Windows.Storage.ApplicationData.current.localFolder zurückgegebenen Speicherort. Der Zugriff auf diese Bilder erfolgt mithilfe des Präfix "ms-appdata:///local/". Erneut wird aus Gründen der Barrierefreiheit, beispielsweise zur Unterstützung eines Bildschirmleseprogramms, alternativer Text zugewiesen.


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

Der folgende Code verwendet ein Webbild. Der Zugriff auf diese Bilder erfolgt mithilfe des Protokolls "http://", um den Bildpfad anzugeben. Im Manifest Ihrer App muss die internetClient-Funktion deklariert sein, damit Webbilder verwendet werden können.


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

Mit dem optionalen baseUri-Attribut können Sie einen Stammpfad, beispielsweise "https://www.microsoft.com/", angeben, der mit jedem relativen URI (Uniform Resource Identifiers) kombiniert wird, der in den src-Attributen eines Bilds angegeben ist. Dieses Attribut kann entweder für das visual-Element (damit es für die ganze Benachrichtigung gilt) oder für das binding-Element (damit es nur für diese Bindung gilt) festgelegt werden. Wenn baseUri für beide Elemente festgelegt wird, überschreibt der Wert in binding den Wert in visual.

Wenn baseUri auf "https://www.contoso.com/" festgelegt wurde, kann folgende Zeile im Beispielcode:


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

wie folgt verkürzt werden:


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

5. Hinzufügen von Benachrichtigungsbindungen für mehrere Kachelgrößen in der Nutzlast

Der Benutzer kann die Kachelgröße auf der Startseite jederzeit ändern. Für Sie ist es unmöglich, vorab zu wissen, in welchem Zustand die Kachel angezeigt wird, wenn Sie eine Benachrichtigung senden. Ist die Kachelgröße so festgelegt, dass es keine passende Vorlagenbindung in der Benachrichtigung gibt, wird die Benachrichtigung nicht angezeigt. Es wird daher empfohlen, in der Nutzlast immer Versionen für alle Live-Kachelgrößen (mittelgroß, breit, groß) hinzufügen, für die Sie in Ihrem Manifest ein Logobild angegeben haben.

Hinweis  Ab Windows Phone 8.1 werden große Kacheln auf dem Smartphone nicht mehr unterstützt.

In diesem Beispiel wird eine nur aus Text bestehende mittelgroße Benachrichtigung definiert, für die der gleiche Text verwendet wird, der schon bei der breiten Benachrichtigung zum Einsatz kam.

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

Fügen Sie nun die mittelgroße Kachel zur Nutzlast der breiten Kachel hinzu. Rufen Sie das binding-Element ab, das die mittelgroße Kachel in der squareTileXml-Nutzlast definiert. Fügen Sie dieses binding-Element als gleichgeordnetes Element der breiten Kachel hinzu.


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

Die vorangegangenen Schritte führen dazu, dass zwei binding-Elemente unter einem einzelnen visual-Element in der XML-Nutzlast hinzugefügt werden. Das Ergebnis sieht folgendermaßen aus:


<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. Erstellen der Benachrichtigung auf der Grundlage des angegebenen XML-Inhalts


var tileNotification = new notifications.TileNotification(tileXml);

7. Festlegen einer Ablaufzeit für die Benachrichtigung

Standardmäßig laufen lokale Kachel- und Signalbenachrichtigungen nicht ab, und Pushbenachrichtigungen sowie periodische und geplante Benachrichtigungen laufen nach drei Tagen ab. Es hat sich bewährt, besonders für alle lokalen Kachel- und Signalbenachrichtigungen eine Ablaufzeit festzulegen und hierfür einen Zeitraum anzugeben, der bezogen auf die App sinnvoll ist. Der Inhalt der Kachel sollte nur solange angezeigt werden, wie er relevant ist. In diesem Fall läuft die Benachrichtigung in zehn Minuten ab und wird dann von der Kachel entfernt.


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

8. Sendet die Benachrichtigung an die App-Kachel.


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

9. Optional: Löschen der Kachelbenachrichtigung

In diesem Beispiel wird gezeigt, wie eine Kachelbenachrichtigung mit einem lokalen Aufruf gelöscht wird. Falls der Inhalt zeitabhängig ist, sollten Sie eine Ablaufzeit für die Benachrichtigung festlegen, anstatt sie explizit zu löschen. Die folgende Codezeile löscht die aktuelle Benachrichtigung aus der App-Kachel.


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

Bei einer Kachel mit aktivierter Benachrichtigungswarteschlange und Benachrichtigungen in der Warteschlange bewirkt das Aufrufen der clear-Methode, dass die Warteschlange geleert wird.

Sie können eine Benachrichtigung nicht von der Cloud aus löschen. Mit einem lokalen Aufruf der clear-Methode wird die Kachel gelöscht, unabhängig von der Quelle ihrer Benachrichtigungen. Periodische Benachrichtigungen oder Pushbenachrichtigungen können die Kachel jedoch nur mit neuen Inhalten aktualisieren.

Zusammenfassung und nächste Schritte

In dieser Schnellstartanleitung haben Sie neue Inhalte definiert und über eine Benachrichtigung an die App-Kachel gesendet, und diese Inhalte wurden nach zehn Minuten wieder entfernt. Der folgende Code bietet eine Zusammenfassung der oben erläuterten Schritte vom Auswählen einer Vorlage bis hin zum Senden der Benachrichtigung. Es wird ein Bild aus dem App-Paket verwendet.

Um diesen Code in einem eigenen Beispiel zu testen, platzieren Sie ihn in einer Funktion, die von einer Schaltfläche in der Benutzeroberfläche des Beispiels ausgelöst wird. Sie können die Schaltfläche z. B. in der Datei "default.html" hinzufügen. Denken Sie daran, den Namen des Bilds zu ersetzen.


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

Nachdem Sie Ihr erstes Kachelupdate ausgeführt haben, können Sie die Funktionalität Ihrer Kachel erweitern, indem Sie eine Benachrichtigungswarteschlange aktivieren.

In dieser Schnellstartanleitung wurde das Kachelupdate in Form einer lokalen Benachrichtigung gesendet. Zum Übermitteln von Benachrichtigung stehen Ihnen außerdem folgende Methoden zur Verfügung: geplante Benachrichtigung, regelmäßige Benachrichtigung und Pushbenachrichtigung. Weitere Informationen finden Sie unter Zustellen von Benachrichtigungen.

Verwandte Themen

Beispiel für App-Kacheln und Signale

Größe von Kachel- und Popupbildern

Übersicht über Kacheln und Kachelbenachrichtigungen

Richtlinien und Prüfliste für Kacheln

So wird's gemacht: Planen einer Kachelbenachrichtigung

Schnellstart: Einrichten regelmäßiger Benachrichtigungen

Schnellstart: Erstellen einer Standardkachel im Manifest-Editor von Visual Studio

Kachelvorlagenkatalog

XML-Schema für Kacheln

Windows.UI.Notifications