Barre de progression toast et liaison de données

L’utilisation d’une barre de progression dans votre notification toast vous permet de transmettre les status d’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 cibler le SDK 15063 et exécuter la build 15063 ou ultérieure pour utiliser les barres de progression sur les toasts. Vous devez utiliser la version 1.4.0 ou ultérieure de la bibliothèque NuGet des notifications de la communauté UWP pour construire la barre de progression dans le contenu de votre toast.

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

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

Notes

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’image ci-dessous montre une barre de progression déterminé avec toutes ses propriétés correspondantes étiquetées.

Toast avec des propriétés de barre de progression étiquetées
Propriété Type Obligatoire Description
Titre string ou BindableString false Obtient ou définit une chaîne de titre facultative. Prend en charge la liaison de données.
Valeur double ou AdaptiveProgressBarValue ou BindableProgressBarValue false 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 string ou BindableString false 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 le cas, quelque chose comme « 70 % » s’affiche.
État string ou BindableString true Obtient ou définit une chaîne status (obligatoire), qui s’affiche sous la barre de progression à gauche. Cette chaîne doit refléter la status 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 « active ». 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. Construire un contenu toast qui utilise des champs liés aux données
  2. Affecter une balise (et é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 toast Data .

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 l’intégralité de la notification toast garantit également que la notification toast reste à la même position dans le Centre de notifications et ne se déplace pas vers le haut ou vers le bas. Il serait assez déroutant pour l’utilisateur si le toast continuait à sauter en haut du centre de notifications toutes les quelques secondes pendant que la barre de progression se remplissait!

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 est introuvable (ce qui signifie que l’utilisateur a probablement ignoré votre notification et que vous devez arrêter d’y envoyer des mises à jour). Nous vous déconseillons de faire un autre toast tant que votre opération de progression n’est pas terminée (par exemple, lorsque le téléchargement est terminé).

É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 les mêmes étiquette et 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 complètement modifier tout le contenu/la 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ît en tant que fenêtre contextuelle Peut réapparaître en tant que fenêtre contextuelle toast si vous laissez SuppressPopup défini sur false (ou défini sur true pour l’envoyer en mode silencieux au Centre de notifications) Ne réapparaît pas sous la forme d’une fenêtre contextuelle ; Les données du toast sont mises à jour en mode silencieux dans le Centre de notifications
Utilisateur ignoré Que l’utilisateur ait ou non ignoré votre notification précédente, votre toast de remplacement sera toujours envoyé Si l’utilisateur a ignoré votre toast, la mise à jour de toast échoue

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

  • Informations qui changent fréquemment dans un court laps de temps et ne nécessitent pas d’être portées au premier plan de l’attention de l’utilisateur
  • Modifications subtiles apportées à votre contenu toast, comme 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 l’étape finale, car...

  • Votre notification finale a probablement des modifications radicales de disposition, 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 se soucie pas de la regarder télécharger, mais souhaite toujours être averti avec un toast contextuel lorsque l’opération est terminée