Démarrage rapide : envoi d’une mise à jour de vignette (HTML)

Article
12/11/2015

[ Cet article est destiné aux développeurs de Windows 8.x et Windows Phone 8.x qui créent des applications Windows Runtime. Si vous développez une application pour Windows 10, voir la Documentation ]

Remarque Vous n’utilisez pas JavaScript ? Voir Démarrage rapide : envoi d’une mise à jour de vignette (XAML).

Pour commencer, une vignette est une vignette par défaut, définie dans votre manifeste et affichée lorsque l’application est installée pour la première fois. Une fois l’application installée, vous pouvez modifier le contenu de la vignette via des notifications.Cette rubrique de démarrage rapide vous indique les étapes à suivre pour définir le nouveau contenu d’une vignette, l’envoyer à la vignette et le supprimer lorsqu’il n’est plus utile. La démonstration de ces actions est effectuée via une notification locale, à savoir le type de notification le plus simple à implémenter. Étapes traitées :

Spécification d’un modèle pour la notification
Récupération du contenu XML vide du modèle
Ajout d’un texte à la notification
Ajout d’une image à la notification
Empaquetage de différentes versions d’une notification pour différentes tailles de vignettes dans une même charge utile
Définition d’un délai d’expiration de la notification
Envoi de la mise à jour à la vignette sous forme de notification locale

Voir cette fonctionnalité en action dans le cadre de notre série Fonctionnalités d’application de A à Z: Interface utilisateur des applications du Windows Store de A à Z

Remarque Dans cette rubrique de démarrage rapide, vous allez manipuler le contenu de la notification directement via le modèle DOM (Document Object Model) XML. Une approche facultative est disponible via la bibliothèque NotificationsExtensions, présentant le contenu XML sous forme de propriétés d’objet, y compris IntelliSense. Pour plus d’informations, voir Démarrage rapide : utilisation de la bibliothèque NotificationsExtensions dans votre code. Pour accéder au code de cette rubrique de démarrage rapide exprimé à l’aide de NotificationsExtensions, voir l’exemple de vignettes et de badges d’application.

Prérequis

Conditions préalables à la compréhension de cette rubrique :

Bonnes connaissances des termes et des concepts de vignette et de notification. Pour plus d’informations, voir Vignettes, badges et notifications.
Bonne connaissance du schéma XML de vignette. Pour plus d’informations, voir Schéma des vignettes.
Aptitude à créer une application élémentaire Windows Store en JavaScript à l’aide des API Windows Runtime. Pour plus d’informations, voir Créer votre première application du Windows Store en JavaScript.
Vignette par défaut existante pour votre application, définie dans son manifeste. Pour plus d’informations, voir Démarrage rapide : création d’une vignette par défaut à l’aide de l’éditeur de manifeste de Microsoft Visual Studio.
Bonne connaissance du langage XML et de sa manipulation via les API DOM (Document Object Model).

Instructions

1. Facultatif : Déclarer une variable d’espace de noms

Cette étape permet d’utiliser un nom court à la place du nom complet de l’espace de noms. Elle équivaut à l’instruction « using » dans C# ou « Imports » dans Visual Basic. Elle vous permet de simplifier votre code.

Remarque Il est supposé que cette variable est déclarée pour le reste du code inclus dans la présente rubrique de démarrage rapide.


var notifications = Windows.UI.Notifications;

2. Choisir un modèle pour la vignette et récupérer son contenu XML

Choisissez un modèle adapté à la disposition requise de votre contenu dans le catalogue de modèles fourni par le système. Pour obtenir la liste complète des modèles, voir l’énumération TileTemplateType. Notez qu’un modèle différent peut être utilisé dans le cadre de chaque notification distincte que vous envoyez.

Dans cet exemple, le modèle TileWide310x150ImageAndText01 est utilisé, lequel requiert une image et une chaîne de texte. Voici un exemple :

TileWide310x150ImageAndText01


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

La méthode GetTemplateContent retourne un objet XmlDocument. Le code ci-dessus permet de récupérer le squelette XML suivant dont vous fournissez les détails dans les étapes suivantes via les fonctions DOM (Document Object Model) standard.

Remarque Quand getTemplateContent est appelée sur un système Windows 8, elle retourne un modèle de version 1. Quand cette méthode est appelée sur un système Windows 8.1, elle retourne un modèle de version 2 ou un modèle de version 3 pour les modèles pour Windows Phone uniquement. Si une application spécifie la compatibilité Windows 8 dans son manifeste, cette méthode retourne un modèle de version 1 quelle que soit la version de Windows. Dans cette rubrique, nous allons utiliser un modèle de version 2.


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

3. Approvisionner la notification en contenu sous forme de texte

Le code commence par récupérer tous les éléments du modèle portant le nom de balise « text ». Le modèle TileWide310x150ImageAndText01 contient uniquement une chaîne de texte, que le code assigne alors. La chaîne peut s’étendre sur deux lignes maximum. Vous devez donc définir sa longueur en fonction, afin d’éviter toute troncation.


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

4. Approvisionner la notification en contenu sous forme d’image

Le code commence par récupérer tous les éléments du modèle portant le nom de balise « image ». Le modèle TileWide310x150ImageAndText01 contient une image unique. Notez que les modèles de vignette ne comprennent pas tous des images ; certains n’incluent que du texte.

Important L’image « redWide.png » utilisée ici n’est qu’un exemple. Elle n’est pas incluse dans un projet a Microsoft Visual Studio. Vous devez remplacer « redWide.png » par le nom d’une des images que vous avez ajoutées au projet avant d’essayer d’envoyer cette notification, sinon la notification ne sera pas remise.


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

Vous pouvez utiliser des images provenant du package de l’application, du stockage local de l’application ou du Web. Des versions de cette étape sont fournies pour chaque source d’image. Si une notification par vignette contient plusieurs images, n’importe quelle combinaison de ces types de source d’image peut être utilisée dans le cadre des éléments d’image. Les images utilisées dans les modèles doivent avoir une taille inférieure à 200 Ko et une définition inférieure à 1024 x 1024 pixels. Pour plus d’informations, voir Tailles des images de vignette et de toast.

Le code suivant utilise une image locale provenant du package de l’application. Ce type d’image est inclus dans votre fichier de solution Visual Studio et il est empaqueté dans l’application. Ces images sont accessibles au moyen du préfixe « ms-appx:/// ». En tant que meilleure pratique, nous affectons également un texte de remplacement en option à des fins d’accessibilité (pour des lecteurs d’écran, par exemple).


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

Le code suivant comporte l’utilisation d’une image locale provenant du stockage local de l’application. Ce type d’image est enregistré par votre application au sein de son stockage local. Il s’agit de l’emplacement renvoyé par Windows.Storage.ApplicationData.current.localFolder. Ces images sont accessibles au moyen du préfixe « ms-appdata:///local/ ». Encore une fois, nous affectons également un texte de remplacement en option à des fins d’accessibilité (pour des lecteurs d’écran, par exemple).


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

Le code suivant comporte l’utilisation d’une image Web. Ces images sont accessibles via le protocole « http:// » ou « https:// » dans le cadre de la spécification de leur chemin d’accès. Notez que l’application doit avoir la fonctionnalité internetClient déclarée dans son manifeste pour pouvoir utiliser les images Web.


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

Il est possible d’utiliser l’attribut baseUri en option pour définir un chemin racine, tel que « https://www.microsoft.com/ », combiné à n’importe quels URI (Uniform Resource Identifier) relatifs spécifiés dans n’importe quels attributs src d’image. Vous pouvez définir cet attribut sur l’élément visual (pour une application à l’ensemble de la notification) ou l’élément binding (pour une application à cette liaison). Si vous définissez baseUri sur les deux, la valeur de binding remplace celle de visual.

Si l’attribut baseUri est défini sur « https://www.contoso.com/ », la ligne qui suit dans l’exemple de code :


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

peut être raccourcie de la manière suivante :


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

5. Inclure des liaisons de notification pour plusieurs tailles de vignettes dans la charge utile

L’utilisateur peut à tout moment redimensionner la vignette sur l’écran d’accueil et il n’existe aucun moyen pour vous de savoir dans quel état elle se trouve (petite, moyenne, large ou grande) quand vous envoyez une notification. Si votre vignette est dimensionnée pour qu’il n’existe aucune liaison de modèle correspondante dans votre notification, celle-ci ne s’affiche pas. Il est donc recommandé de toujours inclure des versions de la notification dans votre charge utile pour toutes les tailles de vignettes dynamiques (moyenne, large, grande) pour lesquelles vous avez fourni une image de logo dans votre manifeste.

Remarque À compter de Windows Phone 8.1, les grandes vignettes ne sont pas prises en charge sur le téléphone.

Cet exemple décrit la définition d’une notification de taille moyenne comprenant uniquement du texte provenant de la même chaîne que celle utilisée dans la notification large.

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

Ajoutez ensuite la moyenne vignette à la charge utile de la vignette large. Récupérez l’élément binding qui définit la moyenne vignette dans la charge utile squareTileXml. Ajoutez cet élément binding comme frère de la vignette large.


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

Les étapes précédentes donnent lieu à deux éléments binding sous un élément visual unique dans la charge utile XML, comme illustré ici :


<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. Créer la notification d’après le contenu XML spécifié


var tileNotification = new notifications.TileNotification(tileXml);

7. Définir un délai d’expiration de la notification

Par défaut, les notifications locales par vignette et de badge n’expirent pas, alors que les notifications Push, périodiques et planifiées expirent après trois jours. La définition d’un délai d’expiration significatif pour l’application, notamment sur les notifications locales par vignette et de badge, constitue une meilleure pratique. Le contenu de la vignette ne doit pas être conservé plus longtemps que nécessaire. Dans ce cas, la notification expire et est supprimée de la vignette au bout de 10 minutes.


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

8. Envoyez la notification à la vignette de l’application.


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

9. Facultatif : Effacer la notification par vignette

Cet exemple montre comment effacer une notification par vignette via un appel local. Notez que si le contenu est temporaire, nous vous recommandons de définir un délai d’expiration au niveau de la notification au lieu de l’effacer explicitement. La ligne de code suivante permet d’effacer la notification actuelle de la vignette de l’application.


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

Si la file d’attente est activée pour une vignette et qu’il y a des notifications en file d’attente, l’appel de la méthode clear a pour effet de vider la file d’attente.

Notez que vous ne pouvez pas effacer une notification à partir du cloud. Un appel local à la méthode clear effacera la vignette quelle que soit la source de ses notifications, mais des notifications périodiques ou Push peuvent uniquement mettre à jour la vignette avec un nouveau contenu.

Récapitulatif et étapes suivantes

Dans cette rubrique de démarrage rapide, vous avez défini et envoyé un nouveau contenu à la vignette de votre application via une notification, que vous avez ensuite supprimée au bout de 10 minutes. Le code ci-dessous résume les étapes précédentes, du choix d’un modèle à l’envoi de la notification. Il utilise une image issue du package de l’application.

Pour tester ce code dans l’un de vos exemples, placez-le dans une fonction déclenchée par un bouton dans l’exemple d’interface utilisateur. Vous pouvez par exemple placer le bouton dans le fichier default.html. N’oubliez pas de remplacer le nom de l’image par celui d’une image réelle.


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

Maintenant que vous avez réalisé votre première mise à jour de vignette, vous pouvez développer les fonctionnalités de la vignette en activant une file d’attente de notifications.

Au cours de la présente rubrique de démarrage rapide, la mise à jour de la vignette a été envoyée sous forme de notification locale. Vous pouvez également explorer les autres méthodes de remise de notification : planifiée, périodique et Push. Pour plus d’informations, voir Remise de notifications.