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.

Contoh dialog

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.

Pedoman 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 pertanyaan pemblokiran sesederhana 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 untuk 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 tidak merusak harus 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 terkait dengan lokasi spesifik di halaman, seperti kesalahan validasi (di bidang kata sandi, misalnya), gunakan kanvas aplikasi itu sendiri untuk menampilkan kesalahan secara langsung.
Gunakan kelas ContentDialog untuk membangun pengalaman dialog Anda. Jangan gunakan MESSAGEDialog API yang tidak digunakan lagi.

Membuat dialog

API Penting: Kelas ContentDialog

Buka aplikasi Galeri WinUI 3 dan lihat ContentDialog beraksi

Aplikasi Galeri WinUI 3 mencakup contoh interaktif kontrol dan fitur WinUI. Dapatkan aplikasi dari Microsoft Store atau telusuri kode sumber pada 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, bisa 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();
}

Jika dialog konten Anda lebih kompleks, akan lebih mudah untuk membuatnya dengan XAML. Anda dapat membuatnya di file XAML untuk halaman Anda, atau Anda dapat membuat subkelas ContentDialog dengan file .xaml dan file code-behind-nya sendiri. Untuk contoh lengkap keduanya, lihat referensi kelas [ContentDialog].

Tidak ada templat item di Visual Studio untuk membuat file dialog konten baru, tetapi Anda bisa menggunakan templat Halaman Kosong dan mengubah file yang dihasilkan untuk membuat dialog.

Untuk membuat dialog konten baru dengan XAML dan code-behind

Di panel Solution Explorer, klik kanan pada nama proyek dan pilih Tambahkan > Item Baru...
Dalam dialog Tambahkan Item Baru , pilih WinUI di daftar templat di sisi kiri jendela.
Pilih templat Halaman Kosong .
Beri nama file . (Dalam contoh ini, file diberi nama XamlContentDialog).
Tekan Tambahkan.

Dalam file .xaml baru, ubah tag Halaman pembuka dan penutupan menjadi Dialog Konten.

<!--
<Page
    x:Class="ContentDialog_WinUI3.XamlContentDialog"
    ...>

</Page>
-->

<ContentDialog
    x:Class="ContentDialog_WinUI3.XamlContentDialog"
    ...>

</ContentDialog>

Dalam file .xaml.cs, buat kelas Anda mewarisi dari ContentDialog alih-alih Halaman.

// public sealed partial class XamlContentDialog : Page

public sealed partial class XamlContentDialog : ContentDialog

Perlihatkan dialog

Untuk menampilkan dialog, panggil metode ShowAsync .

XamlContentDialog xamlDialog = new XamlContentDialog()
{
    XamlRoot = this.XamlRoot
};
await xamlDialog.ShowAsync();

Peringatan

Hanya ada satu ContentDialog yang terbuka per jendela pada satu waktu. Mencoba membuka dua dialog konten akan memunculkan pengecualian.

Mengatur XamlRoot

Saat Anda menampilkan ContentDialog, Anda perlu mengatur XamlRoot dialog secara manual ke akar host XAML. Untuk melakukannya, atur properti XamlRoot dari ContentDialog ke XamlRoot yang sama dengan elemen yang sudah ada di pohon XAML.

Jika ContentDialog ditampilkan dari Halaman, Anda dapat mengatur XamlRoot dari ContentDialog ke XamlRoot dari Halaman seperti yang ditunjukkan pada contoh sebelumnya.

Jendela tidak memiliki properti XamlRoot, jadi jika dialog ditampilkan dari Jendela, atur properti XamlRoot dialog ke elemen konten akar Jendela, seperti yang ditunjukkan di sini.

<Window
    ... >
    <Grid x:Name="rootPanel">
    
    </Grid>
</Window>

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

    ContentDialogResult result = await noWifiDialog.ShowAsync();
}

Menanggapi tombol pada dialog

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.

Dialog satu tombol

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 "tidak merusak" dapat disertai dengan satu atau dua tombol tindakan "lakukan". Saat menyajikan pengguna dengan beberapa opsi, pastikan bahwa tombol menjelaskan dengan jelas tindakan "lakukan" dan aman/"jangan lakukan" yang terkait dengan pertanyaan yang diusulkan.

Dialog dua tombol

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.

Dialog tiga tombol

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 pada 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 tombol tutup 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.

Dialog tiga tombol

Tombol Default

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 perlakuan 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.

Dialog tiga tombol dengan tombol default

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.

ContentDialog di AppWindow atau Xaml Islands

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

Secara bawaan, dialog konten ditampilkan secara modal relatif terhadap akar ApplicationView. Saat Anda menggunakan ContentDialog di dalam AppWindow atau XAML Island, Anda perlu mengatur XamlRoot secara manual pada dialog sesuai dengan akar host XAML.

Untuk melakukan ini, atur properti XamlRoot dari ContentDialog 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();
}