Bagikan melalui

Bilah kemajuan toast dan pengikatan data

  • Artikel

Menggunakan bilah kemajuan di dalam pemberitahuan toast memungkinkan Anda untuk menyampaikan status operasi jangka panjang kepada pengguna, seperti unduhan, penyajian video, tujuan latihan, dan banyak lagi.

Penting

Memerlukan Pembaruan Pembuat dan pustaka Pemberitahuan 1.4.0: Anda harus menargetkan SDK 15063 dan menjalankan build 15063 atau yang lebih baru untuk menggunakan bilah kemajuan pada toast. Anda harus menggunakan versi 1.4.0 atau yang lebih baru dari pustaka NuGet Pemberitahuan Toolkit Komunitas UWP untuk membuat bilah kemajuan dalam konten toast Anda.

Bilah kemajuan di dalam roti panggang dapat "tidak ditentukan" (tidak ada nilai tertentu, titik animasi menunjukkan operasi sedang terjadi) atau "menentukan" (persentase tertentu dari bilah diisi, seperti 60%).

API Penting: Kelas NotificationData, metode ToastNotifier.Update, kelas ToastNotification

Catatan

Hanya Desktop yang mendukung bilah kemajuan dalam pemberitahuan toast. Di perangkat lain, bilah kemajuan akan dihilangkan dari pemberitahuan Anda.

Gambar di bawah ini memperlihatkan bilah kemajuan penentuan dengan semua properti terkait berlabel.

Toast dengan properti bilah kemajuan berlabel
Properti Tipe Wajib Deskripsi
Judul string atau BindableString salah Mendapatkan atau mengatur string judul opsional. Mendukung pengikatan data.
Nilai double atau AdaptiveProgressBarValue atau BindableProgressBarValue salah Mendapatkan atau mengatur nilai bilah kemajuan. Mendukung pengikatan data. Default ke 0. Dapat berupa ganda antara 0,0 dan 1,0, AdaptiveProgressBarValue.Indeterminate, atau new BindableProgressBarValue("myProgressValue").
ValueStringOverride string atau BindableString salah Mendapatkan atau mengatur string opsional yang akan ditampilkan alih-alih string persentase default. Jika ini tidak disediakan, sesuatu seperti "70%" akan ditampilkan.
Keadaan string atau BindableString benar Mendapatkan atau mengatur string status (diperlukan), yang ditampilkan di bawah bilah kemajuan di sebelah kiri. String ini harus mencerminkan status operasi, seperti "Mengunduh..." atau "Menginstal..."

Berikut adalah cara Anda akan menghasilkan pemberitahuan yang terlihat di atas...

new ToastContentBuilder()
    .AddText("Downloading your weekly playlist...")
    .AddVisualChild(new AdaptiveProgressBar()
    {
        Title = "Weekly playlist",
        Value = 0.6,
        ValueStringOverride = "15/26 songs",
        Status = "Downloading..."
    });

Namun, Anda harus memperbarui nilai bilah kemajuan secara dinamis agar benar-benar "langsung". Ini dapat dilakukan dengan menggunakan pengikatan data untuk memperbarui toast.

Menggunakan pengikatan data untuk memperbarui toast

Menggunakan pengikatan data melibatkan langkah-langkah berikut...

  1. Membuat konten toast yang menggunakan bidang terikat data
  2. Menetapkan Tag (dan secara opsional Grup) ke ToastNotification Anda
  3. Tentukan nilai Data awal Anda di ToastNotification Anda
  4. Kirim roti panggang
  5. Menggunakan Tag dan Grup untuk memperbarui nilai Data dengan nilai baru

Cuplikan kode berikut menunjukkan langkah 1-4. Cuplikan berikutnya akan menunjukkan cara memperbarui nilai Data toast.

using Windows.UI.Notifications;
using Microsoft.Toolkit.Uwp.Notifications;
 
public void SendUpdatableToastWithProgress()
{
    // Define a tag (and optionally a group) to uniquely identify the notification, in order update the notification data later;
    string tag = "weekly-playlist";
    string group = "downloads";
 
    // Construct the toast content with data bound fields
    var content = new ToastContentBuilder()
        .AddText("Downloading your weekly playlist...")
        .AddVisualChild(new AdaptiveProgressBar()
        {
            Title = "Weekly playlist",
            Value = new BindableProgressBarValue("progressValue"),
            ValueStringOverride = new BindableString("progressValueString"),
            Status = new BindableString("progressStatus")
        })
        .GetToastContent();
 
    // Generate the toast notification
    var toast = new ToastNotification(content.GetXml());
 
    // Assign the tag and group
    toast.Tag = tag;
    toast.Group = group;
 
    // Assign initial NotificationData values
    // Values must be of type string
    toast.Data = new NotificationData();
    toast.Data.Values["progressValue"] = "0.6";
    toast.Data.Values["progressValueString"] = "15/26 songs";
    toast.Data.Values["progressStatus"] = "Downloading...";
 
    // Provide sequence number to prevent out-of-order updates, or assign 0 to indicate "always update"
    toast.Data.SequenceNumber = 1;
 
    // Show the toast notification to the user
    ToastNotificationManager.CreateToastNotifier().Show(toast);
}

Kemudian, saat Anda ingin mengubah nilai Data, gunakan metode Perbarui untuk menyediakan data baru tanpa membuat ulang seluruh payload toast.

using Windows.UI.Notifications;
 
public void UpdateProgress()
{
    // Construct a NotificationData object;
    string tag = "weekly-playlist";
    string group = "downloads";
 
    // Create NotificationData and make sure the sequence number is incremented
    // since last update, or assign 0 for updating regardless of order
    var data = new NotificationData
    {
        SequenceNumber = 2
    };

    // Assign new values
    // Note that you only need to assign values that changed. In this example
    // we don't assign progressStatus since we don't need to change it
    data.Values["progressValue"] = "0.7";
    data.Values["progressValueString"] = "18/26 songs";

    // Update the existing notification's data by using tag/group
    ToastNotificationManager.CreateToastNotifier().Update(data, tag, group);
}

Menggunakan metode Perbarui daripada mengganti seluruh roti panggang juga memastikan bahwa pemberitahuan roti panggang tetap berada di posisi yang sama di Pusat Tindakan dan tidak bergerak ke atas atau ke bawah. Akan sangat membingungkan bagi pengguna jika roti panggang terus melompat ke bagian atas Pusat Tindakan setiap beberapa detik saat bilah kemajuan terisi!

Metode Pembaruan mengembalikan enum, NotificationUpdateResult, yang memungkinkan Anda mengetahui apakah pembaruan berhasil atau apakah pemberitahuan tidak dapat ditemukan (yang berarti pengguna kemungkinan telah menutup pemberitahuan Anda dan Anda harus berhenti mengirim pembaruan ke dalamnya). Kami tidak menyarankan untuk memunculkan toast lain hingga operasi kemajuan Anda selesai (seperti ketika unduhan selesai).

Elemen yang mendukung pengikatan data

Elemen berikut dalam pemberitahuan toast mendukung pengikatan data

  • Semua properti di AdaptiveProgress
  • Properti Teks pada elemen AdaptiveText tingkat atas

Memperbarui atau mengganti pemberitahuan

Karena Windows 10, Anda selalu dapat mengganti pemberitahuan dengan mengirim toast baru dengan Tag dan Grup yang sama. Jadi apa perbedaan antara mengganti roti panggang dan memperbarui data toast?

Mengganti Memperbarui
Posisi di Pusat Tindakan Memindahkan pemberitahuan ke bagian atas Pusat Tindakan. Membiarkan pemberitahuan di tempat dalam Pusat Tindakan.
Memodifikasi konten Dapat sepenuhnya mengubah semua konten/tata letak roti panggang Hanya dapat mengubah properti yang mendukung pengikatan data (bilah kemajuan dan teks tingkat atas)
Muncul kembali sebagai popup Dapat muncul kembali sebagai popup roti panggang jika Anda membiarkan SuppressPopup diatur ke false (atau diatur ke true untuk mengirimnya secara diam-diam ke Pusat Tindakan) Tidak akan muncul kembali sebagai popup; data toast diperbarui secara diam-diam dalam Pusat Tindakan
Pengguna diberhentikan Terlepas dari apakah pengguna menutup pemberitahuan Anda sebelumnya, roti panggang pengganti Anda akan selalu dikirim Jika pengguna menutup toast Anda, pembaruan roti panggang akan gagal

Secara umum, pembaruan berguna untuk...

  • Informasi yang sering berubah dalam waktu singkat dan tidak perlu dibawa ke depan perhatian pengguna
  • Perubahan halang pada konten toast Anda, seperti mengubah 50% menjadi 65%

Sering kali, setelah urutan pembaruan Anda selesai (seperti file telah diunduh), sebaiknya ganti untuk langkah terakhir, karena...

  • Pemberitahuan akhir Anda kemungkinan memiliki perubahan tata letak drastis, seperti penghapusan bilah kemajuan, penambahan tombol baru, dll
  • Pengguna mungkin telah menutup pemberitahuan kemajuan Anda yang tertunda karena mereka tidak peduli menonton unduhannya, tetapi masih ingin diberi tahu dengan roti panggang popup ketika operasi selesai