Partager via


Envoyer une notification toast locale à partir d’applications UWP C++

Une notification toast est un message que votre application peut construire et remettre à votre utilisateur alors qu’il ne se trouve pas actuellement à l’intérieur de votre application.

Capture d’écran d’une notification toast

Ce guide de démarrage rapide vous guide tout au long des étapes de création, de remise et d’affichage d’une notification toast Windows 10 ou Windows 11 à l’aide d’un contenu enrichi et d’actions interactives. Ce guide de démarrage rapide utilise des notifications locales, qui sont la notification la plus simple à implémenter. Tous les types d’applications (WPF, UWP, WinForms, console) peuvent envoyer des notifications !

Important

Si vous écrivez une application C++ non-UWP, consultez la documentation WRL C++ . Si vous écrivez une application C#, consultez la documentation C#.

Étape 1 : Installer le package NuGet

Vous pouvez créer des notifications toast avec la syntaxe de générateur de Windows Community Toolkit (WCT) OU avec XML. Si vous préférez ce dernier, passez à l’étape 2 et reportez-vous aux exemples de code de syntaxe Sans générateur .

Dans votre solution Visual Studio, cliquez avec le bouton droit sur votre projet, cliquez sur « Gérer les packages NuGet... », puis recherchez et installez le Microsoft.Toolkit.Uwp.Notificationspackage NuGet version 7.0 ou ultérieure.

Nos exemples de code de syntaxe Builder utilisent ce package. Ce package vous permet de créer des notifications toast sans utiliser XML.

Étape 2 : Ajouter des déclarations d’espace de noms

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

Étape 3 : Envoyer un toast

Dans Windows 10 et Windows 11, le contenu de votre notification toast est décrit à l’aide d’un langage adaptatif qui offre une grande flexibilité quant à l’apparence de votre notification. Pour plus d’informations, consultez la documentation relative au contenu toast.

Nous allons commencer par une simple notification textuelle. Construisez le contenu de la notification (à l’aide de la bibliothèque notifications) et affichez la notification ! Notez que l’espace de noms est Microsoft.Toolkit.Uwp.Notifications.

Notification texte simple

Si vous n’utilisez pas la syntaxe du générateur de bibliothèque notifications WCT, vous allez plutôt construire le modèle toast XML, le remplir avec du texte et des valeurs, construire la notification et l’afficher.

// 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();

Étape 4 : Gestion de l’activation

Lorsque l’utilisateur clique sur votre notification (ou un bouton sur la notification avec activation au premier plan), l’application App.xaml.cppOnActivated de votre application est appelée.

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

Vous devez initialiser votre frame et activer votre fenêtre comme votre code OnLaunched . OnLaunched n’est PAS appelé si l’utilisateur clique sur votre toast, même si votre application a été fermée et est lancée pour la première fois. Nous vous recommandons souvent de combiner OnLaunched et OnActivated dans votre propre OnLaunchedOrActivated méthode, car la même initialisation doit se produire dans les deux.

Activation en profondeur

La première étape pour rendre vos notifications exploitables consiste à ajouter des arguments de lancement à votre notification, afin que votre application puisse savoir quoi lancer lorsque l’utilisateur clique sur la notification (dans ce cas, nous incluons des informations qui nous indiquent ultérieurement que nous devons ouvrir une conversation, et nous savons quelle conversation spécifique ouvrir).

// 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();

Ajout d’images

Vous pouvez ajouter du contenu enrichi aux notifications. Nous allons ajouter une image inline et une image de profil (remplacement du logo d’application).

Notes

Les images peuvent être utilisées à partir du package de l’application, du stockage local de l’application ou du web. À compter de la mise à jour fall Creators Update, les images web peuvent atteindre 3 Mo sur les connexions normales et 1 Mo sur les connexions limitées. Sur les appareils qui n’exécutent pas encore fall Creators Update, les images web ne doivent pas dépasser 200 Ko.

Toast avec des images
// 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();

Ajout de boutons et d’entrées

Vous pouvez ajouter des boutons et des entrées pour rendre vos notifications interactives. Les boutons peuvent lancer votre application de premier plan, un protocole ou votre tâche en arrière-plan. Nous allons ajouter une zone de texte de réponse, un bouton « J’aime » et un bouton « Afficher » qui ouvre l’image.

Capture d’écran d’une notification toast avec entrées et boutons
// 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();

L’activation des boutons de premier plan est gérée de la même manière que le corps toast main (votre app.xaml.cpp OnActivated sera appelé).

Gestion de l’activation en arrière-plan

Lorsque vous spécifiez l’activation en arrière-plan sur votre toast (ou sur un bouton à l’intérieur du toast), votre tâche en arrière-plan est exécutée au lieu d’activer votre application de premier plan.

Pour plus d’informations sur les tâches en arrière-plan, consultez Prise en charge de votre application avec des tâches en arrière-plan.

Si vous ciblez la build 14393 ou ultérieure, vous pouvez utiliser des tâches en arrière-plan in-process, ce qui simplifie considérablement les choses. Notez que les tâches en arrière-plan in-process ne pourront pas s’exécuter sur les versions antérieures de Windows. Nous allons utiliser une tâche en arrière-plan in-process dans cet exemple de code.

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();

Ensuite, dans votre app.xaml.cs, remplacez la méthode OnBackgroundActivated. Vous pouvez ensuite récupérer les arguments prédéfinis et l’entrée utilisateur, comme l’activation au premier plan.

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();
}

Définir une heure d’expiration

Dans Windows 10 et 11, toutes les notifications toast sont envoyées dans le Centre de notifications une fois qu’elles ont été ignorées ou ignorées par l’utilisateur, afin que les utilisateurs puissent consulter votre notification une fois la fenêtre contextuelle supprimée.

Toutefois, si le message de votre notification n’est pertinent que pour une période donnée, vous devez définir une heure d’expiration sur la notification toast afin que les utilisateurs ne voient pas les informations obsolètes de votre application. Par exemple, si une promotion n’est valide que pendant 12 heures, définissez le délai d’expiration sur 12 heures. Dans le code ci-dessous, nous définissons la durée d’expiration sur 2 jours.

Notes

La durée d’expiration par défaut et maximale des notifications toast locales est de 3 jours.

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

Fournissez une clé primaire pour votre toast

Si vous souhaitez supprimer ou remplacer par programmation la notification que vous envoyez, vous devez utiliser la propriété Tag (et éventuellement la propriété Group) pour fournir une clé primaire pour votre notification. Ensuite, vous pouvez utiliser cette clé primaire à l’avenir pour supprimer ou remplacer la notification.

Pour plus d’informations sur le remplacement/la suppression des notifications toast déjà remises, consultez Démarrage rapide : Gestion des notifications toast dans le centre de notifications (XAML) .

L’étiquette et le groupe combinés agissent comme une clé primaire composite. Group est l’identificateur le plus générique, où vous pouvez affecter des groupes tels que « wallPosts », « messages », « friendRequests », etc. La balise doit ensuite identifier de manière unique la notification elle-même à partir du groupe. En utilisant un groupe générique, vous pouvez ensuite supprimer toutes les notifications de ce groupe à l’aide de l’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";
    });

Effacer vos notifications

Les applications sont responsables de la suppression et de l’effacement de leurs propres notifications. Lorsque votre application est lancée, nous n’effacez PAS automatiquement vos notifications.

Windows supprime automatiquement une notification uniquement si l’utilisateur clique explicitement sur la notification.

Voici un exemple de ce qu’une application de messagerie doit faire...

  1. L’utilisateur reçoit plusieurs toasts sur les nouveaux messages dans une conversation
  2. L’utilisateur appuie sur l’un de ces toasts pour ouvrir la conversation
  3. L’application ouvre la conversation, puis efface tous les toasts pour cette conversation (à l’aide de RemoveGroup sur le groupe fourni par l’application pour cette conversation)
  4. Le Centre de notifications de l’utilisateur reflète désormais correctement l’état de notification, car il n’y a plus de notifications obsolètes pour cette conversation dans le Centre de notifications.

Pour en savoir plus sur l’effacement de toutes les notifications ou la suppression de notifications spécifiques, consultez Démarrage rapide : Gestion des notifications toast dans le centre de notifications (XAML) .

ToastNotificationManagerCompat::History->Clear();

Ressources