Udostępnij przez

Wysyłanie powiadomienia lokalnego app z aplikacji platformy UWP w języku C++

Powiadomienie app to komunikat, który app może skonstruować i dostarczyć użytkownikowi, gdy nie znajdują się obecnie w twojej aplikacji app.

app Zrzut ekranu przedstawiający powiadomienie

Ten przewodnik Szybki start przeprowadzi Cię przez kroki tworzenia, dostarczania i wyświetlania powiadomienia systemu Windows 10 lub Windows 11 app przy użyciu rozbudowanej zawartości i akcji interaktywnych. W tym przewodniku szybkiego startu używane są powiadomienia lokalne, które najłatwiej zaimplementować. Wszystkie typy aplikacji (WPF, UWP, WinForms, konsola) mogą wysyłać powiadomienia!

Note

Termin "toast powiadomienie" jest zastępowany "app powiadomienie". Te dwa terminy odnoszą się do tej samej funkcji systemu Windows, ale z czasem wycofamy użycie "toast powiadomienia" w dokumentacji.

Important

Jeśli piszesz język C++ spoza platformy UWP app, zapoznaj się z dokumentacją biblioteki WRL języka C++ . Jeśli piszesz język C# app, zapoznaj się z dokumentacją języka C#.

Krok 1. Instalowanie pakietu NuGet

Powiadomienia można tworzyć app za pomocą składni konstruktora zestawu narzędzi Windows Community Toolkit (WCT) LUB przy użyciu kodu XML. Jeśli wolisz to drugie, przejdź do Krok 2 i odnieś się do przykładów kodu bez składni typu builder.

W rozwiązaniu programu Visual Studio kliknij prawym przyciskiem myszy projekt, kliknij pozycję "Zarządzaj pakietami NuGet..." i wyszukaj i zainstaluj Microsoft.Toolkit.Uwp.Notifications w wersji 7.0 lub nowszej.

Przykłady kodu dla naszego Buildera użyją składni z tego pakietu. Ten pakiet umożliwia tworzenie app powiadomień bez użycia kodu XML.

Krok 2. Dodawanie deklaracji przestrzeni nazw

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

Krok 3. Wysyłanie app powiadomienia

W systemach Windows 10 i Windows 11 app zawartość powiadomień jest opisywana przy użyciu języka adaptacyjnego, który zapewnia dużą elastyczność w sposobie wyglądu powiadomienia. Aby uzyskać więcej informacji, zobacz dokumentację App zawartości powiadomień .

Zaczniemy od prostego powiadomienia tekstowego. Skonstruuj zawartość powiadomienia (przy użyciu biblioteki powiadomień) i wyświetl powiadomienie! Należy pamiętać, że przestrzeń nazw to Microsoft.Toolkit.Uwp.Notifications.

proste powiadomienie tekstowe

Jeśli nie używasz składni konstruktora biblioteki powiadomień WCT, zamiast tego skonstruujesz szablon powiadomienia XML app , wypełnisz go tekstem i wartościami, skonstruujesz powiadomienie i pokażesz.

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

Krok 4. Obsługa aktywacji

Gdy użytkownik kliknie powiadomienie (lub przycisk w powiadomieniu z aktywacją w trybie pierwszoplanowym), metoda app w pliku App's .xaml.cpp zostanie wywołana.

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

Musisz zainicjować ramkę i aktywować okno tak jak w kodzie OnLaunched. OnLaunched nie jest uruchamiane, jeśli użytkownik kliknie na powiadomienieapp, nawet jeśli app był zamknięty i jest uruchamiany po raz pierwszy. Często zalecamy połączenie OnLaunched i OnActivated we własną metodę OnLaunchedOrActivated, ponieważ w obu tych przypadkach musi wystąpić ta sama inicjalizacja.

Szczegółowe informacje dotyczące aktywacji

Pierwszym krokiem, aby uczynić powiadomienia interaktywnymi, jest dodanie do nich niektórych argumentów uruchamiania, dzięki czemu app będzie wiedzieć, co uruchomić, gdy użytkownik kliknie powiadomienie (w tym przypadku będziemy zawierać informacje, które później powiedzą nam, że powinniśmy otworzyć konwersację, i będziemy wiedzieli, którą konkretną konwersację otworzyć).

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

Dodawanie obrazów

Możesz dodać bogatą zawartość do powiadomień. Dodamy obraz wbudowany i obraz profilu (app przesłonięcia logo).

Note

Obrazy mogą być używane z pakietu app, lokalnej pamięci app lub z Internetu. W ramach aktualizacji Fall Creators Update obrazy internetowe mogą mieć do 3 MB na zwykłych połączeniach i 1 MB w przypadku połączeń taryfowych. Na urządzeniach, na których nie uruchomiono jeszcze aktualizacji Fall Creators Update, obrazy internetowe nie mogą być większe niż 200 KB.

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

Dodawanie przycisków i danych wejściowych

Możesz dodawać przyciski i dane wejściowe, aby otrzymywać powiadomienia interakcyjne. Przyciski mogą uruchamiać pierwszy plan app, protokół lub zadanie w tle. Dodamy pole tekstowe odpowiedzi, przycisk "Lubię to" i przycisk "Wyświetl", który otwiera obraz.

toast Zrzut ekranu przedstawiający powiadomienie z danymi wejściowymi i przyciskami 
// 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();

Aktywacja przycisków pierwszego planu jest obsługiwana w taki sam sposób, jak główna treść powiadomienia ( Appzostanie wywołana .xaml.cpp OnActivated).

Obsługa aktywacji w tle

Gdy określisz uruchamianie w tle dla swojego powiadomienia app (lub przycisku wewnątrz powiadomienia), zadanie w tle zostanie wykonane zamiast uruchamiania zadania pierwszoplanowego app.

Aby uzyskać więcej informacji na temat zadań w tle, zobacz Wspieraj swój app za pomocą zadań w tle.

Jeśli celujesz w wersję 14393 lub nowszą, możesz użyć zadań w tle w obrębie procesu, które znacznie upraszczają pracę. Należy pamiętać, że zadania w tle w procesie nie będą działać w starszych wersjach systemu Windows. W tym przykładzie kodu użyjemy zadania w tle w ramach procesu.

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

Następnie w App.xaml.cs nadpisz metodę OnBackgroundActivated. Następnie możesz pobrać wstępnie zdefiniowane argumenty i dane wejściowe użytkownika, podobnie jak w przypadku aktywacji na pierwszym planie.

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

Ustawianie czasu wygaśnięcia

W systemie Windows 10 i 11 wszystkie app powiadomienia trafiają do Centrum akcji po ich odrzuceniu lub zignorowaniu przez użytkownika, aby użytkownicy mogli przeglądać powiadomienia po zniknięciu okienka.

Jeśli jednak komunikat w powiadomieniu jest istotny tylko przez pewien czas, należy ustawić czas wygaśnięcia na powiadomieniu app, aby użytkownicy nie widzieli nieaktualnych informacji z app. Jeśli na przykład promocja jest ważna tylko przez 12 godzin, ustaw czas wygaśnięcia na 12 godzin. W poniższym kodzie ustawiliśmy czas wygaśnięcia na 2 dni.

Note

Domyślny i maksymalny czas wygaśnięcia dla powiadomień lokalnych app wynosi 3 dni.

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

Podaj klucz podstawowy dla app powiadomienia

Jeśli chcesz programowo usunąć lub zamienić wysyłane powiadomienie, musisz użyć właściwości Tag (i opcjonalnie właściwości Grupa), aby podać klucz podstawowy powiadomienia. Następnie możesz użyć tego klucza podstawowego w przyszłości, aby usunąć lub zamienić powiadomienie.

Aby uzyskać więcej informacji na temat zastępowania/usuwania już dostarczonych app powiadomień, zobacz Szybki start: zarządzanie powiadomieniami toast w centrum akcji (XAML).

Tag i grupa łączone działają jako złożony klucz podstawowy. Grupa to bardziej ogólny identyfikator, w którym można przypisywać grupy, takie jak "wallPosts", "messages", "friendRequests" itp. Następnie tag powinien jednoznacznie zidentyfikować samo powiadomienie z grupy. Korzystając z grupy ogólnej, można usunąć wszystkie powiadomienia z tej grupy przy użyciu interfejsu 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";
    });

Wyczyść powiadomienia

Aplikacje są odpowiedzialne za usuwanie i czyszczenie własnych powiadomień. Po uruchomieniu app nie usuwamy automatycznie powiadomień.

System Windows automatycznie usunie powiadomienie tylko wtedy, gdy użytkownik jawnie kliknie powiadomienie.

Oto przykład działania komunikatów app ...

  1. Użytkownik otrzymuje wiele app powiadomień o nowych wiadomościach w konwersacji
  2. Użytkownik dotknie jedno z tych powiadomień, aby otworzyć konwersację
  3. Element app otwiera konwersację, a następnie wyczyszcza wszystkie powiadomienia dotyczące tej konwersacji (przy użyciu polecenia RemoveGroup na grupie dostarczonej przez app dla tej konwersacji)
  4. Centrum akcji użytkownika teraz prawidłowo odzwierciedla stan powiadomienia, ponieważ w Centrum akcji nie ma już nieaktualnych powiadomień dla tej konwersacji.

Aby dowiedzieć się więcej na temat czyszczenia wszystkich powiadomień lub usuwania określonych powiadomień, zobacz Szybki start: zarządzanie powiadomieniami toast w centrum akcji (XAML).

ToastNotificationManagerCompat::History->Clear();

Resources

  • Last updated on