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

O uso de uma barra de progresso dentro da notificação permite que o utilizador visualize o status de operações de longa duração, como downloads, renderização de vídeo, metas de exercícios e muito mais.

Uma barra de progresso dentro de um toast pode ser "indeterminada" (sem valor específico, pontos animados indicam que uma operação está a ocorrer) ou "determinada" (uma percentagem específica da barra é preenchida, como 60%%).

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

A imagem abaixo mostra uma barra de progresso determinado com todas as suas propriedades correspondentes rotuladas.

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

<toast>
    <visual>
        <binding template="ToastGeneric">
            <text>Downloading your weekly playlist...</text>
            <progress
                title="Weekly playlist"
                value="0.6"
                valueStringOverride="15/26 songs"
                status="Downloading..."/>
        </binding>
    </visual>
</toast>

No entanto, você precisará atualizar dinamicamente os valores da barra de progresso para que ela seja realmente "ao vivo". Isso pode ser feito usando a vinculaçã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. Criar conteúdo de notificação em toast que utiliza campos ligados a dados
2. Atribua uma Tag (e, opcionalmente, um Grupo) à sua ToastNotification
3. Defina os seus valores iniciais Data no ToastNotification
4. Envie o brinde
5. Utilize Tag e Grupo para atualizar os valores de Dados com novos valores

O trecho de código a seguir mostra as etapas 1 a 4. O próximo trecho mostrará como atualizar os valores de Data do toast .

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 quiser alterar os valores de dados , use o método Atualizar para fornecer os novos dados sem reconstruir toda a carga útil do toast.

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 o toast inteiro também garante que a notificação permaneça na mesma posição na Central de Ações e não se desloque para cima ou para baixo. Seria bastante confuso para o usuário se o brinde continuasse pulando para o topo da Central de Ações a cada poucos segundos enquanto a barra de progresso estava cheia!

O método Update retorna um enum, 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 apresentar outra notificação até que a operação em curso tenha sido concluída (como quando o download termina).

Elementos que suportam a vinculação de dados

Os seguintes elementos nas notificações de "toast" suportam a 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 o mesmo de tags e Grupo. Então, qual é a diferença entre substituir a torrada e atualizar os dados da torrada?

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

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

Muitas vezes, após a conclusão da sua sequência de atualizações (como se o arquivo tivesse sido baixado), recomendamos a substituição 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 utilizador pode ter descartado a sua notificação de progresso pendente, pois não se importa em ver o download, mas ainda deseja ser notificado com uma notificação de pop-up quando a operação for concluída.

Related topics

• Exemplo de código completo no GitHub
• Documentação de conteúdo do Toast