Démarrage rapide : envoi d’une notification toast (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 notification toast (XAML).

Une notification toast est un élément d’interface utilisateur contextuel qui apparaît sur votre écran pour permettre à l’application de communiquer avec l’utilisateur quand il se trouve dans une autre application, sur l’écran d’accueil ou, dans le cas de Windows, sur le Bureau. Ce didacticiel de démarrage rapide vous guide tout au long des étapes de définition et d’affichage du contenu d’une notification toast. 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
Définition d’une durée pour la notification
Spécification de l’audio pour accompagner la notification
Fourniture d’informations contextuelles utilisées lorsque votre application est activée par la notification
Envoi de la notification toast en tant que notification locale

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 notifications toast.

Remarque Lors des tests de la fonctionnalité de code de notification toast à l’aide de Microsoft Visual Studio, vous devez utiliser le paramètre de débogage Ordinateur local ou Ordinateur distant sur un ordinateur Windows x86, x64 ou Windows Runtime. Vous ne pouvez pas utiliser l’option de fonction de débogage Simulateur Visual Studio (votre code serait compilé et exécuté dans le Simulateur, mais le toast n’apparaîtrait pas).

Prérequis

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

Bonnes connaissances des termes et des concepts liés aux notifications toast. Pour plus d’informations, voir Vue d’ensemble des notifications toast.
L’option Compatible toast doit avoir la valeur « true » dans le manifeste de votre application (« Oui » dans l’éditeur de manifeste de Visual Studio) pour permettre l’envoi ou la réception de notifications toast. Pour plus d’informations, voir Comment s’abonner aux notifications toast.
Bonne connaissance du langage XML et de sa manipulation via les API DOM (Document Object Model).
Bonne connaissance du schéma XML des notifications toast. Pour plus d’informations, voir Schéma des notifications toast.
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.

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 notification toast et récupérer son contenu XML

Choisissez un modèle adapté à 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 ToastTemplateType. Notez qu’un modèle différent peut être utilisé dans le cadre de chaque notification distincte que vous envoyez.

Remarque Seule une variante du modèle toastText02 est prise en charge sur Windows Phone 8.1. Elle accepte deux chaînes de texte, la première affichée en gras et toutes deux affichées sur la même ligne. Pour éviter toute concaténation, vous devez donc utiliser une courte chaîne ou deux chaînes très courtes.

Cet exemple, utilisable dans Windows, utilise le modèle toastImageAndText01, qui nécessite une image et une chaîne de texte. Voici un exemple :

ToastImageAndText01


var template = notifications.ToastTemplateType.toastImageAndText01;
var toastXml = notifications.ToastNotificationManager.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 :


<toast>
    <visual>
        <binding template="ToastImageAndText01">
            <image id="1" src=""/>
            <text id="1"></text>
        </binding>
    </visual>
</toast>

3. Approvisionner la notification en contenu sous forme de texte

Cet exemple commence par récupérer tous les éléments du modèle portant le nom de balise « text ». Le modèle toastImageAndText01 contient une seule chaîne de texte attribuée par le code. Cette chaîne peut s’étendre sur trois lignes au maximum. Vous devez donc définir sa longueur en fonction, afin d’éviter toute troncation.

   
var toastTextElements = toastXml.getElementsByTagName("text");
toastTextElements[0].appendChild(toastXml.createTextNode("Hello World!"));

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 ». Un modèle de toast tel que toastImageAndText01 contient au plus une image. Notez que les modèles de toast ne comprennent pas tous des images ; certains n’incluent que du texte.


var toastImageElements = toastXml.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. Les images 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).

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 ce toast.


toastImageElements[0].setAttribute("src", "ms-appx:///images/redWide.png");
toastImageElements[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).


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

Le code suivant comporte l’utilisation d’une image Web. Ces images sont accessibles via le protocole « http:// » dans le cadre de la spécification de leur chemin d’accès. Vous pouvez également utiliser le protocole « https:// ».


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

Il est possible d’utiliser l’attribut facultatif baseUri 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.microsoft.com/ », la ligne qui suit dans l’exemple de code :

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

peut être raccourcie de la manière suivante :

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

5. Facultatif : spécifier une durée du toast

Vous pouvez éventuellement définir la durée d’affichage de votre toast. Vous avez le choix entre deux valeurs : « short » (court) [valeur par défaut] et « long ». Utilisez « long » seulement si votre notification fait partie d’un scénario tel qu’un appel entrant ou un rappel de rendez-vous. Pour plus d’informations, voir Vue d’ensemble des notifications toast.

Remarque Windows Phone 8.1 ne prend pas en charge les durées variables. Tous les toasts ont la même durée. Si cet attribut est inclus dans une notification toast de téléphone, il est ignoré.

Remarque La durée par défaut est « short », par conséquent vous ajoutez généralement cet attribut uniquement pour définir la durée sur « long ».


var toastNode = toastXml.selectSingleNode("/toast");
toastNode.setAttribute("duration", "long");

6. Facultatif : spécifier l’audio du toast

Pour en savoir plus sur les options audio des toasts, voir Catalogue des options audio de toast.

Par défaut, Windows émet un son bref lorsque le toast est affiché. Vous pouvez éventuellement spécifier un son différent à partir d’un ensemble de sons fournis par le système, ou aucun son du tout. Sur Windows Phone 8.1, vous pouvez spécifier un son personnalisé. Pour plus d’informations, voir Catalogue d’options audio de toast.

Un modèle extrait par l’intermédiaire de getTemplateContent ne contient pas d’élément audio. Vous devez donc en définir et en ajouter un à votre charge utile XML. Le fichier audio est spécifié à l’aide du préfixe « ms-winsoundevent: » ou, sur Windows Phone 8.1, par un chemin d’accès qui utilise le préfixe « ms-appx:/// » ou « ms-appdata:/// ». Cet exemple crée un élément audio et sélectionne l’élément toast qui sera son parent.


var toastNode = toastXml.selectSingleNode("/toast");                        
var audio = toastXml.createElement("audio");

Cet exemple spécifie un son autre que celui par défaut.

audio.setAttribute("src", "ms-winsoundevent:Notification.IM");

Cet exemple spécifie qu’aucun son ne doit être émis.

audio.setAttribute("silent", "true");

Dans le cas d’une notification toast de longue durée, le son peut être émis en boucle au lieu d’être émis une seule fois. Notez qu’émettre un son en boucle n’est valide que pour les notifications toast de longue durée. Les sons spécifiques pouvant être utilisés en boucle sont inclus dans l’ensemble de sons fournis par le système. Cet exemple spécifie un son à émettre en boucle.

Remarque Comme il ne prend pas en charge les toasts de longue durée, Windows Phone 8.1 ne prend pas en charge la lecture en boucle de séquences audio.


toastNode.setAttribute("duration", "long");

var audio = toastXml.createElement("audio");
audio.setAttribute("src", "ms-winsoundevent:Notification.Looping.Alarm");
audio.setAttribute("loop", "true");

Une fois que vous avez défini votre élément audio, vous devez le joindre à la charge utile XML de la notification toast en tant qu’enfant de l’élément toast, comme illustré ici.

toastNode.appendChild(audio);

7. Spécifier les paramètres de lancement des applications

Lorsque l’utilisateur clique sur votre notification toast, votre application devrait se lancer, avec un affichage lié au contenu de la notification. Pour ce faire, utilisez l’attribut launch de l’élément de toast, qui fournit une chaîne qui est transmise du toast à l’application lorsque l’application est lancée par l’intermédiaire du toast. Cette chaîne n’a aucune chaîne spécifique et est définie par l’application. Votre application doit rechercher cette chaîne comme argument chaque fois qu’elle est activée car son affichage ou l’opération effectuée en dépend.


toastXml.selectSingleNode("/toast").setAttribute("launch", '{"type":"toast","param1":"12345","param2":"67890"}');

Remarque Dans Windows Phone Silverlight 8.1, la valeur de la chaîne de lancement est ajoutée à l’URI de votre page de démarrage par défaut. Par exemple, si vous fournissez la chaîne de lancement « ?conversation=71 », il en résulte un URI comme /MainPage.xaml?conversation=71. La chaîne de lancement doit donc être également une chaîne de requête valide, faute de quoi une exception est levée.

8. Créez la notification toast en fonction du contenu XML spécifié.

var toast = new notifications.ToastNotification(toastXml);

9. Envoyez votre notification toast.

 
 var toastNotifier = notifications.ToastNotificationManager.createToastNotifier();
 toastNotifier.show(toast);

Remarque Dans Windows Phone Silverlight 8.1, aucun toast n’est affiché si l’application de premier plan active est l’appelant de la méthode ToastNotifier.Show. Dans ce cas, un toast doit être principalement utilisé par un agent d’arrière-plan.

Remarque: La couleur d’arrière-plan appliquée à votre notification toast est celle déclarée pour la vignette de votre application dans le manifeste de l’application. Pour plus d’informations, voir Démarrage rapide : création d’une vignette par défaut à l’aide de l’éditeur de manifeste de Visual Studio.

Récapitulatif et étapes suivantes

Dans cette rubrique de démarrage rapide, vous avez envoyé votre notification toast locale à l’utilisateur.

La notification toast a été envoyée en tant que notification locale (type de notification le plus simple à implémenter), vous permettant de voir rapidement les résultats. Ensuite, vous devez explorer les autres méthodes de remise de notification toast : planifiée et Push. Pour plus d’informations, voir Remise de notifications.