Compartilhar via

Barra de progresso de notificação do sistema e associação de dados

  • Artigo

Uma barra de progresso na notificação do sistema permite que você transmita o status das operações de longa duração para o usuário, como downloads, renderização de vídeo, metas de exercício e muito mais.

Importante

Requer a Atualização para Criadores e a 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 do sistema.

Uma barra de progresso dentro de uma notificação do sistema pode ser "indeterminada" (nenhum valor específico, pontos animados indicam que uma operação está ocorrendo) ou "determinante" (um percentual específico da barra é preenchido, como 60%).

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

Observação

Somente a Área de trabalho oferece suporte às barras de progresso em notificações do sistema. Em outros dispositivos, a barra de progresso será descartada da notificação.

A imagem abaixo mostra uma barra de progresso determinada com todas as propriedades correspondente identificadas.

Notificação do sistema com propriedades da barra de progresso rotuladas
Propriedade Type Obrigatório Descrição
Título string ou BindableString false Obtém ou define uma sequência de título opcional. Suporte à associação de dados.
Valor dobro ou AdaptiveProgressBarValue ou BindableProgressBarValue false Obtém ou define o valor da barra de progresso. Suporte à associação de dados. Assume o padrão de 0. Pode ser um duplo entre 0,0 e 1,0; AdaptiveProgressBarValue.Indeterminate ou new BindableProgressBarValue("myProgressValue").
ValueStringOverride string ou BindableString false Obtém ou define uma sequência para exibição em vez da sequência de percentual padrão. Caso não seja fornecida, algo como "70%" será exibido.
Status string ou BindableString true Obtém ou define uma sequência de status (obrigatória), 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ê pode gerar a notificação 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ê deve atualizar dinamicamente os valores da barra de progresso para que seja realmente "dinâmica". Isso pode ser feito usando associação de dados para atualizar a notificação do sistema.

Uso da associação de dados para atualizar uma notificação do sistema

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

  1. Construir o conteúdo da notificação do sistema que utiliza os campos de dados associados
  2. Atribuir uma Marca (e, opcionalmente, um Grupo) à ToastNotification
  3. Definir os valores de Dados iniciais na ToastNotification
  4. Enviar a notificação do sistema.
  5. Utilizar a Marca e Grupo para atualizar os valores de Dados com os novos valores

O trecho de código a seguir mostra as etapas 1 a 4. O trecho a seguir mostrará como atualizar a 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 os valores de Dados, use o método Update para fornecer os novos dados sem reconstruir o conteúdo inteiro da notificação 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);
}

O uso do método Update em vez da substituição da notificação inteira 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 muito confuso para o usuário ver a notificação do sistema mudar para a parte superior da Central de ações a cada segundo enquanto a barra de progresso é preenchida.

O método Update retorna uma enumeração, NotificationUpdateResult, que permite a você saber se a atualização foi bem-sucedida ou se não foi possível encontrar a notificação (ou seja, o usuário provavelmente ignorou a notificação e você deve parar de enviar atualização dela). Não recomendamos enviar outra notificação até que a operação em andamento seja concluída (por exemplo, quando o download é concluído).

Elementos que oferecem suporte à associação de dados

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

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

Atualizar ou substituir uma notificação

Desde o Windows 10, você sempre pode substituir uma notificação ao enviar 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?

Substituir Atualizar
Posição na Central de Ações Move a notificação para o tipo da Central de ações. Deixa a notificação sem alterações na Central de ações.
Modificar o conteúdo Pode alterar completamente todo o conteúdos/layout da notificação do sistema Pode alterar somente as propriedades que oferecem suporte à associação de dados (barra de progresso e texto de nível superior)
Reaparece como pop-up Podem reaparecer como um pop-up de notificação do sistema se você deixar SuppressPopup definida como false (ou definida como true para enviá-la silenciosamente à Central de ações) Não reaparece como um pop-up; os dados da notificação do sistema são atualizados silenciosamente na Central de ações
Ignorado pelo usuário A notificação substituta sempre será enviada independentemente do usuário ignorar a notificação anterior Se o usuário ignorou a notificação do sistema, ocorre falha na atualização dela

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

  • Informações que mudam frequentemente em um curto período de tempo e não exigem a atenção imediata do usuário
  • Alterações sutis de conteúdo de notificação do sistema, como alterar 50% para 65%

Muitas vezes, após a conclusão da sequência de atualizações (como o fim do download do arquivo), recomendamos a substituição como a etapa final, pois...

  • A notificação final provavelmente tem alterações de layout drásticas, como a remoção da barra de progresso, adição de novos botões etc
  • O usuário talvez tenha ignorado sua notificação de progresso pendente, pois eles não se preocupam em assistir o download, mas ainda querem ser notificados com um pop-up de notificação do sistema quando a operação é concluída