Mengirim pemberitahuan toast lokal dari aplikasi C++ UWP

  • Artikel

Pemberitahuan toast adalah pesan bahwa aplikasi Anda dapat membangun dan mengirimkannya kepada pengguna anda saat ini tidak berada di dalam aplikasi Anda.

Cuplikan layar pemberitahuan toast

Mulai cepat ini memanding Anda melalui langkah-langkah untuk membuat, mengirimkan, dan menampilkan pemberitahuan toast Windows 10 atau Windows 11 menggunakan konten yang kaya dan tindakan interaktif. Mulai cepat ini menggunakan pemberitahuan lokal, yang merupakan pemberitahuan paling sederhana untuk diterapkan. Semua jenis aplikasi (WPF, UWP, WinForms, konsol) dapat mengirim pemberitahuan!

Penting

Jika Anda menulis aplikasi non-UWP C++, silakan lihat dokumentasi C++ WRL . Jika Anda menulis aplikasi C#, silakan lihat dokumentasi C#.

Langkah 1: Instal paket NuGet

Anda dapat membuat pemberitahuan toast dengan sintaks penyusun Windows Community Toolkit (WCT) ATAU dengan XML. Jika Anda lebih suka yang terakhir, silakan lewati ke Langkah 2 dan lihat contoh kode sintaks tanpa penyusun .

Dalam solusi Visual Studio Anda, klik kanan proyek Anda, klik "Kelola Paket NuGet..." dan cari dan instal Microsoft.Toolkit.Uwp.Notificationspaket NuGet versi 7.0 atau yang lebih baru.

Contoh kode sintaks Builder kami akan menggunakan paket ini. Paket ini memungkinkan Anda membuat pemberitahuan toast tanpa menggunakan XML.

Langkah 2: Menambahkan deklarasi namespace

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

Langkah 3: Kirim roti panggang

Dalam Windows 10 dan Windows 11, konten pemberitahuan toast Anda dijelaskan menggunakan bahasa adaptif yang memungkinkan fleksibilitas besar dengan tampilan pemberitahuan Anda. Untuk informasi selengkapnya, lihat dokumentasi konten toast.

Kita akan mulai dengan pemberitahuan berbasis teks sederhana. Buat konten pemberitahuan (menggunakan pustaka Pemberitahuan), dan tampilkan pemberitahuan! Perhatikan bahwa namespace adalah Microsoft.Toolkit.Uwp.Notifications.

Pemberitahuan teks sederhana

Jika Anda tidak menggunakan sintaks penyusun pustaka Pemberitahuan WCT, Anda akan membuat templat toast XML, mengisinya dengan teks dan nilai, membuat pemberitahuan, dan menampilkannya.

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

Langkah 4: Menangani aktivasi

Saat pengguna mengklik pemberitahuan Anda (atau tombol pada pemberitahuan dengan aktivasi latar depan), App.xaml.cppOnActivated aplikasi Anda akan dipanggil.

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
    }
}

Penting

Anda harus menginisialisasi bingkai dan mengaktifkan jendela seperti kode OnLaunched Anda. OnLaunched TIDAK dipanggil jika pengguna mengklik toast Anda, bahkan jika aplikasi Anda ditutup dan diluncurkan untuk pertama kalinya. Kami sering merekomendasikan untuk menggabungkan OnLaunched dan OnActivated ke dalam metode Anda sendiri OnLaunchedOrActivated karena inisialisasi yang sama perlu terjadi di keduanya.

Aktivasi secara mendalam

Langkah pertama dalam membuat pemberitahuan Anda dapat ditindaklanjuti adalah menambahkan beberapa argumen peluncuran ke pemberitahuan Anda, sehingga aplikasi Anda dapat mengetahui apa yang harus diluncurkan saat pengguna mengklik pemberitahuan (dalam hal ini, kami menyertakan beberapa informasi yang kemudian memberi tahu kami bahwa kami harus membuka percakapan, dan kami tahu percakapan khusus mana yang akan dibuka).

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

Menambahkan gambar

Anda dapat menambahkan konten kaya ke pemberitahuan. Kami akan menambahkan gambar sebaris dan gambar profil (penimpaan logo aplikasi).

Catatan

Gambar dapat digunakan dari paket aplikasi, penyimpanan lokal aplikasi, atau dari web. Pada Pembaruan Fall Creators, gambar web dapat mencapai 3 MB pada koneksi normal dan 1 MB pada koneksi terukur. Pada perangkat yang belum menjalankan Pembaruan Fall Creators, gambar web tidak boleh lebih besar dari 200 KB.

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

Menambahkan tombol dan input

Anda dapat menambahkan tombol dan input untuk membuat pemberitahuan Anda interaktif. Tombol dapat meluncurkan aplikasi latar depan, protokol, atau tugas latar belakang Anda. Kita akan menambahkan kotak teks balasan, tombol "Suka", dan tombol "Tampilan" yang membuka gambar.

Cuplikan layar pemberitahuan toast dengan input dan tombol 
// 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();

Aktivasi tombol latar depan ditangani dengan cara yang sama seperti isi roti panggang utama (App.xaml.cpp OnActivated Anda akan dipanggil).

Menangani aktivasi latar belakang

Saat Anda menentukan aktivasi latar belakang pada roti panggang Anda (atau pada tombol di dalam roti panggang), tugas latar belakang Anda akan dijalankan alih-alih mengaktifkan aplikasi latar depan Anda.

Untuk informasi selengkapnya tentang tugas latar belakang, silakan lihat Mendukung aplikasi Anda dengan tugas latar belakang.

Jika Anda menargetkan build 14393 atau yang lebih baru, Anda dapat menggunakan tugas latar belakang dalam proses, yang sangat menyederhanakan berbagai hal. Perhatikan bahwa tugas latar belakang dalam proses akan gagal berjalan pada versi Windows yang lebih lama. Kita akan menggunakan tugas latar belakang dalam proses dalam sampel kode ini.

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

Kemudian di App.xaml.cs Anda, ganti metode OnBackgroundActivated. Anda kemudian dapat mengambil argumen yang telah ditentukan sebelumnya dan input pengguna, mirip dengan aktivasi latar depan.

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

Mengatur waktu kedaluwarsa

Di Windows 10 dan 11, semua pemberitahuan toast masuk ke Pusat Tindakan setelah ditutup atau diabaikan oleh pengguna, sehingga pengguna dapat melihat pemberitahuan Anda setelah popup hilang.

Namun, jika pesan di pemberitahuan Anda hanya relevan untuk jangka waktu tertentu, Anda harus mengatur waktu kedaluwarsa pada pemberitahuan toast sehingga pengguna tidak melihat informasi kedaluwarsa dari aplikasi Anda. Misalnya, jika promosi hanya berlaku selama 12 jam, atur waktu kedaluwarsa menjadi 12 jam. Dalam kode di bawah ini, kami mengatur waktu kedaluwarsa menjadi 2 hari.

Catatan

Waktu kedaluwarsa default dan maksimum untuk pemberitahuan toast lokal adalah 3 hari.

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

Menyediakan kunci primer untuk roti panggang Anda

Jika Anda ingin menghapus atau mengganti pemberitahuan yang Anda kirim secara terprogram, Anda perlu menggunakan properti Tag (dan secara opsional properti Grup) untuk menyediakan kunci utama untuk pemberitahuan Anda. Kemudian, Anda dapat menggunakan kunci utama ini di masa mendatang untuk menghapus atau mengganti pemberitahuan.

Untuk melihat detail selengkapnya tentang mengganti/menghapus pemberitahuan toast yang sudah dikirimkan, silakan lihat Mulai Cepat: Mengelola pemberitahuan toast di pusat tindakan (XAML).

Gabungan Tag dan Grup bertindak sebagai kunci primer komposit. Grup adalah pengidentifikasi yang lebih umum, di mana Anda dapat menetapkan grup seperti "wallPosts", "pesan", "friendRequests", dll. Lalu Tag harus secara unik mengidentifikasi pemberitahuan itu sendiri dari dalam grup. Dengan menggunakan grup generik, Anda kemudian dapat menghapus semua pemberitahuan dari grup tersebut dengan menggunakan 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";
    });

Menghapus pemberitahuan Anda

Aplikasi bertanggung jawab untuk menghapus dan menghapus pemberitahuan mereka sendiri. Saat aplikasi Anda diluncurkan, kami TIDAK secara otomatis menghapus pemberitahuan Anda.

Windows hanya akan otomatis menghapus pemberitahuan jika pengguna secara eksplisit mengklik pemberitahuan.

Berikut adalah contoh apa yang harus dilakukan aplikasi olahpesan...

  1. Pengguna menerima beberapa toast tentang pesan baru dalam percakapan
  2. Pengguna mengetuk salah satu toast tersebut untuk membuka percakapan
  3. Aplikasi membuka percakapan lalu menghapus semua toast untuk percakapan tersebut (dengan menggunakan RemoveGroup pada grup yang disediakan aplikasi untuk percakapan tersebut)
  4. Pusat Tindakan Pengguna sekarang mencerminkan status pemberitahuan dengan benar, karena tidak ada pemberitahuan kedaluarsa untuk percakapan yang tersisa di Pusat Tindakan.

Untuk mempelajari tentang menghapus semua pemberitahuan atau menghapus pemberitahuan tertentu, lihat Mulai Cepat: Mengelola pemberitahuan toast di pusat tindakan (XAML).

ToastNotificationManagerCompat::History->Clear();

Sumber