Partilhar via

Enviar uma notificação local app de aplicativos UWP C++

Uma app notificação é uma mensagem que você app pode construir e entregar ao seu usuário enquanto ele não estiver dentro do seu app.

Captura de ecrã 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 guia de início rápido usa notificações locais, que são a notificação mais simples de implementar. Todos os tipos de aplicativos (WPF, UWP, WinForms, console) podem enviar notificações!

Note

O termo "toast notificação" está a ser substituído por "app notificação". Ambos os 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 do C++ WRL . 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 do construtor do Windows Community Toolkit (WCT) OU com XML. Se preferir o último, por favor, pule para a Etapa 2 e consulte os exemplos de código sem sintaxe de construtor .

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

Nossos exemplos de sintaxe código do Builder usarão este pacote. Este 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, o app conteúdo da 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 de conteúdo da App notificação .

Começaremos com uma simples notificação 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 é Microsoft.Toolkit.Uwp.Notifications.

Notificação de texto simples

Se você não estiver usando a sintaxe do construtor de bibliotecas de Notificações WCT, construirá o modelo de notificação XML app , preenchê-lo-á com texto e valores, construirá a notificação e a 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 utilizador clica na sua notificação (ou num botão na notificação com ativação em primeiro plano), o app do seu App será OnActivated 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 os seus quadros e ativar as suas janelas tal como faz com o seu código OnLaunched. OnLaunched NÃO é chamado se o usuário clicar em sua app notificação, mesmo que sua app tenha sido fechada e esteja iniciando pela primeira vez. Muitas vezes, recomendamos combinar OnLaunched e OnActivated no seu próprio método OnLaunchedOrActivated, já que a mesma inicialização precisa ocorrer em ambos.

Ativação em profundidade

O primeiro passo para tornar suas notificações acionáveis é adicionar alguns args de lançamento à sua notificação, para que você app possa saber o que iniciar quando o usuário clicar na notificação (neste 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 às notificações. Adicionaremos uma imagem inserida e uma imagem de perfil (substituição do logotipo app).

Note

As imagens podem ser usadas a partir do pacote do app, do armazenamento local do app ou da web. A partir da 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 a Atualização para Criadores de Outono, as imagens na 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 "Gosto" e um botão "Ver" que abre a imagem.

Captura de ecrã 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 de notificação principal (seu App.xaml.cpp OnActivated será chamado).

Manipular a ativação em segundo plano

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

Para obter mais informações sobre tarefas em segundo plano, consulte Apoie o seu app com tarefas em segundo plano.

Se estiver a direcionar-se para a compilação 14393 ou posterior, pode usar tarefas em segundo plano em processo, o que torna as coisas muito mais simples. Observe que as tarefas em segundo plano em 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 seu App.xaml.cs, sobrescreva 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 serem descartadas ou ignoradas pelo usuário, para que os usuários possam olhar para sua notificação depois que o pop-up desaparecer.

No entanto, se a mensagem na sua notificação for relevante apenas por um período de tempo, deve definir um tempo de expiração na app notificação para que os utilizadores não vejam informações obsoletas do seu app. Por exemplo, se uma promoção for válida apenas por 12 horas, defina o tempo de expiração para 12 horas. No código abaixo, definimos o tempo de expiração para ser de 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);
    });

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

Se quiser remover ou substituir programaticamente a notificação enviada, você 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á entreguesapp, consulte Guia de início rápido: gerenciando toast notificações na central de ações (XAML).

Tag e Grupo combinados atuam como uma chave primária composta. Grupo é o identificador mais genérico, onde você pode atribuir grupos como "wallPosts", "mensagens", "friendRequests", etc. E, em seguida, a Tag deve identificar exclusivamente a própria notificação 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 as notificações

As aplicações são responsáveis por remover e limpar as suas próprias notificações. Quando o seu app é iniciado, NÃO limpamos automaticamente as suas notificações.

O Windows só removerá automaticamente uma notificação se o utilizador 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. O app abre a conversa e depois limpa todas as notificações dessa conversa (utilizando RemoveGroup no grupo fornecido pelo app para essa conversa)
  4. A Central de Ações do Usuário agora reflete corretamente o estado de notificação, uma vez que não há notificações obsoletas para essa conversa deixadas na Central de Ações.

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

ToastNotificationManagerCompat::History->Clear();

Resources

  • Last updated on