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.

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

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

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

<toast>
    <visual>
        <binding template="ToastGeneric">
            <text>Downloading your weekly playlist...</text>
            <progress
                title="Weekly playlist"
                value="0.6"
                valueStringOverride="15/26 songs"
                status="Downloading..."/>
        </binding>
    </visual>
</toast>

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. Construire du 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 de données 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 l’intégralité du toast garantit également que la notification toast reste dans la même position dans le Centre de notifications et ne se déplace pas vers le haut ou vers le bas. Il serait tout à fait déroutant pour l’utilisateur si le toast a continué à sauter au sommet du Centre de notifications toutes les quelques secondes pendant que la barre de progression a rempli !

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 un autre toast tant que votre opération de progression n’a pas été terminée (comme 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 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 ?

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, 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 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.

Rubriques connexes

• Exemple de code complet sur GitHub
• Documentation sur le contenu des toast