Kontrol dialog

Kontrol dialog adalah overlay UI modal yang menyediakan informasi aplikasi kontekstual. Mereka memblokir interaksi dengan jendela aplikasi hingga diberhentikan secara eksplisit. Mereka sering meminta semacam tindakan dari pengguna.

Apakah ini kontrol yang tepat?

Gunakan dialog untuk memberi tahu pengguna tentang informasi penting atau untuk meminta konfirmasi atau info tambahan sebelum tindakan dapat diselesaikan.

Untuk rekomendasi tentang kapan menggunakan dialog vs. kapan menggunakan flyout (kontrol serupa), lihat Dialog dan flyout.

Panduan umum

• Identifikasi masalah atau tujuan pengguna dengan jelas di baris pertama teks dialog.
• Judul dialog adalah instruksi utama dan bersifat opsional.
  • Gunakan judul singkat untuk menjelaskan apa yang perlu dilakukan orang dengan dialog.
  • Jika Anda menggunakan dialog untuk mengirimkan pesan, kesalahan, atau pertanyaan sederhana, Anda dapat secara opsional menghilangkan judul. Mengandalkan teks konten untuk mengirimkan informasi inti tersebut.
  • Pastikan judul berkaitan langsung dengan pilihan tombol.
• Konten dialog berisi teks deskriptif dan diperlukan.
  • Sajikan pesan, kesalahan, atau pemblokiran pertanyaan sesering mungkin.
  • Jika judul dialog digunakan, gunakan area konten untuk memberikan detail lebih lanjut atau menentukan terminologi. Jangan ulangi judul dengan kata-kata yang sedikit berbeda.
• Setidaknya satu tombol dialog harus muncul.
  • Pastikan dialog Anda memiliki setidaknya satu tombol yang sesuai dengan tindakan yang aman dan tidak merusak seperti "Got it!", "Close", atau "Cancel". Gunakan CLOSEButton API untuk menambahkan tombol ini.
  • Gunakan respons khusus untuk instruksi utama atau konten sebagai teks tombol. Contohnya adalah, "Apakah Anda ingin mengizinkan AppName mengakses lokasi Anda?", diikuti dengan tombol "Izinkan" dan "Blokir". Respons spesifik dapat dipahami lebih cepat, menghasilkan pengambilan keputusan yang efisien.
  • Pastikan bahwa teks tombol tindakan ringkas. String pendek memungkinkan pengguna untuk membuat pilihan dengan cepat dan percaya diri.
  • Selain tindakan aman dan tidak merusak, Anda dapat secara opsional menyajikan pengguna dengan satu atau dua tombol tindakan yang terkait dengan instruksi utama. Tombol tindakan "lakukan" ini mengonfirmasi titik utama dialog. Gunakan API PrimaryButton dan SecondaryButton untuk menambahkan tindakan "lakukan" ini.
  • Tombol tindakan "lakukan" akan muncul sebagai tombol paling kiri. Tindakan aman dan nondestructive akan muncul sebagai tombol paling kanan.
  • Anda dapat secara opsional memilih untuk membedakan salah satu dari tiga tombol sebagai tombol default dialog. Gunakan DefaultButton API untuk membedakan salah satu tombol.
• Jangan gunakan dialog untuk kesalahan yang kontekstual ke tempat tertentu di halaman, seperti kesalahan validasi (di bidang kata sandi, misalnya), gunakan kanvas aplikasi itu sendiri untuk menampilkan kesalahan sebaris.
• Gunakan kelas ContentDialog untuk membangun pengalaman dialog Anda. Jangan gunakan MESSAGEDialog API yang tidak digunakan lagi.

UWP dan WinUI 2

Penting

Informasi dan contoh dalam artikel ini dioptimalkan untuk aplikasi yang menggunakan SDK Aplikasi Windows dan WinUI 3, tetapi umumnya berlaku untuk aplikasi UWP yang menggunakan WinUI 2. Lihat referensi API UWP untuk informasi dan contoh spesifik platform.

Bagian ini berisi informasi yang Anda butuhkan untuk menggunakan kontrol di aplikasi UWP atau WinUI 2.

API untuk kontrol ini ada di namespace Windows.UI.Xaml.Controls .

• API UWP: Kelas ContentDialog
• Buka aplikasi Galeri WinUI 2 dan lihat Tindakan ContentDialog. Aplikasi Galeri WinUI 2 mencakup contoh interaktif dari sebagian besar kontrol, fitur, dan fungsi WinUI 2. Dapatkan aplikasi dari Microsoft Store atau dapatkan kode sumber di GitHub.

Sebaiknya gunakan WinUI 2 terbaru untuk mendapatkan gaya dan templat terbaru untuk semua kontrol. WinUI 2.2 atau yang lebih baru menyertakan templat baru untuk kontrol ini yang menggunakan sudut bulat. Untuk informasi selengkapnya, lihat radius sudut.

Membuat dialog

• API Penting: Kelas ContentDialog

Buka aplikasi Galeri WinUI 3 dan lihat ContentDialog beraksi.

Aplikasi Galeri WinUI 3 mencakup contoh interaktif dari sebagian besar kontrol, fitur, dan fungsi WinUI 3. Dapatkan aplikasi dari Microsoft Store atau dapatkan kode sumber di GitHub

Untuk membuat dialog, Anda menggunakan kelas ContentDialog. Anda dapat membuat dialog dalam kode atau markup. Meskipun biasanya lebih mudah untuk menentukan elemen UI di XAML, dalam kasus dialog sederhana, sebenarnya lebih mudah untuk hanya menggunakan kode. Contoh ini membuat dialog untuk memberi tahu pengguna bahwa tidak ada koneksi WiFi, lalu menggunakan metode ShowAsync untuk menampilkannya.

private async void DisplayNoWifiDialog()
{
    ContentDialog noWifiDialog = new ContentDialog
    {
        Title = "No wifi connection",
        Content = "Check your connection and try again.",
        CloseButtonText = "OK"
    };

    ContentDialogResult result = await noWifiDialog.ShowAsync();
}

Saat pengguna mengklik tombol dialog, metode ShowAsync mengembalikan ContentDialogResult untuk memberi tahu Anda tombol mana yang diklik pengguna.

Dialog dalam contoh ini mengajukan pertanyaan dan menggunakan ContentDialogResult yang dikembalikan untuk menentukan respons pengguna.

private async void DisplayDeleteFileDialog()
{
    ContentDialog deleteFileDialog = new ContentDialog
    {
        Title = "Delete file permanently?",
        Content = "If you delete this file, you won't be able to recover it. Do you want to delete it?",
        PrimaryButtonText = "Delete",
        CloseButtonText = "Cancel"
    };

    ContentDialogResult result = await deleteFileDialog.ShowAsync();

    // Delete the file if the user clicked the primary button.
    /// Otherwise, do nothing.
    if (result == ContentDialogResult.Primary)
    {
        // Delete the file.
    }
    else
    {
        // The user clicked the CloseButton, pressed ESC, Gamepad B, or the system back button.
        // Do nothing.
    }
}

Berikan tindakan yang aman

Karena dialog memblokir interaksi pengguna, dan karena tombol adalah mekanisme utama bagi pengguna untuk menutup dialog, pastikan dialog Anda berisi setidaknya satu tombol "aman" dan nondestruktif seperti "Tutup" atau "Dapatkan!". Semua dialog harus berisi setidaknya satu tombol tindakan aman untuk menutup dialog. Ini memastikan bahwa pengguna dapat dengan percaya diri menutup dialog tanpa melakukan tindakan.

private async void DisplayNoWifiDialog()
{
    ContentDialog noWifiDialog = new ContentDialog
    {
        Title = "No wifi connection",
        Content = "Check your connection and try again.",
        CloseButtonText = "OK"
    };

    ContentDialogResult result = await noWifiDialog.ShowAsync();
}

Ketika dialog digunakan untuk menampilkan pertanyaan pemblokiran, dialog Anda harus menyajikan pengguna dengan tombol tindakan yang terkait dengan pertanyaan. Tombol "aman" dan nondestructive dapat disertai dengan satu atau dua tombol tindakan "do it". Saat menyajikan pengguna dengan beberapa opsi, pastikan bahwa tombol menjelaskan dengan jelas tindakan "lakukan" dan aman/"jangan lakukan" yang terkait dengan pertanyaan yang diusulkan.

private async void DisplayLocationPromptDialog()
{
    ContentDialog locationPromptDialog = new ContentDialog
    {
        Title = "Allow AppName to access your location?",
        Content = "AppName uses this information to help you find places, connect with friends, and more.",
        CloseButtonText = "Block",
        PrimaryButtonText = "Allow"
    };

    ContentDialogResult result = await locationPromptDialog.ShowAsync();
}

Tiga dialog tombol digunakan saat Anda menyajikan pengguna dengan dua tindakan "lakukan" dan tindakan "jangan lakukan". Tiga dialog tombol harus digunakan dengan hemat dengan perbedaan yang jelas antara tindakan sekunder dan tindakan aman/tutup.

private async void DisplaySubscribeDialog()
{
    ContentDialog subscribeDialog = new ContentDialog
    {
        Title = "Subscribe to App Service?",
        Content = "Listen, watch, and play in high definition for only $9.99/month. Free to try, cancel anytime.",
        CloseButtonText = "Not Now",
        PrimaryButtonText = "Subscribe",
        SecondaryButtonText = "Try it"
    };

    ContentDialogResult result = await subscribeDialog.ShowAsync();
}

Tiga tombol dialog

ContentDialog memiliki tiga jenis tombol berbeda yang dapat Anda gunakan untuk membangun pengalaman dialog.

• CloseButton - Wajib - Mewakili tindakan aman dan nondestructive yang memungkinkan pengguna keluar dari dialog. Muncul sebagai tombol paling kanan.
• PrimaryButton - Opsional - Mewakili tindakan "lakukan" pertama. Muncul sebagai tombol paling kiri.
• SecondaryButton - Opsional - Mewakili tindakan "lakukan" kedua. Muncul sebagai tombol tengah.

Menggunakan tombol bawaan akan memposisikan tombol dengan tepat, memastikan bahwa tombol tersebut merespons peristiwa keyboard dengan benar, memastikan bahwa area perintah tetap terlihat bahkan ketika keyboard di layar aktif, dan akan membuat dialog terlihat konsisten dengan dialog lain.

Tutup Tombol

Setiap dialog harus berisi tombol tindakan yang aman dan tidak merusak yang memungkinkan pengguna untuk keluar dari dialog dengan percaya diri.

Gunakan ContentDialog.CloseButton API untuk membuat tombol ini. Ini memungkinkan Anda untuk membuat pengalaman pengguna yang tepat untuk semua input termasuk mouse, keyboard, sentuhan, dan gamepad. Pengalaman ini akan terjadi ketika:

• Pengguna mengklik atau mengetuk CloseButton.
• Pengguna menekan tombol kembali sistem.
• Pengguna menekan tombol ESC pada keyboard.
• Pengguna menekan Gamepad B.

Saat pengguna mengklik tombol dialog, metode ShowAsync mengembalikan ContentDialogResult untuk memberi tahu Anda tombol mana yang diklik pengguna. Menekan CloseButton mengembalikan ContentDialogResult.None.

PrimaryButton dan SecondaryButton

Selain CloseButton, Anda dapat secara opsional menyajikan pengguna dengan satu atau dua tombol tindakan yang terkait dengan instruksi utama. Manfaatkan PrimaryButton untuk tindakan "lakukan" pertama, dan SecondaryButton untuk tindakan "lakukan" kedua. Dalam dialog tiga tombol, PrimaryButton umumnya mewakili tindakan "lakukan" afirmatif, sementara SecondaryButton umumnya mewakili tindakan "lakukan" netral atau sekunder. Misalnya, aplikasi dapat meminta pengguna untuk berlangganan layanan. PrimaryButton sebagai tindakan "lakukan" afirmatif akan menghosting teks Berlangganan, sementara SecondaryButton sebagai tindakan "lakukan" netral akan menghosting teks Coba. CloseButton akan memungkinkan pengguna untuk membatalkan tanpa melakukan salah satu tindakan.

Ketika pengguna mengklik PrimaryButton, metode ShowAsync mengembalikan ContentDialogResult.Primary. Ketika pengguna mengklik SecondaryButton, metode ShowAsync mengembalikan ContentDialogResult.Secondary.

DefaultButton

Anda dapat secara opsional memilih untuk membedakan salah satu dari tiga tombol sebagai tombol default. Menentukan tombol default menyebabkan hal berikut ini terjadi:

• Tombol menerima perawatan visual Tombol Aksen
• Tombol akan merespons tombol ENTER secara otomatis
  • Ketika pengguna menekan tombol ENTER pada keyboard, handler klik yang terkait dengan Tombol Default akan diaktifkan dan ContentDialogResult akan mengembalikan nilai yang terkait dengan Tombol Default
  • Jika pengguna telah menempatkan Fokus Keyboard pada kontrol yang menangani ENTER, Tombol Default tidak akan merespons tekan ENTER
• Tombol akan menerima fokus secara otomatis ketika Dialog dibuka kecuali konten dialog berisi UI yang dapat difokuskan

Gunakan properti ContentDialog.DefaultButton untuk menunjukkan tombol default. Secara default, tidak ada tombol default yang diatur.

private async void DisplaySubscribeDialog()
{
    ContentDialog subscribeDialog = new ContentDialog
    {
        Title = "Subscribe to App Service?",
        Content = "Listen, watch, and play in high definition for only $9.99/month. Free to try, cancel anytime.",
        CloseButtonText = "Not Now",
        PrimaryButtonText = "Subscribe",
        SecondaryButtonText = "Try it",
        DefaultButton = ContentDialogButton.Primary
    };

    ContentDialogResult result = await subscribeDialog.ShowAsync();
}

Dialog konfirmasi (OK/Batal)

Dialog konfirmasi memberi pengguna kesempatan untuk mengonfirmasi bahwa mereka ingin melakukan tindakan. Mereka dapat menegaskan tindakan, atau memilih untuk membatalkan. Dialog konfirmasi umum memiliki dua tombol: tombol afirmasi ("OK") dan tombol batalkan.

• Secara umum, tombol afirmasi harus berada di sebelah kiri (tombol utama) dan tombol batal (tombol sekunder) harus berada di sebelah kanan.

  
• Seperti disebutkan di bagian rekomendasi umum, gunakan tombol dengan teks yang mengidentifikasi respons tertentu terhadap instruksi atau konten utama.

Beberapa platform menempatkan tombol afirmasi di sebelah kanan alih-alih kiri. Jadi mengapa sebaiknya letakkan di sebelah kiri? Jika Anda berasumsi bahwa sebagian besar pengguna menggunakan tangan kanan dan mereka memegang ponsel mereka dengan tangan itu, sebenarnya lebih nyaman untuk menekan tombol afirmasi ketika berada di sebelah kiri, karena tombol lebih mungkin berada dalam busur jempol pengguna. Tombol di sisi kanan layar mengharuskan pengguna untuk menarik jempol mereka ke dalam ke posisi yang kurang nyaman.

ContentDialog di AppWindow atau Kepulauan Xaml

CATATAN: Bagian ini hanya berlaku untuk aplikasi yang menargetkan Windows 10, versi 1903 atau yang lebih baru. Kepulauan AppWindow dan XAML tidak tersedia di versi sebelumnya. Untuk informasi selengkapnya tentang penerapan versi, lihat Aplikasi adaptif versi.

Secara default, dialog konten ditampilkan secara modal relatif terhadap ApplicationView akar. Saat Anda menggunakan ContentDialog di dalam AppWindow atau Pulau XAML, Anda perlu mengatur XamlRoot secara manual pada dialog ke akar host XAML.

Untuk melakukannya, atur properti ContentDialog XamlRoot ke XamlRoot yang sama dengan elemen yang sudah ada di AppWindow atau XAML Island, seperti yang ditunjukkan di sini.

private async void DisplayNoWifiDialog()
{
    ContentDialog noWifiDialog = new ContentDialog
    {
        Title = "No wifi connection",
        Content = "Check your connection and try again.",
        CloseButtonText = "OK"
    };

    // Use this code to associate the dialog to the appropriate AppWindow by setting
    // the dialog's XamlRoot to the same XamlRoot as an element that is already present in the AppWindow.
    if (ApiInformation.IsApiContractPresent("Windows.Foundation.UniversalApiContract", 8))
    {
        noWifiDialog.XamlRoot = elementAlreadyInMyAppWindow.XamlRoot;
    }

    ContentDialogResult result = await noWifiDialog.ShowAsync();
}

Peringatan

Hanya ada satu ContentDialog yang terbuka per utas pada satu waktu. Mencoba membuka dua ContentDialogs akan melemparkan pengecualian, bahkan jika mereka mencoba membuka di AppWindows terpisah.

Mendapatkan kode sampel

• Sampel Galeri WinUI - Lihat semua kontrol XAML dalam format interaktif.

Artikel terkait

• Tipsalat
• Menu dan menu konteks
• Kelas flyout
• Kelas ContentDialog