Dela via

Skicka ett lokalt app meddelande från C++ UWP-appar

Ett app meddelande är ett meddelande som du app kan skapa och leverera till användaren medan de för närvarande inte finns i .app

Skärmbild av ett app meddelande

Den här snabbstarten vägleder dig genom stegen för att skapa, leverera och visa ett Windows 10- eller Windows 11-meddelande app med omfattande innehåll och interaktiva åtgärder. Den här snabbstarten använder lokala meddelanden, som är det enklaste meddelandet att implementera. Alla typer av appar (WPF, UWP, WinForms, konsol) kan skicka meddelanden!

Note

Termen "toast meddelande" ersätts med "app notification". Båda dessa termer refererar till samma funktion i Windows, men med tiden kommer vi att fasa ut användningen av "toast meddelande" i dokumentationen.

Important

Om du skriver en C++ icke-UWP appkan du läsa C++ WRL-dokumentationen . Om du skriver en C# appkan du läsa C#-dokumentationen.

Steg 1: Installera NuGet-paketet

Du kan skapa app meddelanden med Windows Community Toolkit (WCT) builder syntax ELLER med XML. Om du föredrar det senare går du vidare till steg 2 och läser Utan builder-syntax kodexempel.

Högerklicka på ditt projekt i Visual Studio-lösningen, klicka på "Hantera NuGet-paket..." och sök efter och installera Microsoft.Toolkit.Uwp.NotificationsNuGet-paketet version 7.0 eller senare.

Våra exempel på builder-syntaxkod använder det här paketet. Med det här paketet kan du skapa app meddelanden utan att använda XML.

Steg 2: Lägga till namnområdesdeklarationer

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

Steg 3: Skicka ett app meddelande

I Windows 10 och Windows 11 beskrivs ditt app meddelandeinnehåll med ett anpassningsbart språk som ger stor flexibilitet med hur meddelandet ser ut. Mer information finns i dokumentationen om App meddelandeinnehåll .

Vi börjar med ett enkelt textbaserat meddelande. Skapa meddelandeinnehållet (med hjälp av meddelandebiblioteket) och visa meddelandet! Observera att namnområdet är Microsoft.Toolkit.Uwp.Notifications.

Enkel textavisering

Om du inte använder builder-syntaxen för WCT Notifications-biblioteket skapar du i stället XML-meddelandemallen app , fyller den med text och värden, skapar meddelandet och visar det.

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

Steg 4: Hantera aktivering

När användaren klickar på ditt meddelande (eller en knapp i meddelandet med förgrundsaktivering) anropas App din app.xaml.cpp OnActivated.

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

Du måste initiera ramen och aktivera fönstret precis som din OnLaunched kod. OnLaunched anropas INTE om användaren klickar på din app avisering, även om din app stängdes och startas för första gången. Vi rekommenderar ofta att du kombinerar OnLaunched och OnActivated i din egen OnLaunchedOrActivated metod eftersom samma initiering måste ske i båda.

Aktivering på djupet

Det första steget för att göra dina meddelanden användbara är att lägga till några start args i ditt meddelande, så att du app kan veta vad du ska starta när användaren klickar på meddelandet (i det här fallet inkluderar vi viss information som senare talar om för oss att vi ska öppna en konversation och vi vet vilken specifik konversation som ska öppnas).

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

Add images

Du kan lägga till omfattande innehåll i meddelanden. Vi lägger till en infogad bild och en profilbild (app åsidosättning av logotyp).

Note

Bilder kan användas från app's-paketet, den lokala lagringen appeller från webben. Från och med Fall Creators Update kan webbilder vara upp till 3 MB för vanliga anslutningar och 1 MB på mätade anslutningar. På enheter som ännu inte kör Fall Creators Update får webbbilderna inte vara större än 200 kB.

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

Lägga till knappar och indata

Du kan lägga till knappar och indata för att göra dina meddelanden interaktiva. Knappar kan starta förgrunden app, ett protokoll eller bakgrundsaktiviteten. Vi lägger till en svarstextruta, en "Gilla"-knapp och en "Visa"-knapp som öppnar bilden.

Skärmbild av ett toast meddelande med indata och knappar 
// 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();

Aktiveringen av förgrundsknappar hanteras på samma sätt som huvudmeddelandetexten (din App.xaml.cpp OnActivated anropas).

Hantera bakgrundsaktivering

När du anger bakgrundsaktivering för ditt app meddelande (eller på en knapp i meddelandet) körs bakgrundsaktiviteten i stället för att aktivera förgrunden app.

Mer information om bakgrundsaktiviteter finns i Support your with background tasks (Stöd för bakgrundsaktiviteterapp).

Om du riktar in dig på version 14393 eller senare kan du använda pågående bakgrundsaktiviteter, vilket förenklar saker och ting avsevärt. Observera att pågående bakgrundsaktiviteter inte kan köras på äldre versioner av Windows. Vi använder en pågående bakgrundsaktivitet i det här kodexemplet.

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

Åsidosätt sedan metoden OnBackgroundActivated i din App.xaml.cs. Du kan sedan hämta parametrarna och användarindatan som är fördefinierade, liknande förgrundsaktiveringen.

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

Ange en förfallotid

I Windows 10 och 11 går alla app meddelanden i Åtgärdscenter när de har stängts eller ignorerats av användaren, så att användarna kan titta på ditt meddelande när popup-fönstret är borta.

Men om meddelandet i meddelandet bara är relevant under en tidsperiod bör du ange en förfallotid app för meddelandet så att användarna inte ser inaktuell information från din app. Om en kampanj till exempel bara är giltig i 12 timmar anger du förfallotiden till 12 timmar. I koden nedan anger vi förfallotiden till 2 dagar.

Note

Standard och maximal förfallotid för lokala app meddelanden är 3 dagar.

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

Ange en primärnyckel för ditt app meddelande

Om du vill ta bort eller ersätta meddelandet som du skickar programmatiskt måste du använda egenskapen Tagg (och eventuellt egenskapen Grupp) för att ange en primärnyckel för meddelandet. Sedan kan du använda den här primärnyckeln i framtiden för att ta bort eller ersätta meddelandet.

Mer information om hur du ersätter/tar bort redan levererade app meddelanden finns i Snabbstart: Hantera toast meddelanden i Åtgärdscenter (XAML).

Tagg och grupp tillsammans fungerar som en sammansatt primärnyckel. Grupp är den mer generiska identifieraren, där du kan tilldela grupper som "wallPosts", "messages", "friendRequests" osv. Och sedan bör taggen unikt identifiera själva meddelandet inifrån gruppen. Genom att använda en allmän grupp kan du sedan ta bort alla meddelanden från gruppen med hjälp av RemoveGroup-API:et.

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

Rensa dina meddelanden

Appar ansvarar för att ta bort och rensa sina egna meddelanden. När du app startar rensar vi INTE dina meddelanden automatiskt.

Windows tar bara bort ett meddelande automatiskt om användaren uttryckligen klickar på meddelandet.

Här är ett exempel på vad ett meddelande app ska göra...

  1. Användaren får flera app meddelanden om nya meddelanden i en konversation
  2. Användaren trycker på ett av dessa meddelanden för att öppna konversationen
  3. Öppnar app konversationen och rensar sedan alla meddelanden för konversationen (genom att använda RemoveGroup i gruppen -provided för den konversationen app)
  4. Användarens Åtgärdscenter återspeglar nu meddelandetillståndet korrekt, eftersom det inte finns några inaktuella meddelanden för konversationen kvar i Åtgärdscenter.

Mer information om hur du rensar alla meddelanden eller tar bort specifika meddelanden finns i Snabbstart: Hantera toast meddelanden i Åtgärdscenter (XAML).

ToastNotificationManagerCompat::History->Clear();

Resources