Compartir a través de

Enviar una notificación local app desde aplicaciones para UWP de C++

Una app notificación es un mensaje que app puede construir y entregar al usuario mientras no se encuentra dentro de app.

Captura de pantalla de una app notificación

Este inicio rápido le guía por los pasos para crear, entregar y mostrar una notificación de Windows 10 o Windows 11 app con contenido enriquecido y acciones interactivas. En este inicio rápido se usan las notificaciones locales, que son las más sencillas de implementar. ¡Todos los tipos de aplicaciones (WPF, UWP, WinForms, consola) pueden enviar notificaciones!

Note

El término "toast notificación" se va a reemplazar por "app notification". Estos términos hacen referencia a la misma característica de Windows, pero con el tiempo se eliminará el uso de "toast notificación" en la documentación.

Important

Si escribes un C++ que no sea para UWP app, consulta la documentación de WRL de C++ . Si está escribiendo un C# app, consulte la documentación de C#.

Paso 1: Instalación del paquete NuGet

Puede crear app notificaciones con la sintaxis del generador de Windows Community Toolkit (WCT) O con XML. Si prefiere esta última opción, salte al paso 2 y consulte los ejemplos de código en sin la sintaxis del generador.

En la solución de Visual Studio, haga clic con el botón derecho en el proyecto, haga clic en "Administrar paquetes NuGet..." y busque e instale la versión 7.0 o posterior del Microsoft.Toolkit.Uwp.Notificationspaquete NuGet.

Nuestros ejemplos de código de sintaxis de Builder usarán este paquete. Este paquete permite crear app notificaciones sin usar XML.

Paso 2: Agregar declaraciones de espacio de nombres

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

Paso 3: Enviar una app notificación

En Windows 10 y Windows 11, el app contenido de la notificación se describe mediante un lenguaje adaptable que permite una gran flexibilidad con el aspecto de la notificación. Para obtener más información, consulte la documentación sobre el contenido de la notificación.

Comenzaremos con una notificación sencilla basada en texto. Construya el contenido de la notificación (mediante la biblioteca de notificaciones) y muestre la notificación. Tenga en cuenta que el espacio de nombres es Microsoft.Toolkit.Uwp.Notifications.

Notificación de texto simple

Si no usa la sintaxis del generador de bibliotecas de notificaciones de WCT, construirá la plantilla de notificación XML app , la rellenará con texto y valores, construirá la notificación y la 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();

Paso 4: Controlar la activación

Cuando el usuario hace clic en tu notificación (o en un botón de la notificación con activación en primer plano), app invocará el método App.xaml.cppOnActivated.

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

Debe inicializar el marco y activar la ventana de la misma manera que el código de OnLaunched. No se llama a OnLaunched si el usuario hace clic en tu app notificación, incluso si tu se cerró y se inicia por primera vez. A menudo recomendamos combinar OnLaunched y OnActivated en su propio método OnLaunchedOrActivated, ya que la misma inicialización debe producirse en ambos.

Activación en profundidad

El primer paso para hacer que las notificaciones sean accionables es agregar algunos argumentos de inicio a la notificación, de modo que app pueda saber qué iniciar cuando el usuario hace clic en la notificación (en este caso, se incluye cierta información que más adelante nos indica que deberíamos abrir una conversación y sabemos qué conversación 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();

Agregar imágenes

Puede agregar contenido enriquecido a las notificaciones. Agregaremos una imagen insertada y una imagen de perfil (app anulación del logotipo).

Note

Las imágenes se pueden usar desde el paquete del app, el almacenamiento local del app, o desde la web. A partir de la actualización Fall Creators, las imágenes web pueden tener hasta 3 MB en conexiones normales y 1 MB en conexiones medidas. En los dispositivos que aún no ejecutan Fall Creators Update, las imágenes web no deben tener más de 200 KB.

Toast con imágenes 
// 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();

Agregar botones y entradas

Puede agregar botones y entradas para que las notificaciones sean interactivas. Los botones pueden iniciar el primer plano app, un protocolo o la tarea en segundo plano. Agregaremos un cuadro de texto de respuesta, un botón "Like" y un botón "Ver" que abre la imagen.

Captura de pantalla de una toast notificación con entradas y botones 
// 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();

La activación de botones en primer plano se controla de la misma manera que el cuerpo de la notificación principal, se llamará a tu App.xaml.cpp OnActivated.

Controlar la activación en segundo plano

Al especificar la activación en segundo plano en la app notificación (o en un botón dentro de la notificación), la tarea en segundo plano se ejecutará en lugar de activar el primer plano app.

Para obtener más información sobre las tareas en segundo plano, consulte Apoye su app con tareas en segundo plano.

Si tiene como destino la compilación 14393 o posterior, puede usar tareas en segundo plano en proceso, lo que simplifica considerablemente las cosas. Tenga en cuenta que las tareas en segundo plano en proceso no se ejecutarán en versiones anteriores de Windows. Usaremos una tarea en segundo plano en proceso en este ejemplo 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();

A continuación, en el App.xaml.cs, invalide el método OnBackgroundActivated. A continuación, puede recuperar los argumentos predefinidos y la entrada del usuario, similar a la activación en primer 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();
}

Establecer una hora de expiración

En Windows 10 y 11, todas las app notificaciones van en el Centro de actividades una vez descartadas o ignoradas por el usuario, por lo que los usuarios pueden ver la notificación después de que el elemento emergente haya desaparecido.

Sin embargo, si el mensaje de la notificación solo es relevante durante un período de tiempo, debe establecer una hora de expiración en la app notificación para que los usuarios no vean información obsoleta de su app. Por ejemplo, si una promoción solo es válida durante 12 horas, establezca el tiempo de expiración en 12 horas. En el código siguiente, establecemos el tiempo de expiración en 2 días.

Note

El tiempo de expiración predeterminado y máximo para las notificaciones locales app es de 3 días.

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

Proporcione una clave principal para la app notificación.

Si desea quitar o reemplazar mediante programación la notificación que envía, debe usar la propiedad Tag (y, opcionalmente, la propiedad Group) para proporcionar una clave principal para la notificación. A continuación, puede usar esta clave principal en el futuro para quitar o reemplazar la notificación.

Para ver más detalles sobre cómo reemplazar o quitar notificaciones ya entregadasapp, consulta Inicio rápido: Administración toast de notificaciones en el centro de actividades (XAML).

La etiqueta y el grupo combinados actúan como una clave principal compuesta. El grupo es el identificador más genérico, donde puede asignar grupos como "wallPosts", "messages", "friendRequests", etc. Y, a continuación, Tag debe identificar de forma única la notificación desde dentro del grupo. Mediante el uso de un grupo genérico, puede quitar todas las notificaciones de ese grupo mediante el RemoveGroup API.

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

Borrar las notificaciones

Las aplicaciones son responsables de quitar y borrar sus propias notificaciones. Cuando se lanza tu app, NO borramos automáticamente las notificaciones.

Windows solo quitará automáticamente una notificación si el usuario hace clic explícitamente en la notificación.

Este es un ejemplo de lo que debe hacer un sistema de mensajería app ...

  1. El usuario recibe varias app notificaciones sobre los nuevos mensajes de una conversación
  2. El usuario pulsa una de esas notificaciones para abrir la conversación
  3. app abre la conversación y, a continuación, borra todas las notificaciones de esa conversación (mediante RemoveGroup en el appgrupo proporcionado para esa conversación).
  4. El Centro de actividades ahora refleja correctamente el estado de las notificaciones, ya que no quedan notificaciones obsoletas para esa conversación en el Centro de actividades.

Para obtener información sobre cómo borrar todas las notificaciones o quitar notificaciones específicas, consulta Inicio rápido: Administración toast de notificaciones en el centro de actividades (XAML).

ToastNotificationManagerCompat::History->Clear();

Resources

  • Last updated on