Toast-förloppsindikator och databindning

Med hjälp av ett förloppsfält i popup-meddelandet kan du förmedla statusen för långvariga åtgärder till användaren, till exempel nedladdningar, videorendering, träningsmål med mera.

Ett förloppsfält i ett toast-meddelande kan antingen vara "obestämd" (inget specifikt värde, animerade punkter indikerar att en åtgärd inträffar) eller "bestämd" (en viss procent av fältet fylls, till exempel 60%).

Viktiga API:er: NotificationData-klass, ToastNotifier.Update-metod, ToastNotification-klass

Bilden nedan visar en fast förloppsindikator med alla motsvarande egenskaper märkta.

Så här genererar du meddelandet som visas ovan...

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>

Du måste dock dynamiskt uppdatera värdena i förloppsindikatorn så att den faktiskt är "live". Detta kan göras med hjälp av databindning för att uppdatera toast-meddelandet.

Använda databindning för att uppdatera ett popup-meddelande

Användning av databindning omfattar följande steg...

1. Skapa toastmeddelande som använder databundna fält
2. Tilldela en -tagg (och eventuellt en grupp) till din ToastNotification-
3. Definiera dina initiala Data-värden i din ToastNotification-
4. Skicka meddelande-toast
5. Använda tagg och grupp för att uppdatera datavärdena med nya värden

Följande kodfragment visar steg 1–4. Nästa kodsnutt visar hur du ska uppdatera notismeddelande Data värden.

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

När du sedan vill ändra värdena för Data använder du Update-metoden för att ge nya data utan att återskapa hela toast-nyttolasten.

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

Om du använder metoden Uppdatering i stället för att ersätta hela toast-meddelandet ser du också till att toast-meddelandet förblir i samma position i åtgärdscentret och inte flyttas uppåt eller nedåt. Det skulle vara ganska förvirrande för användaren om popup-brödet fortsatte att hoppa till toppen av Action Center med några sekunders mellanrum medan förloppsindikatorn fylldes!

Metoden Update returnerar en uppräkningstyp, NotificationUpdateResult, som informerar dig om uppdateringen lyckades eller om meddelandet inte kunde hittas (vilket innebär att användaren sannolikt har stängt meddelandet och att du bör sluta skicka uppdateringar till det). Vi rekommenderar inte att du poppar ett nytt popup-meddelande förrän förloppsåtgärden har slutförts (till exempel när nedladdningen är klar).

Element som stöder databindning

Följande element i toast-aviseringar stöder databindning

• Alla egenskaper för AdaptiveProgress
• Egenskapen Text på den översta nivån AdaptiveText--element

Uppdatera eller ersätta ett meddelande

Eftersom Windows 10 kan du alltid ersätta ett meddelande genom att skicka ett nytt popup-meddelande med samma Tag och Group. Så vad är skillnaden mellan att ersätta toasten och uppdatera toastens data?

I allmänhet är att uppdatera användbart för...

• Information som ofta ändras på kort tid och som inte behöver vara i fokus för användarens uppmärksamhet
• Diskreta ändringar i toastinnehållet, som att ändra 50% till 65%

När din uppdateringssekvens har slutförts (till exempel att filen har laddats ned) rekommenderar vi ofta att du ersätter för det sista steget, eftersom...

• Ditt slutliga meddelande har troligen drastiska layoutändringar, till exempel borttagning av förloppsindikatorn, tillägg av nya knappar osv.
• Användaren kan ha avvisat det väntande förloppsmeddelandet eftersom de inte bryr sig om att titta på nedladdningen, men ändå vill få ett meddelande med ett popup-fönster när åtgärden har slutförts

Related topics

• fullständigt kodexempel på GitHub
• Dokumentation av Toast-meddelandeinnehåll