Compartilhar via

Enviar uma notificação local app de um aplicativo UWP em C++

Uma notificação app é uma mensagem que seu app pode construir e entregar ao usuário quando ele não está no seu app.

Captura de tela de uma app notificação

Este guia de início rápido orienta você pelas etapas para criar, entregar e exibir uma notificação do Windows 10 ou Windows 11 app usando conteúdo avançado e ações interativas. Este início rápido usa notificações locais, que são a notificação mais simples a ser implementada. Todos os tipos de aplicativos (WPF, UWP, WinForms, console) podem enviar notificações!

Note

O termo "toast notificação" está sendo substituído por "app notificação". Esses termos se referem ao mesmo recurso do Windows, mas, com o tempo, eliminaremos gradualmente o uso de "toast notificação" na documentação.

Important

Se você estiver escrevendo um C++ não UWP app, consulte a documentação da WRL do C++ . Se você estiver escrevendo um C# app, consulte a documentação do C#.

Etapa 1: Instalar o pacote NuGet

Você pode criar app notificações com a sintaxe de construtor do WCT (Windows Community Toolkit) ou com XML. Se preferir a última opção, pule para etapa 2 e consulte os exemplos de código Sem a sintaxe do construtor.

Na solução do Visual Studio, clique com o botão direito do mouse no projeto, clique em "Gerenciar pacotes NuGet..." e pesquise e instale o Microsoft.Toolkit.Uwp.Notificationspacote NuGet versão 7.0 ou superior.

Nossos exemplos de código de sintaxe Builder usarão este pacote. Esse pacote permite que você crie app notificações sem usar XML.

Etapa 2: Adicionar declarações de namespace

using namespace Microsoft::Toolkit::Uwp::Notifications;

Etapa 3: Enviar uma app notificação

No Windows 10 e no Windows 11, seu app conteúdo de notificação é descrito usando uma linguagem adaptável que permite grande flexibilidade com a aparência da notificação. Para obter mais informações, consulte a documentação do conteúdo da App notificação .

Começaremos com uma notificação simples baseada em texto. Construa o conteúdo da notificação (usando a biblioteca de notificações) e mostre a notificação! Observe que o namespace está Microsoft.Toolkit.Uwp.Notifications.

Notificação de texto simples

Se você não estiver usando a sintaxe do construtor de bibliotecas de Notificações do WCT, construirá o modelo de notificação XML app , o preencherá com texto e valores, construirá a notificação e mostrará.

// Construct the content and show the toast!
(ref new ToastContentBuilder())
    ->AddArgument("action", "viewConversation")
    ->AddArgument("conversationId", 9813)
    ->AddText("Andrew sent you a picture")
    ->AddText("Check this out, The Enchantments in Washington!")
    ->Show();

Etapa 4: Manipular a ativação

Quando o usuário clica na notificação (ou em um botão na notificação com ativação em primeiro plano), o appApp.xaml.cppOnActivated será invocado.

App.xaml.cpp

void App::OnActivated(IActivatedEventArgs^ e)
{
    // Handle notification activation
    if (e->Kind == ActivationKind::ToastNotification)
    {
        ToastNotificationActivatedEventArgs^ toastActivationArgs = (ToastNotificationActivatedEventArgs^)e;

        // Obtain the arguments from the notification
        ToastArguments^ args = ToastArguments::Parse(toastActivationArgs->Argument);

        // Obtain any user input (text boxes, menu selections) from the notification
        auto userInput = toastActivationArgs->UserInput;

        // TODO: Show the corresponding content
    }
}

Important

Você deve inicializar seu quadro e ativar sua janela assim como seu código OnLaunched . OnLaunched NÃO será chamado se o usuário clicar na sua app notificação, mesmo que o seu app esteja fechado e seja iniciado pela primeira vez. Geralmente, recomendamos combinar OnLaunched e OnActivated no seu próprio método OnLaunchedOrActivated, já que a mesma inicialização precisa ocorrer nos dois casos.

Ativação detalhada

A primeira etapa para tornar suas notificações acionáveis é adicionar alguns argumentos de inicialização à notificação, para que você app possa saber o que iniciar quando o usuário clicar na notificação (nesse caso, estamos incluindo algumas informações que mais tarde nos dizem que devemos abrir uma conversa e sabemos qual conversa específica abrir).

// Construct the content and show the toast!
(ref new ToastContentBuilder())

    // Arguments returned when user taps body of notification
    ->AddArgument("action", "viewConversation")
    ->AddArgument("conversationId", 9813)

    ->AddText("Andrew sent you a picture")
    ->Show();

Adicionar imagens

Você pode adicionar conteúdo avançado a notificações. Adicionaremos uma imagem embutida e uma imagem de perfil (app substituição de logotipo).

Note

As imagens podem ser usadas do pacote do app, do armazenamento local do app ou da web. A partir do Fall Creators Update, as imagens da Web podem ter até 3 MB em conexões normais e 1 MB em conexões limitadas. Em dispositivos que ainda não executam o Fall Creators Update, as imagens da Web não devem ter mais de 200 KB.

Toast com imagens 
// Construct the content and show the toast!
(ref new ToastContentBuilder())
    ...

    // Inline image
    ->AddInlineImage(ref new Uri("https://picsum.photos/360/202?image=883"))

    // Profile (app logo override) image
    ->AddAppLogoOverride(ref new Uri("ms-appdata:///local/Andrew.jpg"), ToastGenericAppLogoCrop::Circle)

    ->Show();

Adicionar botões e entradas

Você pode adicionar botões e entradas para tornar suas notificações interativas. Os botões podem iniciar seu primeiro plano app, um protocolo ou sua tarefa em segundo plano. Adicionaremos uma caixa de texto de resposta, um botão "Curtir" e um botão "Exibir" que abre a imagem.

Captura de tela de uma toast notificação com entradas e botões 
// Construct the content
(ref new ToastContentBuilder())
    ->AddArgument("conversationId", 9813)
    ...

    // Text box for replying
    ->AddInputTextBox("tbReply", "Type a response")

    // Buttons
    ->AddButton((ref new ToastButton())
        ->SetContent("Reply")
        ->AddArgument("action", "reply")
        ->SetBackgroundActivation())

    ->AddButton((ref new ToastButton())
        ->SetContent("Like")
        ->AddArgument("action", "like")
        ->SetBackgroundActivation())

    ->AddButton((ref new ToastButton())
        ->SetContent("View")
        ->AddArgument("action", "view"))

    ->Show();

A ativação dos botões de primeiro plano é tratada da mesma forma que o corpo principal da notificação (o método OnActivated em seu arquivo App.xaml.cpp será chamado).

Gerenciar a ativação em segundo plano

Quando você especificar a ativação em segundo plano na app notificação (ou em um botão dentro da notificação), sua tarefa em segundo plano será executada em vez de ativar seu primeiro plano app.

Para obter mais informações sobre tarefas em segundo plano, consulte Dar suporte às tarefas app em segundo plano.

Se você estiver direcionando o build 14393 ou posterior, poderá usar tarefas em segundo plano em execução, o que simplifica muito as coisas. Observe que as tarefas em segundo plano no processo não serão executadas em versões mais antigas do Windows. Usaremos uma tarefa em segundo plano em processo neste exemplo de código.

const string taskName = "ToastBackgroundTask";

// If background task is already registered, do nothing
if (BackgroundTaskRegistration.AllTasks.Any(i => i.Value.Name.Equals(taskName)))
    return;

// Otherwise request access
BackgroundAccessStatus status = await BackgroundExecutionManager.RequestAccessAsync();

// Create the background task
BackgroundTaskBuilder builder = new BackgroundTaskBuilder()
{
    Name = taskName
};

// Assign the toast action trigger
builder.SetTrigger(new ToastNotificationActionTrigger());

// And register the task
BackgroundTaskRegistration registration = builder.Register();

Em seguida, no App.xaml.cs, sobreponha o método OnBackgroundActivated. Em seguida, você pode recuperar os argumentos predefinidos e a entrada do usuário, semelhante à ativação em primeiro plano.

App.xaml.cs

protected override async void OnBackgroundActivated(BackgroundActivatedEventArgs args)
{
    var deferral = args.TaskInstance.GetDeferral();

    switch (args.TaskInstance.Task.Name)
    {
        case "ToastBackgroundTask":
            var details = args.TaskInstance.TriggerDetails as ToastNotificationActionTriggerDetail;
            if (details != null)
            {
                string arguments = details.Argument;
                var userInput = details.UserInput;

                // Perform tasks
            }
            break;
    }

    deferral.Complete();
}

Definir um tempo de expiração

No Windows 10 e 11, todas as app notificações vão para a Central de Ações depois de descartadas ou ignoradas pelo usuário, para que os usuários possam verificar as notificações depois que o pop-up desaparecer.

No entanto, se a mensagem em sua notificação for relevante apenas por um período de tempo, você deverá definir um tempo de expiração na app notificação para que os usuários não vejam informações obsoletas de seu app. Por exemplo, se uma promoção for válida apenas por 12 horas, defina o tempo de expiração como 12 horas. No código abaixo, definimos o tempo de expiração como 2 dias.

Note

O tempo de expiração padrão e máximo para notificações locais app é de 3 dias.

// Create toast content and show the toast!
(ref new ToastContentBuilder())
    ->AddText("Expires in 2 days...")
    ->Show(toast =>
    {
        toast->ExpirationTime = DateTime::Now->AddDays(2);
    });

Fornecer uma chave primária para sua app notificação

Se você quiser remover ou substituir programaticamente a notificação enviada, precisará usar a propriedade Tag (e, opcionalmente, a propriedade Group) para fornecer uma chave primária para sua notificação. Em seguida, você pode usar essa chave primária no futuro para remover ou substituir a notificação.

Para ver mais detalhes sobre como substituir/remover notificações já entregues app , consulte Início Rápido: Gerenciando toast notificações na central de ações (XAML).

A tag e o grupo combinados funcionam como uma chave primária composta. O grupo é o identificador mais genérico, onde você pode criar grupos como "wallPosts", "messages", "friendRequests" etc. Em seguida, a tag deve identificar exclusivamente a notificação propriamente dita dentro do grupo. Usando um grupo genérico, você pode remover todas as notificações desse grupo usando a API RemoveGroup.

// Create toast content and show the toast!
(ref new ToastContentBuilder())
    ->AddText("New post on your wall!")
    ->Show(toast =>
    {
        toast.Tag = "18365";
        toast.Group = "wallPosts";
    });

Limpar suas notificações

Os aplicativos são responsáveis por remover e limpar suas próprias notificações. Quando o seu app é iniciado, NÃO excluímos automaticamente suas notificações.

O Windows só removerá automaticamente uma notificação se o usuário clicar explicitamente na notificação.

Aqui está um exemplo do que uma mensagem app deve fazer...

  1. O usuário recebe várias app notificações sobre novas mensagens em uma conversa
  2. O usuário toca em uma dessas notificações para abrir a conversa
  3. Abre app a conversa e limpa todas as notificações dessa conversa (usando RemoveGroup no appgrupo fornecido para essa conversa)
  4. A Central de Ações do usuário agora reflete corretamente o estado de notificação, já que não há notificações obsoletas para essa conversa deixada na Central de Ações.

Para saber mais sobre como limpar todas as notificações ou remover notificações específicas, consulte Início Rápido: Gerenciando toast notificações na central de ações (XAML).

ToastNotificationManagerCompat::History->Clear();

Resources

  • Last updated on