Compartilhar via

Barra de progresso da notificação do sistema e vinculação de dados

  • Artigo

O uso de uma barra de progresso dentro da notificação do sistema permite que você transmita o status de operações de longa duração ao usuário, como downloads, renderização de vídeo, metas de exercícios e muito mais.

Importante

Requer a Atualização para Criadores e a versão 1.4.0 da biblioteca de notificações: você deve direcionar o SDK 15063 e estar executando o build 15063 ou posterior para usar barras de progresso em notificações do sistema. Você deve usar a versão 1.4.0 ou posterior da biblioteca NuGet de Notificações do Kit de Ferramentas da Comunidade UWP para construir a barra de progresso no conteúdo da notificação do sistema.

Uma barra de progresso dentro de uma notificação do sistema pode ser "indeterminada" (sem valor específico, pontos animados indicam que uma operação está ocorrendo) ou "determinada" (uma porcentagem específica da barra é preenchida, como 60%).

APIs importantes: classe NotificationData, método ToastNotifier.Update, classe ToastNotification

Observação

Somente o Desktop oferece suporte a barras de progresso em notificações do sistema. Em outros dispositivos, a barra de progresso será removida da sua notificação.

A figura abaixo mostra uma barra de progresso determinada com todas as suas propriedades correspondentes rotuladas.

Notificação do sistema com propriedades da barra de progresso rotuladas
Propriedade Type Obrigatória Description
Título string ou BindableString false Obtém ou define uma sequência de títulos opcional. Suporte para a associação de dados.
Valor double ou AdaptiveProgressBarValue ou BindableProgressBarValue false Obtém ou define o valor da barra de progresso. Suporte para a associação de dados. Assume o padrão de 0. Pode ser um duplo entre 0,0 e 1,0, AdaptiveProgressBarValue.Indeterminateou new BindableProgressBarValue("myProgressValue").
ValueStringOverride string ou BindableString false Obtém ou define uma sequência opcional a ser exibida em vez da sequência de porcentagem padrão. Se isso não for fornecido, algo como "70%" será exibido.
Status string ou BindableString true Obtém ou define uma sequência de status (obrigatório), que é exibida abaixo da barra de progresso à esquerda. Essa sequência deve refletir o status da operação, como "Baixando..." ou "Instalando..."

Veja como você geraria a notificação vista acima...

new ToastContentBuilder()
    .AddText("Downloading your weekly playlist...")
    .AddVisualChild(new AdaptiveProgressBar()
    {
        Title = "Weekly playlist",
        Value = 0.6,
        ValueStringOverride = "15/26 songs",
        Status = "Downloading..."
    });

No entanto, você precisará atualizar dinamicamente os valores da barra de progresso para que ela esteja realmente "ativa". Isso pode ser feito usando a associação de dados para atualizar a notificação do sistema.

Usando a vinculação de dados para atualizar uma notificação do sistema

O uso da vinculação de dados envolve as seguintes etapas...

  1. Construir conteúdo do sistema que utiliza campos associados a dados
  2. Atribua uma Tag (e, opcionalmente, um Grupo) ao seu ToastNotification
  3. Defina seus valores iniciais de dados em seu ToastNotification
  4. Enviar a notificação do sistema
  5. Utilize Tag e Grupo para atualizar os valores de dados com novos valores

O snippet de código a seguir mostra as etapas 1 a 4. O próximo snippet mostrará como atualizar os valores de dados da notificação do 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);
}

Em seguida, quando você quiser alterar seus valores de dados , use o método Update para fornecer os novos dados sem reconstruir toda a carga do 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);
}

Usar o método Update em vez de substituir toda a notificação do sistema também garante que a notificação do sistema permaneça na mesma posição na Central de Ações e não se mova para cima ou para baixo. Seria bastante confuso para o usuário se a notificação do sistema continuasse pulando para o topo da Central de Ações a cada poucos segundos enquanto a barra de progresso era preenchida!

O método Update retorna uma enumeração, NotificationUpdateResult, que permite saber se a atualização foi bem-sucedida ou se a notificação não pôde ser encontrada (o que significa que o usuário provavelmente descartou sua notificação e você deve parar de enviar atualizações para ela). Não recomendamos fazer outra notificação do sistema até que sua operação de progresso seja concluída (como quando o download for concluído).

Elementos que dão suporte à associação de dados

Os seguintes elementos em notificações do sistema dão suporte à vinculação de dados

  • Todas as propriedades em AdaptiveProgress
  • A propriedade Text nos elementos AdaptiveText de nível superior

Atualizar ou substituir uma notificação

Desde o Windows 10, você sempre pode substituir uma notificação enviando uma nova notificação do sistema com a mesma marca e grupo. Então, qual é a diferença entre substituir a notificação do sistema e atualizar os dados da notificação do sistema?

Substituição Atualizar
Posição no Centro de Ação Move a notificação para a parte superior da Central de Ações. Deixa a notificação em vigor na Central de Ações.
Modificando conteúdo Pode alterar completamente todo o conteúdo/layout da notificação do sistema Só pode alterar propriedades que dão suporte à associação de dados (barra de progresso e texto de nível superior)
Reaparecendo como pop-up Pode reaparecer como um pop-up da notificação do sistema se você deixar SuppressPopup definido como false (ou definido como true para enviá-lo silenciosamente para a Central de Ações) Não reaparecerá como um pop-up; os dados da notificação do sistema são atualizados silenciosamente na Central de Ações
Usuário dispensado Independentemente de o usuário ter descartado sua notificação anterior, sua notificação do sistema de substituição sempre será enviada Se o usuário descartou sua notificação do sistema, a atualização da notificação do sistema falhará

Em geral, a atualização é útil para...

  • Informações que mudam com frequência em um curto período de tempo e não precisam ser trazidas à tona da atenção do usuário
  • Alterações sutis no conteúdo da notificação do sistema, como alterar de 50% para 65%

Muitas vezes, após a conclusão da sequência de atualizações (como o download do arquivo), recomendamos substituí-la para a etapa final, porque...

  • Sua notificação final provavelmente tem mudanças drásticas de layout, como remoção da barra de progresso, adição de novos botões, etc
  • O usuário pode ter descartado sua notificação de progresso pendente, pois não se importa em assisti-la ao download, mas ainda deseja ser notificado com uma notificação do sistema pop-up quando a operação for concluída