Dialog API — MRTK3

Dialog adalah tampilan UI berumur pendek yang menyediakan informasi aplikasi kontekstual. Mereka sering meminta beberapa tindakan dari pengguna dan kemudian mengembalikan hasilnya kembali ke logika bisnis aplikasi dalam tugas atau hasil asinkron. Gunakan dialog untuk memberi tahu pengguna tentang informasi penting atau konfirmasi permintaan sebelum tindakan dapat diselesaikan.

MRTK3 UXCore menyediakan IDialog API, bersama dengan implementasi dasar Dialog dan DialogPool untuk pemijahan dan pengelolaan instans. Dokumentasi ini menjelaskan API fasih berbasis kode untuk menampilkan Dialog dari logika bisnis Anda. Untuk dokumentasi tentang prefab yang disertakan dalam paket Komponen UX, lihat dokumentasi Prefab dialog di sini.

Penggunaan

Tempatkan DialogPool di suatu tempat di adegan atau hierarki UI Anda. Jika diinginkan, Anda dapat mengelola referensi global DialogPool Anda sendiri dengan singleton, manajer, atau pola lainnya. MRTK sendiri tidak memberikan pendapat tentang bagaimana Anda mempertahankan referensi global DialogPool , tetapi komponen harus berada di adegan Anda di suatu tempat sehingga prefab tampilan dialog yang dirujuk disertakan dalam build Anda.

DialogPool akan secara otomatis mengatur referensi prefab-nya ke Komponen CanvasDialog.prefab UX standar jika paket diinstal. Untuk informasi selengkapnya tentang standar CanvasDialog.prefabKomponen UX, lihat dokumentasi di sini.

Setelah mendapatkan DialogPool referensi, Anda dapat menggunakan API penyusun gaya fasih untuk mengonfigurasi dan menampilkan dialog Anda.

dialogPool.Get()
    .SetHeader("This is the Dialog's header.")
    .SetBody("You can specify the dialog's body text here.")
    .SetPositive("The positive button's label.", (args) => { /* Do thing! */ })
    .Show()

Hanya sub-kontrol yang ditentukan dalam panggilan Anda ke API penyusun yang akan terlihat pada Dialog penggunaan kembali. Misalnya, sampel kode di atas akan menghasilkan Dialog dengan teks header dan teks isi, tetapi hanya satu tombol pilihan positif. Tombol tambahan dapat ditentukan dengan menautkan panggilan metode lebih lanjut.

// This dialog will show all three buttons.
dialogPool.Get()
    .SetHeader("A header.")
    .SetBody("Foobarbaz!")
    .SetPositive("The positive button's label.", (args) => { /* Do thing! */ })
    .SetNegative("The negative button's label.", (args) => { /* Do another thing! */ })
    .SetNeutral("A neutral option, too!", (args) => { /* Do some neutral thing. */ })
    .Show()

args yang diteruskan melalui panggilan balik tombol akan menjadi DialogButtonEventArgs, yang mencakup referensi ke IDialog peristiwa yang dihasilkan dan DialogButtonType tombol yang dipilih pengguna.

Ada kemungkinan bahwa dialog mungkin ditutup secara eksternal sebelum pengguna dapat membuat keputusan. Ini dapat disebabkan oleh dialog lain yang dibuka atau oleh dialog yang ditutup secara manual dalam kode. Dalam hal ini, panggilan balik yang disediakan untuk SetPositive() tidak akan pernah dipanggil. Jika Anda ingin mendengarkan peristiwa apa pun pada dialog, termasuk pemecatan eksternal, Anda dapat mendengarkan OnDismissed panggilan balik.

var dialog = dialogPool.Get()?SetBody("Foobar!");
dialog.OnDismissed += (args) => { /* do things! */ };
dialog.Show();

OnDismissed akan meneruskan DialogDismissedEventArgs, yang akan berisi DialogButtonEventArgs jika pengguna telah membuat pilihan, atau null jika dialog diberhentikan karena alasan lain.

Metode standar IDialog.Show() cocok untuk penggunaan Unity-idiomatic yang khas dalam metode non-async . Jika Anda menulis logika bisnis dalam async konteks, Anda dapat menggunakan IDialog.ShowAsync() metode untuk await pada hasil dialog dengan sintaks yang lebih ekspresif.

async void SomeAsyncBusinessLogic()
{
    var result = await dialogPool.Get()
                    .SetBody("The await will resolve when the user selects the option.")
                    .SetNeutral("A button!")
                    .ShowAsync();

    Debug.Log("Async dialog says: " + result.Choice?.ButtonText);
}

ShowAsync akan mengembalikan jenis arg yang sama dengan OnDismissed, a DialogDismissedEventArgs.

Contoh adegan dan prefab

Untuk informasi tentang prefab dan adegan sampel yang disertakan, lihat dokumentasi Komponen UX di sini.