Partager via

Barre de progression toast et liaison de données

L’utilisation d’une barre de progression à l’intérieur de votre notification toast vous permet de transmettre l’état des opérations de longue durée à l’utilisateur, comme les téléchargements, le rendu vidéo, les objectifs d’exercice, etc.

Important

Nécessite Creators Update et la bibliothèque de notifications 1.4.0 : vous devez viser le SDK 15063 et exécuter la version 15063 ou une version ultérieure pour utiliser des barres de progression sur les notifications toast. Vous devez utiliser la version 1.4.0 ou ultérieure de la bibliothèque NuGet UWP Community Toolkit Notifications pour construire la barre de progression dans le contenu de votre notification toast.

Une barre de progression à l’intérieur d’un toast peut être « indéterminée » (aucune valeur spécifique, points animés indiquent qu’une opération se produit) ou « détermina » (un pourcentage spécifique de la barre est rempli, comme 60%).

API importantes : classe NotificationData, méthode ToastNotifier.Update, classe ToastNotification

Remarque

Seul Desktop prend en charge les barres de progression dans les notifications toast. Sur d’autres appareils, la barre de progression est supprimée de votre notification.

L’illustration ci-dessous montre une barre de progression déterminée avec toutes ses propriétés correspondantes étiquetées.

Toast avec propriétés de la barre de progression étiquetées
Propriété Catégorie Obligatoire Descriptif
Titre chaîne ou BindableString faux Obtient ou définit une chaîne de titre facultative. Prend en charge la liaison de données.
Valeur double ou AdaptiveProgressBarValue ou BindableProgressBarValue faux Obtient ou définit la valeur de la barre de progression. Prend en charge la liaison de données. La valeur par défaut est 0. Peut être un double compris entre 0,0 et 1.0, AdaptiveProgressBarValue.Indeterminateou new BindableProgressBarValue("myProgressValue").
ValueStringOverride chaîne ou BindableString faux Obtient ou définit une chaîne facultative à afficher au lieu de la chaîne de pourcentage par défaut. Si ce n’est pas fourni, quelque chose comme « 70%» s’affiche.
État chaîne ou BindableString vrai Obtient ou définit une chaîne d’état (obligatoire), qui s’affiche sous la barre de progression à gauche. Cette chaîne doit refléter l’état de l’opération, comme « Téléchargement... » ou « Installation... »

Voici comment générer la notification ci-dessus...

new ToastContentBuilder()
    .AddText("Downloading your weekly playlist...")
    .AddVisualChild(new AdaptiveProgressBar()
    {
        Title = "Weekly playlist",
        Value = 0.6,
        ValueStringOverride = "15/26 songs",
        Status = "Downloading..."
    });

Toutefois, vous devez mettre à jour dynamiquement les valeurs de la barre de progression pour qu’elle soit réellement « dynamique ». Pour ce faire, utilisez la liaison de données pour mettre à jour le toast.

Utilisation de la liaison de données pour mettre à jour un toast

L’utilisation de la liaison de données implique les étapes suivantes...

  1. Créer un contenu de notification toast qui utilise des champs de données liés
  2. Affecter une balise (ou éventuellement un groupe) à votre ToastNotification
  3. Définir vos valeurs de données initiales sur votre ToastNotification
  4. Envoyer le toast
  5. Utiliser l’étiquette et le groupe pour mettre à jour les valeurs de données avec de nouvelles valeurs

L’extrait de code suivant montre les étapes 1 à 4. L’extrait de code suivant montre comment mettre à jour les valeurs de données du toast.

using Windows.UI.Notifications;
using Microsoft.Toolkit.Uwp.Notifications;
 
public void SendUpdatableToastWithProgress()
{
    // Define a tag (and optionally a group) to uniquely identify the notification, in order update the notification data later;
    string tag = "weekly-playlist";
    string group = "downloads";
 
    // Construct the toast content with data bound fields
    var content = new ToastContentBuilder()
        .AddText("Downloading your weekly playlist...")
        .AddVisualChild(new AdaptiveProgressBar()
        {
            Title = "Weekly playlist",
            Value = new BindableProgressBarValue("progressValue"),
            ValueStringOverride = new BindableString("progressValueString"),
            Status = new BindableString("progressStatus")
        })
        .GetToastContent();
 
    // Generate the toast notification
    var toast = new ToastNotification(content.GetXml());
 
    // Assign the tag and group
    toast.Tag = tag;
    toast.Group = group;
 
    // Assign initial NotificationData values
    // Values must be of type string
    toast.Data = new NotificationData();
    toast.Data.Values["progressValue"] = "0.6";
    toast.Data.Values["progressValueString"] = "15/26 songs";
    toast.Data.Values["progressStatus"] = "Downloading...";
 
    // Provide sequence number to prevent out-of-order updates, or assign 0 to indicate "always update"
    toast.Data.SequenceNumber = 1;
 
    // Show the toast notification to the user
    ToastNotificationManager.CreateToastNotifier().Show(toast);
}

Ensuite, lorsque vous souhaitez modifier vos valeurs de données , utilisez la méthode Update pour fournir les nouvelles données sans recréer la charge utile toast entière.

using Windows.UI.Notifications;
 
public void UpdateProgress()
{
    // Construct a NotificationData object;
    string tag = "weekly-playlist";
    string group = "downloads";
 
    // Create NotificationData and make sure the sequence number is incremented
    // since last update, or assign 0 for updating regardless of order
    var data = new NotificationData
    {
        SequenceNumber = 2
    };

    // Assign new values
    // Note that you only need to assign values that changed. In this example
    // we don't assign progressStatus since we don't need to change it
    data.Values["progressValue"] = "0.7";
    data.Values["progressValueString"] = "18/26 songs";

    // Update the existing notification's data by using tag/group
    ToastNotificationManager.CreateToastNotifier().Update(data, tag, group);
}

L’utilisation de la méthode Update plutôt que de remplacer le toast en entier garantit aussi que la notification toast reste à la même position dans le Centre de notifications et ne se déplace ni vers le haut ni vers le bas. Il serait tout à fait déroutant pour l’utilisateur si le toast continue de sauter au sommet du Centre d’Action toutes les quelques secondes pendant que la barre de progression se remplit.

La méthode Update retourne une énumération, NotificationUpdateResult, qui vous permet de savoir si la mise à jour a réussi ou si la notification n’a pas pu être trouvée (ce qui signifie que l’utilisateur a probablement ignoré votre notification et que vous devez arrêter d’envoyer des mises à jour à celui-ci). Nous vous déconseillons d'afficher une nouvelle notification tant que votre opération n'est pas terminée (comme lorsque le téléchargement est achevé).

Éléments qui prennent en charge la liaison de données

Les éléments suivants dans les notifications toast prennent en charge la liaison de données

  • Toutes les propriétés sur AdaptiveProgress
  • Propriété Text sur les éléments AdaptiveText de niveau supérieur

Mettre à jour ou remplacer une notification

Depuis Windows 10, vous pouvez toujours remplacer une notification en envoyant un nouveau toast avec la même balise et le même groupe. Quelle est la différence entre le remplacement du toast et la mise à jour des données du toast ?

Remplacement Mise à jour
Position dans le Centre de notifications Déplace la notification en haut du Centre de notifications. Laisse la notification en place dans le Centre de notifications.
Modification du contenu Peut modifier complètement tout le contenu/disposition du toast Peut uniquement modifier les propriétés qui prennent en charge la liaison de données (barre de progression et texte de niveau supérieur)
Réapparaître en tant que fenêtre contextuelle Peut réapparaître sous forme de fenêtre contextuelle de type toast si vous laissez SuppressPopup défini sur false (ou sur vrai pour l’envoyer silencieusement au centre de notifications) Ne réapparaît pas en tant que fenêtre contextuelle ; les données de la notification toast sont mises à jour de manière silencieuse dans le Centre de notifications.
Utilisateur rejeté Quel que soit l’utilisateur qui a ignoré votre notification précédente, votre toast de remplacement sera toujours envoyé Si l’utilisateur a ignoré votre toast, la mise à jour toast échoue

En général, la mise à jour est utile pour...

  • Informations qui changent fréquemment dans une courte période et ne nécessitent pas d’être portées à l’avant de l’attention de l’utilisateur
  • Modifications subtiles apportées à votre contenu toast, telles que la modification de 50% à 65%

Souvent, une fois votre séquence de mises à jour terminée (comme le fichier a été téléchargé), nous vous recommandons de remplacer pour la dernière étape, car...

  • Votre notification finale a probablement des modifications de disposition radicales, comme la suppression de la barre de progression, l’ajout de nouveaux boutons, etc.
  • L’utilisateur a peut-être ignoré votre notification de progression en attente, car il ne s’intéresse pas à son téléchargement, mais il souhaite toujours être averti avec un toast contextuel lorsque l’opération est terminée.