Barre de progression Toast et liaison de donnéesToast progress bar and data binding

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 de l’exercice, et bien plus encore.Using a progress bar inside your toast notification allows you to convey the status of long-running operations to the user, like downloads, video rendering, exercise goals, and more.

Important

Nécessite les créateurs Update et 1.4.0 de la bibliothèque de notifications: vous devez cibler le kit de développement logiciel 15063 et exécuter la version 15063 ou une version ultérieure pour utiliser les barres de progression sur les toasts.Requires Creators Update and 1.4.0 of Notifications library: You must target SDK 15063 and be running build 15063 or higher to use progress bars on toasts. Vous devez utiliser la version 1.4.0 ou supérieure de la bibliothèque du kit de développement de la série UWP notifications pour construire la barre de progression dans le contenu de votre toast.You must use version 1.4.0 or higher of the UWP Community Toolkit Notifications NuGet library to construct the progress bar in your toast's content.

Une barre de progression à l’intérieur d’un toast peut être « indéterminée » (aucune valeur spécifique, des points animés indiquent qu’une opération se produit) ou « se terminer » (un pourcentage spécifique de la barre est rempli, comme 60%).A progress bar inside a toast can either be "indeterminate" (no specific value, animated dots indicate an operation is occurring) or "determinate" (a specific percent of the bar is filled, like 60%).

API importantes: classe NotificationData, méthode ToastNotifier. Update, ToastNotification, classeImportant APIs: NotificationData class, ToastNotifier.Update method, ToastNotification class

Notes

Seul Desktop prend en charge les barres de progression dans les notifications Toast.Only Desktop supports progress bars in toast notifications. Sur les autres appareils, la barre de progression sera supprimée de votre notification.On other devices, the progress bar will be dropped from your notification.

L’image ci-dessous montre une barre de progression qui se termine avec toutes les propriétés correspondantes étiquetées.The picture below shows a determinate progress bar with all of its corresponding properties labeled.

Toast with progress bar properties labeled
PropriétéProperty TypeType ObligatoireRequired DescriptionDescription
TitreTitle chaîne ou BindableStringstring or BindableString falsefalse Obtient ou définit une chaîne de titre facultative.Gets or sets an optional title string. Prend en charge la liaison de données.Supports data binding.
ValeurValue double ou AdaptiveProgressBarValue ou BindableProgressBarValuedouble or AdaptiveProgressBarValue or BindableProgressBarValue falsefalse Obtient ou définit la valeur de la barre de progression.Gets or sets the value of the progress bar. Prend en charge la liaison de données.Supports data binding. La valeur par défaut est 0.Defaults to 0. Peut être une valeur double comprise entre 0,0 et 1,0, AdaptiveProgressBarValue.Indeterminate ou new BindableProgressBarValue("myProgressValue") .Can either be a double between 0.0 and 1.0, AdaptiveProgressBarValue.Indeterminate, or new BindableProgressBarValue("myProgressValue").
ValueStringOverrideValueStringOverride chaîne ou BindableStringstring or BindableString falsefalse Obtient ou définit une chaîne facultative à afficher à la place de la chaîne de pourcentage par défaut.Gets or sets an optional string to be displayed instead of the default percentage string. Si cette valeur n’est pas fournie, un nom similaire à « 70% » s’affiche.If this isn't provided, something like "70%" will be displayed.
ÉtatStatus chaîne ou BindableStringstring or BindableString truetrue Obtient ou définit une chaîne d’État (obligatoire), qui s’affiche sous la barre de progression sur la gauche.Gets or sets a status string (required), which is displayed underneath the progress bar on the left. Cette chaîne doit refléter l’état de l’opération, par exemple « téléchargement... » ou « installation... »This string should reflect the status of the operation, like "Downloading..." or "Installing..."

Voici comment générer la notification illustrée ci-dessus...Here's how you would generate the notification seen above...

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’elles soient réellement « actives ».However, you'll need to dynamically update the values of the progress bar for it to actually be "live". Pour ce faire, vous pouvez utiliser la liaison de données pour mettre à jour le Toast.This can be done by using data binding to update the toast.

Utilisation de la liaison de données pour mettre à jour un toastUsing data binding to update a toast

L’utilisation de la liaison de données implique les étapes suivantes...Using data binding involves the following steps...

  1. Construire un contenu Toast qui utilise des champs liés aux donnéesConstruct toast content that utilizes data bound fields
  2. Affecter une balise (et éventuellement un Groupe) à votre ToastNotificationAssign a Tag (and optionally a Group) to your ToastNotification
  3. Définir vos valeurs de données initiales sur votre ToastNotificationDefine your initial Data values on your ToastNotification
  4. Envoyer le ToastSend the toast
  5. Utiliser la balise et le groupe pour mettre à jour les valeurs de données avec les nouvelles valeursUtilize Tag and Group to update the Data values with new values

L’extrait de code suivant montre les étapes 1-4.The following code snippet shows steps 1-4. L’extrait de code suivant indique comment mettre à jour les valeurs des données de Toast.The next snippet will show how to update the toast Data values.

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 reconstruire l’intégralité de la charge du Toast.Then, when you want to change your Data values, use the Update method to provide the new data without re-constructing the entire toast payload.

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 de mise à jour au lieu de remplacer l’intégralité du Toast garantit également que la notification Toast reste à la même position dans le centre de maintenance et ne se déplace pas vers le haut ou vers le haut.Using the Update method rather than replacing the entire toast also ensures that the toast notification stays in the same position in Action Center and doesn't move up or down. Il serait tout à fait confus pour l’utilisateur si le Toast s’est maintenu vers le haut du centre de maintenance toutes les quelques secondes alors que la barre de progression était pleine.It would be quite confusing to the user if the toast kept jumping to the top of Action Center every few seconds while the progress bar filled!

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 rejeté votre notification et vous devez arrêter d’envoyer des mises à jour à celle-ci).The Update method returns an enum, NotificationUpdateResult, which lets you know whether the update succeeded or whether the notification couldn't be found (which means the user has likely dismissed your notification and you should stop sending updates to it). Nous vous déconseillons d’utiliser un autre Toast jusqu’à ce que votre opération de progression soit terminée (comme lorsque le téléchargement est terminé).We do not recommend popping another toast until your progress operation has been completed (like when the download completes).

Éléments qui prennent en charge la liaison de donnéesElements that support data binding

Les éléments suivants dans les notifications Toast prennent en charge la liaison de donnéesThe following elements in toast notifications support data binding

  • Toutes les propriétés sur AdaptiveProgressAll properties on AdaptiveProgress
  • Propriété Text sur les éléments AdaptiveText de niveau supérieurThe Text property on the top-level AdaptiveText elements

Mettre à jour ou remplacer une notificationUpdate or replace a notification

Depuis Windows 10, vous pouviez toujours remplacer une notification en envoyant un nouveau Toast avec la même balise et le même groupe.Since Windows 10, you could always replace a notification by sending a new toast with the same Tag and Group. Alors, quelle est la différence entre le remplacement du Toast et la mise à jour des données du Toast ?So what's the difference between replacing the toast and updating the toast's data?

ChangementReplacing Mise à jourUpdating
Position dans le centre de maintenancePosition in Action Center Déplace la notification vers le haut du centre de maintenance.Moves the notification to the top of Action Center. Laisse la notification en place dans le centre de maintenance.Leaves the notification in place within Action Center.
Modification du contenuModifying content Peut modifier complètement tout le contenu/la mise en page du ToastCan completely change all content/layout of the toast Ne peut modifier que les propriétés qui prennent en charge la liaison de données (barre de progression et texte de niveau supérieur)Can only change properties that support data binding (progress bar and top-level text)
Réapparaît comme PopupReappearing as popup Peut réapparaître sous la forme d’une fenêtre contextuelle Toast si vous laissez SuppressPopup défini sur false (ou sur true pour l’envoyer silencieusement au centre de maintenance)Can reappear as a toast popup if you leave SuppressPopup set to false (or set to true to silently send it to Action Center) Ne réapparaît pas sous forme de fenêtre contextuelle. les données du Toast sont mises à jour silencieusement dans le centre de notificationsWon't reappear as a popup; the toast's data is silently updated within Action Center
Utilisateur rejetéUser dismissed Que l’utilisateur ait rejeté votre notification précédente, votre toast de remplacement est toujours envoyéRegardless of whether user dismissed your previous notification, your replacement toast will always be sent Si l’utilisateur a fermé votre toast, la mise à jour Toast échoueIf the user dismissed your toast, the toast update will fail

En général, la mise à jour est utile pour...In general, updating is useful for...

  • Des informations qui changent fréquemment sur une période de temps et qui ne nécessitent pas d’être placées au début de l’attention de l’utilisateurInformation that frequently changes in a short period of time and doesn't require being brought to the front of the user's attention
  • Modifications subtiles apportées à votre contenu Toast, telles que la modification de 50% en 65%Subtle changes to your toast content, like changing 50% to 65%

Souvent, une fois que la séquence des mises à jour est terminée (comme le fichier a été téléchargé), nous vous recommandons de remplacer pour la dernière étape, car...Often times, after your sequence of updates have completed (like the file has been downloaded), we recommend replacing for the final step, because...

  • Votre dernière notification a probablement des modifications de disposition drastiques, telles que la suppression de la barre de progression, l’ajout de nouveaux boutons, etc.Your final notification likely has drastic layout changes, like removal of the progress bar, addition of new buttons, etc
  • L’utilisateur a peut-être ignoré votre notification de progression en attente, car il ne se soucie pas de regarder le téléchargement, mais souhaite toujours être notifié avec un toast de la fenêtre contextuelle lorsque l’opération est terminée.The user might have dismissed your pending progress notification since they don't care about watching it download, but still want to be notified with a popup toast when the operation is completed