Barra de progreso del sistema y enlace de datosToast progress bar and data binding

El uso de una barra de progreso dentro de la notificación del sistema le permite transmitir el estado de las operaciones de ejecución prolongada al usuario, como las descargas, la representación de vídeo, los objetivos del ejercicio y mucho más.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.

Importante

Requiere Creators Update y 1.4.0 de la biblioteca de notificaciones: debe tener como destino el SDK 15063 y ejecutar la compilación 15063 o superior para usar barras de progreso en notificaciones del sistema.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. Debe usar la versión 1.4.0 o posterior de la biblioteca de NuGet de notificaciones de la comunidad de UWP para construir la barra de progreso en el contenido de la notificación del sistema.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.

Una barra de progreso dentro de una notificación del sistema puede ser "indeterminada" (sin valor específico, puntos animados que indican que se está produciendo una operación) o "determinando" (se rellena un porcentaje específico de la barra, como 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: clase NotificationData, método ToastNotifier. Update, clase ToastNotificationImportant APIs: NotificationData class, ToastNotifier.Update method, ToastNotification class

Nota

Solo Desktop admite barras de progreso en las notificaciones del sistema.Only Desktop supports progress bars in toast notifications. En otros dispositivos, la barra de progreso se quitará de la notificación.On other devices, the progress bar will be dropped from your notification.

En la imagen siguiente se muestra una barra de progreso de determinación con todas sus propiedades correspondientes etiquetadas.The picture below shows a determinate progress bar with all of its corresponding properties labeled.

Toast with progress bar properties labeled
PropiedadProperty TipoType ObligatorioRequired DescripciónDescription
TítuloTitle string o BindableStringstring or BindableString falsefalse Obtiene o establece una cadena de título opcional.Gets or sets an optional title string. Admite el enlace de datos.Supports data binding.
ValorValue Double o AdaptiveProgressBarValue o BindableProgressBarValuedouble or AdaptiveProgressBarValue or BindableProgressBarValue falsefalse Obtiene o establece el valor de la barra de progreso.Gets or sets the value of the progress bar. Admite el enlace de datos.Supports data binding. El valor predeterminado es 0.Defaults to 0. Puede ser un valor de tipo Double entre 0,0 y 1,0, AdaptiveProgressBarValue.Indeterminate o new BindableProgressBarValue("myProgressValue") .Can either be a double between 0.0 and 1.0, AdaptiveProgressBarValue.Indeterminate, or new BindableProgressBarValue("myProgressValue").
ValueStringOverrideValueStringOverride string o BindableStringstring or BindableString falsefalse Obtiene o establece una cadena opcional que se va a mostrar en lugar de la cadena de porcentaje predeterminada.Gets or sets an optional string to be displayed instead of the default percentage string. Si no se proporciona, se mostrará algo como "70%".If this isn't provided, something like "70%" will be displayed.
EstadoStatus string o BindableStringstring or BindableString truetrue Obtiene o establece una cadena de estado (obligatorio), que se muestra debajo de la barra de progreso de la izquierda.Gets or sets a status string (required), which is displayed underneath the progress bar on the left. Esta cadena debe reflejar el estado de la operación, como "descargando..." o "instalando..."This string should reflect the status of the operation, like "Downloading..." or "Installing..."

Aquí se muestra cómo generaría la notificación más arriba...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..."
    });

Sin embargo, deberá actualizar dinámicamente los valores de la barra de progreso para que realmente sea "activo".However, you'll need to dynamically update the values of the progress bar for it to actually be "live". Esto puede hacerse mediante el enlace de datos para actualizar la notificación del sistema.This can be done by using data binding to update the toast.

Usar el enlace de datos para actualizar una notificación del sistemaUsing data binding to update a toast

El uso del enlace de datos implica los siguientes pasos...Using data binding involves the following steps...

  1. Construir contenido del sistema de notificación que use campos enlazados a datosConstruct toast content that utilizes data bound fields
  2. Asignar una etiqueta (y, opcionalmente, un Grupo) a su ToastNotificationAssign a Tag (and optionally a Group) to your ToastNotification
  3. Definir los valores de datos iniciales en el ToastNotificationDefine your initial Data values on your ToastNotification
  4. Enviar la notificación del sistemaSend the toast
  5. Uso de etiquetas y grupos para actualizar los valores de datos con nuevos valoresUtilize Tag and Group to update the Data values with new values

En el fragmento de código siguiente se muestran los pasos 1-4.The following code snippet shows steps 1-4. El siguiente fragmento de código mostrará cómo actualizar los valores de datos del sistema.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);
}

Después, si desea cambiar los valores de datos , use el método Update para proporcionar los nuevos datos sin volver a construir toda la carga del sistema.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);
}

El uso del método Update en lugar de reemplazar toda la notificación del sistema también garantiza que la notificación del sistema se mantiene en la misma posición en el centro de actividades y no se desplaza hacia arriba o hacia abajo.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. Sería bastante confuso para el usuario si la notificación del sistema estaba pasando a la parte superior del centro de actividades cada pocos segundos mientras se rellena la barra de progreso.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!

El método Update devuelve una enumeración, NotificationUpdateResult, que le permite saber si la actualización se ha realizado correctamente o si no se ha podido encontrar la notificación (lo que significa que el usuario probablemente haya descartado la notificación y debe dejar de enviarle actualizaciones).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). No se recomienda extraer otra notificación de sistema hasta que se haya completado la operación de progreso (como cuando se complete la descarga).We do not recommend popping another toast until your progress operation has been completed (like when the download completes).

Elementos que admiten el enlace de datosElements that support data binding

Los siguientes elementos de las notificaciones del sistema admiten el enlace de datosThe following elements in toast notifications support data binding

  • Todas las propiedades de AdaptiveProgressAll properties on AdaptiveProgress
  • Propiedad de texto en los elementos AdaptiveText de nivel superiorThe Text property on the top-level AdaptiveText elements

Actualizar o reemplazar una notificaciónUpdate or replace a notification

Desde Windows 10, siempre podía reemplazar una notificación mediante el envío de una nueva notificación con la misma etiqueta y el mismo Grupo.Since Windows 10, you could always replace a notification by sending a new toast with the same Tag and Group. ¿Cuál es la diferencia entre reemplazar la notificación del sistema y Actualizar los datos del sistema de notificaciones?So what's the difference between replacing the toast and updating the toast's data?

ReemplaceReplacing ActualizandoUpdating
Posición en el centro de actividadesPosition in Action Center Mueve la notificación a la parte superior del centro de actividades.Moves the notification to the top of Action Center. Deja la notificación en el centro de actividades.Leaves the notification in place within Action Center.
Modificar contenidoModifying content Puede cambiar completamente todo el contenido o el diseño de la notificación del sistemaCan completely change all content/layout of the toast Solo se pueden cambiar las propiedades que admiten el enlace de datos (barra de progreso y texto de nivel superior)Can only change properties that support data binding (progress bar and top-level text)
Mostrar como emergenteReappearing as popup Puede volver a aparecer como una ventana emergente del sistema si deja SuppressPopup establecido en false (o se establece en true para enviarlo al centro de actividades de forma silenciosa)Can reappear as a toast popup if you leave SuppressPopup set to false (or set to true to silently send it to Action Center) No volverá a aparecer como un elemento emergente; los datos del sistema se actualizan de forma silenciosa en el centro de actividadesWon't reappear as a popup; the toast's data is silently updated within Action Center
Usuario descartadoUser dismissed Independientemente de si el usuario ha descartado la notificación anterior, siempre se enviará la notificación de sustituciónRegardless of whether user dismissed your previous notification, your replacement toast will always be sent Si el usuario ha descartado la notificación del sistema, se producirá un error en la actualización del sistemaIf the user dismissed your toast, the toast update will fail

En general, la actualización es útil para...In general, updating is useful for...

  • Información que cambia con frecuencia en un breve período de tiempo y no requiere que se ponga al frente de la atención del usuarioInformation that frequently changes in a short period of time and doesn't require being brought to the front of the user's attention
  • Cambios sutiles en el contenido de la notificación del sistema, como el cambio del 50% al 65%Subtle changes to your toast content, like changing 50% to 65%

A menudo, una vez completada la secuencia de actualizaciones (al igual que el archivo se ha descargado), se recomienda reemplazar para el paso final, ya que...Often times, after your sequence of updates have completed (like the file has been downloaded), we recommend replacing for the final step, because...

  • La notificación final probablemente tiene cambios de diseño drásticos, como la eliminación de la barra de progreso, la adición de nuevos botones, etc.Your final notification likely has drastic layout changes, like removal of the progress bar, addition of new buttons, etc
  • Es posible que el usuario haya descartado la notificación de progreso pendiente, ya que no le importa ver la descarga, pero aún desea recibir una notificación cuando se complete la operación.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