Share via

Barra de progreso del sistema y enlace de datos

  • Artículo

El uso de una barra de progreso dentro de la notificación del sistema permite transmitir el estado de las operaciones de larga duración al usuario, como descargas, representación de vídeo, objetivos de ejercicio, etc.

Importante

Requiere Creators Update y 1.4.0 de la biblioteca de notificaciones: debe tener como destino sdk 15063 y ejecutar la compilación 15063 o posterior para usar barras de progreso en las notificaciones del sistema. Debes usar la versión 1.4.0 o posterior de la biblioteca NuGet Notificaciones del Kit de herramientas de la comunidad para UWP para construir la barra de progreso en el contenido de la notificación del sistema.

Una barra de progreso dentro de una notificación del sistema puede ser "indeterminada" (ningún valor específico, los puntos animados indican que se está produciendo una operación) o "determinate" (se rellena un porcentaje específico de la barra, como el 60 %).

API importantes: clase NotificationData, método ToastNotifier.Update, clase ToastNotification

Nota

Solo desktop admite barras de progreso en las notificaciones del sistema. En otros dispositivos, la barra de progreso se quitará de la notificación.

En la imagen siguiente se muestra una barra de progreso determinada con todas sus propiedades correspondientes etiquetadas.

Notificación del sistema con propiedades de la barra de progreso etiquetadas
Propiedad Tipo Obligatorio Descripción
Título string o BindableString false Obtiene o establece una cadena de título opcional. Admite el enlace de datos.
Valor double o AdaptiveProgressBarValue o BindableProgressBarValue false Obtiene o establece el valor de la barra de progreso. Admite el enlace de datos. El valor predeterminado es 0. Puede ser un doble entre 0,0 y 1,0, AdaptiveProgressBarValue.Indeterminateo new BindableProgressBarValue("myProgressValue").
ValueStringOverride string o BindableString false Obtiene o establece una cadena opcional que se va a mostrar en lugar de la cadena de porcentaje predeterminada. Si no se proporciona, se mostrará algo parecido a "70%".
Estado string o BindableString true Obtiene o establece una cadena de estado (obligatorio), que se muestra debajo de la barra de progreso de la izquierda. Esta cadena debe reflejar el estado de la operación, como "Descargando..." o "Instalar..."

Aquí se muestra cómo generaría la notificación que se ha visto anteriormente...

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". Esto se puede hacer mediante el enlace de datos para actualizar la notificación del sistema.

Uso del enlace de datos para actualizar una notificación del sistema

El uso del enlace de datos implica los pasos siguientes...

  1. Construir contenido del sistema que use campos enlazados a datos
  2. Asignar una etiqueta (y, opcionalmente, un grupo) a toastNotification
  3. Definición de los valores de datos iniciales en toastNotification
  4. Enviar la notificación del sistema
  5. Usar etiqueta y grupo para actualizar los valores de datos con nuevos valores

En el fragmento de código siguiente se muestran los pasos 1 a 4. El siguiente fragmento de código mostrará cómo actualizar los valores de datos del sistema.

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

A continuación, cuando desee cambiar los valores de data , use el método Update para proporcionar los nuevos datos sin volver a construir toda la carga del sistema.

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 permanezca en la misma posición en el Centro de actividades y no se mueva hacia arriba o hacia abajo. Sería bastante confuso para el usuario si la notificación del sistema seguía saltando a la parte superior del Centro de actividades cada pocos segundos mientras la barra de progreso se llenaba.

El método Update devuelve una enumeración, NotificationUpdateResult, que le permite saber si la actualización se realizó correctamente o si no se encontró la notificación (lo que significa que el usuario probablemente ha descartado la notificación y debe dejar de enviar actualizaciones a ella). No se recomienda sacar otra notificación del sistema hasta que se haya completado la operación de progreso (como cuando se complete la descarga).

Elementos que admiten el enlace de datos

Los siguientes elementos de las notificaciones del sistema admiten el enlace de datos.

  • Todas las propiedades de AdaptiveProgress
  • La propiedad Text de los elementos AdaptiveText de nivel superior

Actualizar o reemplazar una notificación

Desde Windows 10, siempre puedes reemplazar una notificación mediante el envío de una nueva notificación del sistema por la misma etiqueta y grupo. ¿Cuál es la diferencia entre reemplazar la notificación del sistema y actualizar los datos de la notificación del sistema?

Reemplazar Actualizando
Posición en el Centro de actividades Mueve la notificación a la parte superior del Centro de actividades. Deja la notificación en su lugar en el Centro de actividades.
Modificación del contenido Puede cambiar completamente todo el contenido o el diseño de la notificación del sistema Solo se pueden cambiar las propiedades que admiten el enlace de datos (barra de progreso y texto de nivel superior)
Volver a aparecer como elemento emergente Puede volver a aparecer como un elemento emergente de notificación del sistema si deja SuppressPopup establecido false en (o se establece en true para enviarlo de forma silenciosa al Centro de actividades). No reaparecerá como un elemento emergente; Los datos del sistema se actualizan de forma silenciosa en el Centro de actividades
Usuario descartado Independientemente de si el usuario ha descartado la notificación anterior, siempre se enviará la notificación del sistema de reemplazo. Si el usuario descarta la notificación del sistema, se producirá un error en la actualización del sistema.

En general, la actualización es útil para...

  • Información que cambia con frecuencia en un breve período de tiempo y no requiere que se le preste atención al usuario.
  • Cambios sutiles en el contenido de la notificación del sistema, como cambiar del 50 % al 65 %

A menudo, después de que se haya completado la secuencia de actualizaciones (como el archivo se ha descargado), se recomienda reemplazar por el paso final, porque...

  • Es probable que la notificación final tenga cambios de diseño drásticos, como la eliminación de la barra de progreso, la adición de nuevos botones, 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 con una notificación emergente cuando se completa la operación.