Barra de progresso do toast e ligação de dados

O uso de uma barra de progresso dentro da notificação toast permite que você transmita o status de operações longas para o usuário, como downloads, renderização de vídeo, metas de exercício e muito mais.

Uma barra de progresso dentro de uma notificação pode ser "indeterminada" (nenhum valor específico, os 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

A imagem abaixo mostra uma barra de progresso determinante 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 "dinâmica". Isso pode ser feito usando a vinculação de dados para atualizar a notificação.

Usando associação de dados para atualizar um aviso

Usar a associação de dados envolve as seguintes etapas...

1. Construir conteúdo de notificação que utiliza campos vinculados a dados
2. Atribua uma Tag (e, opcionalmente, um grupo ) à sua ToastNotification
3. Defina os valores iniciais de dados para o seu ToastNotification
4. Enviar a notificação
5. Utilize o Tag e o 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 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 seus valores Data, use o método Update para fornecer os novos dados sem construir novamente todo o conteúdo 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 atualizar em vez de substituir todo o toast também garante que a notificação toast 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 continuasse saltando para o topo da Central de Ações a cada poucos segundos enquanto a barra de progresso se preenchia!

O método Update retorna uma enumeração NotificationUpdateResult, que permite que você saiba 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 rejeitou sua notificação e você deve parar de enviar atualizações para ela). Não é recomendável exibir outra notificação até que a 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 elementos a seguir nas notificações tipo 'toast' oferecem apoio à associação de dados.

• Todas as propriedades no 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 um novo sistema pelo mesmo de Marca e Group. Então, qual é a diferença entre substituir o brinde e atualizar os dados do brinde?

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

• Informações que frequentemente são alteradas em um curto período de tempo e não exigem ser trazidas para a frente da atenção do usuário
• Alterações sutis no conteúdo do toast, como alterar 50% para 65%

Muitas vezes, após a sequência de atualizações ter sido concluída (como o arquivo ter sido baixado), recomendamos realizar uma substituição na etapa final, pois...

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

Related topics

• exemplo de código completo no GitHub
• documentação do conteúdo do Toast