Statusanzeige für Popup und DatenbindungToast progress bar and data binding

Durch die Verwendung einer Statusanzeige in der Popup Benachrichtigung können Sie den Status von Vorgängen mit langer Ausführungsdauer an den Benutzer weitergeben, z. b. Downloads, Video Rendering, Testziele und vieles mehr.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.

Wichtig

Erfordert Creators Update und 1.4.0 der Benachrichtigungs Bibliothek: Sie müssen das SDK 15063 als Ziel verwenden und Build 15063 oder höher ausführen, um Status anzeigen in den Toasts zu verwenden.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. Um die Statusanzeige im Inhalt Ihres Popups zu erstellen, müssen Sie die Version 1.4.0 oder eine höhere Version der nuget-Bibliothek der UWP Community Toolkit-Benachrichtigungen verwenden.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.

Eine Statusanzeige in einem Popup kann entweder "unbestimmt" (kein spezifischer Wert, animierte Punkte zeigen, dass ein Vorgang auftritt) oder "determinate" lauten (ein bestimmter Prozentsatz des Balkens wird aufgefüllt, z. b. 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%).

Wichtige APIs: notificationdata-Klasse, " tastnotifier. Update"-Methode, " tastnotification "-KlasseImportant APIs: NotificationData class, ToastNotifier.Update method, ToastNotification class

Hinweis

Nur der Desktop unterstützt Status leisten in Popup Benachrichtigungen.Only Desktop supports progress bars in toast notifications. Auf anderen Geräten wird die Statusanzeige aus der Benachrichtigung gelöscht.On other devices, the progress bar will be dropped from your notification.

Die folgende Abbildung zeigt eine bestimmte-Statusanzeige mit allen zugehörigen Eigenschaften mit der Bezeichnung.The picture below shows a determinate progress bar with all of its corresponding properties labeled.

Toast with progress bar properties labeled
EigenschaftProperty typeType ErforderlichRequired BESCHREIBUNGDescription
TitelTitle String oder bindablestringstring or BindableString falsefalse Ruft eine optionale Zeichenfolge ab oder legt Sie fest.Gets or sets an optional title string. Unterstützt die Datenbindung.Supports data binding.
WertValue Double oder adaptiveprogressbarvalue oder bindableprogressbarvaluedouble or AdaptiveProgressBarValue or BindableProgressBarValue falsefalse Ruft den Wert der Statusanzeige ab oder legt ihn fest.Gets or sets the value of the progress bar. Unterstützt die Datenbindung.Supports data binding. Der Standardwert ist 0.Defaults to 0. Kann entweder ein Double zwischen 0,0 und 1,0, AdaptiveProgressBarValue.Indeterminate oder sein new BindableProgressBarValue("myProgressValue") .Can either be a double between 0.0 and 1.0, AdaptiveProgressBarValue.Indeterminate, or new BindableProgressBarValue("myProgressValue").
ValuestringoverrideValueStringOverride String oder bindablestringstring or BindableString falsefalse Ruft eine optionale Zeichenfolge ab, die anstelle der standardmäßigen Prozent Zeichenfolge angezeigt wird, oder legt diese festGets or sets an optional string to be displayed instead of the default percentage string. Wenn dies nicht angegeben wird, wird etwa "70%" angezeigt.If this isn't provided, something like "70%" will be displayed.
StatusStatus String oder bindablestringstring or BindableString truetrue Ruft eine Status Zeichenfolge (erforderlich) ab, die unterhalb der Statusleiste auf der linken Seite angezeigt wird, oder legt Sie fest.Gets or sets a status string (required), which is displayed underneath the progress bar on the left. Diese Zeichenfolge sollte den Status des Vorgangs widerspiegeln, wie z. b. "herunterladen..." oder "wird installiert..."This string should reflect the status of the operation, like "Downloading..." or "Installing..."

Hier sehen Sie, wie Sie die oben gezeigte Benachrichtigung generieren...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..."
    });

Allerdings müssen Sie die Werte der Statusanzeige dynamisch aktualisieren, damit Sie tatsächlich "Live" ist.However, you'll need to dynamically update the values of the progress bar for it to actually be "live". Dies kann mithilfe der Datenbindung zum Aktualisieren des Popups erreicht werden.This can be done by using data binding to update the toast.

Verwenden der Datenbindung zum Aktualisieren eines PopupsUsing data binding to update a toast

Die Verwendung der Datenbindung umfasst die folgenden Schritte...Using data binding involves the following steps...

  1. Erstellen von Popup Inhalten, die Daten gebundene Felder verwendetConstruct toast content that utilizes data bound fields
  2. Zuweisen eines Tags (und optional einer Gruppe) zu Ihrer Anmelde BenachrichtigungAssign a Tag (and optionally a Group) to your ToastNotification
  3. Definieren Sie Ihre anfänglichen Daten Werte in Ihrer Benachrichtigung .Define your initial Data values on your ToastNotification
  4. Toast sendenSend the toast
  5. Verwenden von Tag und Gruppe zum Aktualisieren der Daten Werte mit neuen WertenUtilize Tag and Group to update the Data values with new values

Der folgende Code Ausschnitt zeigt die Schritte 1-4.The following code snippet shows steps 1-4. Der nächste Code Ausschnitt zeigt, wie die Popup Daten Werte aktualisiert werden.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);
}

Wenn Sie dann die Daten Werte ändern möchten, verwenden Sie die Update -Methode, um die neuen Daten bereitzustellen, ohne die gesamte Toast Nutzlast neu zu erstellen.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);
}

Wenn Sie die Update -Methode verwenden, anstatt den gesamten Toast zu ersetzen, wird auch sichergestellt, dass die Popup Benachrichtigung an der gleichen Position im Aktions Center bleibt und nicht nach oben oder unten verschoben wird.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. Es wäre ziemlich verwirrend für den Benutzer, wenn der Toast alle paar Sekunden auf den Anfang des Aktions Centers springt, während die Statusanzeige gefüllt ist.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!

Die Update -Methode gibt eine Enum- notificationupdateresultzurück, mit der Sie feststellen können, ob die Aktualisierung erfolgreich war oder ob die Benachrichtigung nicht gefunden werden konnte (was bedeutet, dass der Benutzer die Benachrichtigung wahrscheinlich verworfen hat und Sie das Senden von Updates nicht beenden sollten).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). Es wird nicht empfohlen, einen anderen Toast zu löschen, bis der Status Vorgang abgeschlossen ist (z. b. wenn der Download abgeschlossen ist).We do not recommend popping another toast until your progress operation has been completed (like when the download completes).

Elemente, die die Datenbindung unterstützenElements that support data binding

Die folgenden Elemente in Toast Benachrichtigungen unterstützen die Datenbindung.The following elements in toast notifications support data binding

  • Alle Eigenschaften bei adaptiveprogressAll properties on AdaptiveProgress
  • Die Text -Eigenschaft für die adaptivetext -Elemente der obersten Ebene.The Text property on the top-level AdaptiveText elements

Aktualisieren oder Ersetzen einer BenachrichtigungUpdate or replace a notification

Seit Windows 10 könnten Sie eine Benachrichtigung immer ersetzen , indem Sie einen neuen Toast mit dem gleichen Tag und der gleichen Gruppesenden.Since Windows 10, you could always replace a notification by sending a new toast with the same Tag and Group. Worin besteht der Unterschied zwischen dem austauschen und dem Aktualisieren der Popup Daten?So what's the difference between replacing the toast and updating the toast's data?

SetztenReplacing Wird aktualisiertUpdating
Position im Aktions CenterPosition in Action Center Verschiebt die Benachrichtigung an den oberen Rand des Aktions Centers.Moves the notification to the top of Action Center. Verbleibt die Benachrichtigung innerhalb des Aktions Centers.Leaves the notification in place within Action Center.
Ändern von InhaltenModifying content Kann den gesamten Inhalt/das Layout des Popups vollständig ändern.Can completely change all content/layout of the toast Es können nur Eigenschaften geändert werden, die die Datenbindung unterstützen (Statusanzeige und Text der obersten Ebene).Can only change properties that support data binding (progress bar and top-level text)
Wiedergeben als PopupReappearing as popup Kann als Popup Popup angezeigt werden, wenn Sie suppresspopup auf festlegen false (oder auf true festlegen, um Sie automatisch an das Aktions Center zu senden).Can reappear as a toast popup if you leave SuppressPopup set to false (or set to true to silently send it to Action Center) Wird nicht erneut als Popup angezeigt. die Popup Daten werden im Aktions Center automatisch aktualisiert.Won't reappear as a popup; the toast's data is silently updated within Action Center
Benutzer wurde verworfen.User dismissed Unabhängig davon, ob der Benutzer die vorherige Benachrichtigung verworfen hat, wird der Ersatz Toast immer gesendet.Regardless of whether user dismissed your previous notification, your replacement toast will always be sent Wenn der Benutzer den Popup-Vorgang verworfen hat, schlägt das Popup Update fehlIf the user dismissed your toast, the toast update will fail

Im allgemeinen ist die Aktualisierung nützlich für...In general, updating is useful for...

  • Informationen, die sich häufig in kurzer Zeit ändern und nicht vor dem Eingreifen des Benutzers herangezogen werden müssenInformation that frequently changes in a short period of time and doesn't require being brought to the front of the user's attention
  • Feine Änderungen am Popup Inhalt, z. b. Ändern von 50% in 65%Subtle changes to your toast content, like changing 50% to 65%

Häufig wird empfohlen, nach Abschluss der Abfolge der Updates (z. b. wenn die Datei heruntergeladen wurde) für den letzten Schritt zu ersetzen, weil...Often times, after your sequence of updates have completed (like the file has been downloaded), we recommend replacing for the final step, because...

  • Ihre endgültige Benachrichtigung weist wahrscheinlich drastische Layoutänderungen auf, wie z. b. das Entfernen der Statusanzeige, das Hinzufügen neuer Schaltflächen usw.Your final notification likely has drastic layout changes, like removal of the progress bar, addition of new buttons, etc
  • Möglicherweise hat der Benutzer Ihre ausstehende Fortschritts Benachrichtigung verworfen, da er sich nicht um das Herunterladen kümmert, sondern dennoch mit einem Popup Popup benachrichtigt werden soll, wenn der Vorgang abgeschlossen ist.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