Tentang dialog komponen dan air terjun
BERLAKU UNTUK: SDK v4
Dialog hadir dalam beberapa jenis yang berbeda. Artikel ini menjelaskan dialog komponen, air terjun, dan perintah. Untuk informasi tentang dialog secara umum, lihat artikel pustaka dialog . Untuk informasi tentang dialog adaptif, lihat pengenalan dialog adaptif.
Dialog air terjun (atau air terjun) mendefinisikan urutan langkah, memungkinkan bot Anda memandu pengguna melalui proses linier. Dialog ini dirancang untuk bekerja dalam konteks dialog komponen.
Dialog komponen adalah jenis dialog kontainer yang memungkinkan dialog dalam set untuk memanggil dialog lain dalam set, seperti dialog air terjun memanggil dialog permintaan atau dialog air terjun lainnya. Dialog komponen mengelola sekumpulan dialog anak , seperti dialog air terjun, perintah, dan sebagainya. Anda dapat merancang dialog komponen untuk menangani tugas tertentu dan menggunakannya kembali, di bot yang sama atau di beberapa bot.
Dialog perintah (perintah) adalah dialog yang dirancang untuk meminta jenis informasi tertentu kepada pengguna, seperti angka, tanggal, atau nama, dan sebagainya. Perintah dirancang untuk bekerja dengan dialog air terjun dalam dialog komponen.
Dialog komponen
Terkadang Anda ingin menulis dialog yang dapat digunakan kembali yang ingin Anda gunakan dalam skenario yang berbeda, seperti dialog alamat yang meminta pengguna untuk memberikan nilai untuk jalan, kota, dan kode pos.
Dialog komponen menyediakan strategi untuk membuat dialog independen untuk menangani skenario tertentu, memecah dialog besar yang diatur menjadi bagian yang lebih mudah dikelola. Masing-masing bagian ini memiliki kumpulan dialognya sendiri, dan menghindari tabrakan nama dengan kumpulan dialog yang berisinya. Untuk informasi selengkapnya, lihat dialog komponen caranya.
Dialog air terjun
Dialog air terjun adalah implementasi spesifik dari dialog yang umumnya digunakan untuk mengumpulkan informasi dari pengguna atau memandu pengguna melalui serangkaian tugas. Setiap langkah percakapan diimplementasikan sebagai fungsi asinkron yang mengambil parameter konteks langkah air terjun (step). Pada setiap langkah, bot meminta input kepada pengguna (atau dapat memulai dialog anak, tetapi seringkali merupakan perintah), menunggu respons, lalu meneruskan hasilnya ke langkah berikutnya. Hasil dari fungsi pertama diteruskan sebagai argumen ke fungsi berikutnya, dan seterusnya.
Diagram berikut menunjukkan urutan langkah-langkah air terjun dan operasi tumpukan yang berlangsung. Detail tentang penggunaan tumpukan dialog berada di bawah ini di bagian menggunakan dialog .
Dalam langkah-langkah air terjun, konteks dialog air terjun disimpan dalam konteks langkah air terjunnya. Konteks langkah mirip dengan konteks dialog dan menyediakan akses ke konteks dan status giliran saat ini. Gunakan objek konteks langkah air terjun untuk berinteraksi dengan dialog yang diatur dari dalam langkah air terjun.
Anda dapat menangani nilai pengembalian dari dialog baik dalam langkah air terjun dalam dialog atau dari penangan aktif bot Anda, meskipun Anda umumnya hanya perlu memeriksa status hasil giliran dialog dari logika giliran bot Anda. Dalam langkah air terjun, dialog menyediakan nilai kembali di properti hasil konteks langkah air terjun.
Properti konteks langkah air terjun
Konteks langkah air terjun berisi properti berikut:
- Opsi: berisi informasi input untuk dialog.
- Nilai: berisi informasi yang dapat Anda tambahkan ke konteks, dan diteruskan ke langkah-langkah berikutnya.
- Hasil: berisi hasil dari langkah sebelumnya.
Selain itu, metode berikutnya (NextAsync di C#, berikutnya di JavaScript dan Python) berlanjut ke langkah dialog air terjun berikutnya dalam giliran yang sama, memungkinkan bot Anda untuk melewati langkah tertentu jika diperlukan.
Prompt
Perintah, dalam pustaka dialog, menyediakan cara mudah untuk meminta informasi kepada pengguna dan mengevaluasi respons mereka. Misalnya untuk perintah angka, Anda menentukan pertanyaan atau informasi yang Anda minta, dan perintah secara otomatis memeriksa untuk melihat apakah ia menerima respons angka yang valid. Jika ya, percakapan dapat dilanjutkan; jika tidak, itu akan mencabut pengguna untuk jawaban yang valid.
Di balik layar, perintah adalah dialog dua langkah. Pertama, permintaan meminta masukan; kedua, mengembalikan nilai yang valid, atau dimulai dari bagian atas dengan prompt ulang.
Perintah memiliki opsi perintah yang diberikan saat perintah dipanggil, yang merupakan tempat Anda dapat menentukan teks yang akan diminta, permintaan coba lagi jika validasi gagal, dan pilihan untuk menjawab perintah. Secara umum, properti prompt dan retry prompt adalah aktivitas, meskipun ada beberapa variasi tentang bagaimana hal ini ditangani dalam bahasa pemrograman yang berbeda.
Selain itu, Anda dapat memilih untuk menambahkan beberapa validasi kustom untuk perintah Anda saat membuatnya. Misalnya, kami ingin mendapatkan ukuran pesta menggunakan prompt angka, tetapi ukuran pesta itu harus lebih dari 2 dan kurang dari 12. Perintah pertama-tama memeriksa untuk melihat apakah menerima nomor yang valid, lalu menjalankan validasi kustom jika disediakan. Jika validasi kustom gagal, validasi kustom akan memprompeksi ulang pengguna seperti di atas.
Ketika perintah selesai, perintah secara eksplisit mengembalikan nilai hasil yang diminta. Ketika nilai tersebut dikembalikan, kita dapat yakin bahwa nilai tersebut telah melewati validasi permintaan bawaan dan validasi kustom tambahan yang mungkin telah disediakan.
Misalnya tentang menggunakan berbagai perintah, lihat cara menggunakan pustaka dialog untuk mengumpulkan input pengguna.
Jenis perintah
Di balik layar, perintah adalah dialog dua langkah. Pertama, permintaan meminta masukan; kedua, mengembalikan nilai yang valid, atau memulai ulang dari bagian atas dengan prompt ulang. Pustaka dialog menawarkan berbagai perintah dasar, masing-masing digunakan untuk mengumpulkan jenis respons yang berbeda. Perintah dasar dapat menginterpretasikan input bahasa alami, seperti "sepuluh" atau "selusin" untuk angka, atau "besok" atau "Jumat pukul 10 pagi" untuk tanggal-waktu.
| Perintah | Deskripsi | Mengembalikan |
|---|---|---|
| Prompt lampiran | Meminta satu atau beberapa lampiran, seperti dokumen atau gambar. | Kumpulan objek lampiran . |
| Perintah pilihan | Meminta pilihan dari sekumpulan opsi. | Objek pilihan yang ditemukan . |
| Konfirmasi permintaan | Meminta konfirmasi. | Nilai Boolean. |
| Prompt tanggal-waktu | Meminta tanggal-waktu. | Kumpulan objek resolusi tanggal-waktu . |
| Perintah nomor | Meminta nomor. | Nilai numerik. |
| Perintah teks | Meminta input teks umum. | Sebuah string. |
Untuk meminta input kepada pengguna, tentukan perintah menggunakan salah satu kelas bawaan, seperti perintah teks, dan tambahkan ke kumpulan dialog Anda. Perintah memiliki ID tetap yang harus unik dalam kumpulan dialog. Anda dapat memiliki validator kustom untuk setiap perintah, dan untuk beberapa perintah, Anda dapat menentukan lokal default.
Minta lokal
Lokal digunakan untuk menentukan perilaku spesifik bahasa pilihan, konfirmasi, tanggal-waktu, dan perintah angka . Untuk input tertentu dari pengguna, jika saluran menyediakan properti lokal dalam pesan pengguna, maka itu digunakan. Jika tidak, jika lokal default prompt diatur, dengan menyediakannya saat memanggil konstruktor prompt atau dengan mengaturnya nanti, maka itu digunakan. Jika tidak ada lokal yang disediakan, bahasa Inggris ("en-us") digunakan sebagai lokal.
Lokalnya adalah kode ISO 639 dua, tiga, atau empat karakter yang mewakili keluarga bahasa atau bahasa.
Opsi perintah
Parameter kedua dari metode prompt konteks langkah mengambil objek opsi prompt , yang memiliki properti berikut.
| Properti | Deskripsi |
|---|---|
| Perintah | Aktivitas awal untuk mengirim pengguna, untuk meminta input mereka. |
| Coba lagi permintaan | Aktivitas untuk mengirim pengguna jika input pertama mereka tidak memvalidasi. |
| Pilihan | Daftar pilihan untuk dipilih pengguna, untuk digunakan dengan perintah pilihan. |
| Validasi | Parameter tambahan untuk digunakan dengan validator kustom. |
| Gaya | Menentukan bagaimana pilihan untuk permintaan pilihan atau konfirmasi permintaan akan disajikan kepada pengguna. |
Anda harus selalu menentukan aktivitas permintaan awal untuk dikirim ke pengguna, dan permintaan coba lagi untuk instans saat input pengguna tidak memvalidasi.
Jika input pengguna tidak valid, permintaan coba lagi dikirim ke pengguna; jika tidak ada coba lagi yang ditentukan, maka perintah awal digunakan. Namun, jika aktivitas dikirim kembali ke pengguna dari dalam validator, tidak ada permintaan coba lagi yang dikirim.
Validasi permintaan
Anda dapat memvalidasi respons perintah sebelum mengembalikan nilai ke langkah air terjun berikutnya. Fungsi validator memiliki parameter konteks validator perintah dan mengembalikan Boolean, menunjukkan apakah input melewati validasi. Konteks validator prompt mencakup properti berikut:
| Properti | Deskripsi |
|---|---|
| Konteks | Konteks giliran saat ini untuk bot. |
| Diakui | Hasil pengenal perintah yang berisi informasi tentang input pengguna, seperti yang diproses oleh pengenal. |
| Opsi | Berisi opsi perintah yang disediakan dalam panggilan untuk memulai perintah. |
Hasil prompt recognizer memiliki properti berikut:
| Properti | Deskripsi |
|---|---|
| Berhasil | Menunjukkan apakah recognizer dapat mengurai input. |
| Nilai | Nilai yang dikembalikan dari recognizer. Jika perlu, kode validasi dapat memodifikasi nilai ini. |
Menggunakan dialog
Dialog dapat dianggap sebagai tumpukan terprogram, yang kami sebut tumpukan dialog, dengan handler giliran sebagai yang mengarahkannya dan berfungsi sebagai fallback jika tumpukan kosong. Item paling atas pada tumpukan tersebut dianggap sebagai dialog aktif, dan konteks dialog mengarahkan semua input ke dialog aktif.
Saat dialog dimulai, dialog didorong ke tumpukan, dan sekarang menjadi dialog aktif. Ini tetap menjadi dialog aktif sampai berakhir, itu dihapus oleh metode dialog ganti , atau dialog lain didorong ke tumpukan (dengan penangan giliran atau dialog aktif itu sendiri) dan menjadi dialog aktif. Ketika dialog baru berakhir, dialog akan muncul dari tumpukan dan dialog berikutnya ke bawah menjadi dialog aktif lagi. Ini memungkinkan untuk mengulangi dialog atau mencabangkan percakapan, yang dibahas di bawah ini.
Anda dapat memulai atau melanjutkan dialog akar menggunakan metode ekstensi dialog jalankan . Dari kode bot, memanggil metode ekstensi eksekusi dialog melanjutkan dialog yang ada, atau memulai instans baru dialog jika tumpukan saat ini kosong. Input kontrol dan pengguna masuk ke dialog aktif pada tumpukan.
Metode eksekusi memerlukan pengaktif properti status untuk mengakses status dialog. Pengaktif dibuat dan digunakan dengan cara yang sama seperti pengaktif status lainnya, tetapi dibuat sebagai propertinya sendiri berdasarkan status percakapan. Detail tentang mengelola status dapat ditemukan dalam topik mengelola status, dan penggunaan status dialog diperlihatkan dalam panduan alur percakapan berurutan .
Dari dalam dialog, Anda memiliki akses ke konteks dialog dan dapat menggunakannya untuk memulai dialog lain, mengakhiri dialog saat ini, dan melakukan operasi lainnya.
Untuk memulai dialog
Dari dalam dialog air terjun, teruskan ID dialog yang ingin Anda mulai ke konteks dialog air terjun menggunakan dialog mulai, perintah, atau ganti metode dialog .
- Perintah dan metode dialog mulai akan mendorong instans baru dari dialog yang direferensikan ke bagian atas tumpukan.
- Metode dialog ganti akan memunculkan dialog saat ini dari tumpukan dan mendorong dialog penggantian ke tumpukan. Dialog yang diganti dibatalkan dan informasi apa pun yang terkandung instans dibuang.
Gunakan parameter opsi untuk meneruskan informasi ke instans baru dialog. Opsi yang diteruskan ke dialog baru dapat diakses melalui properti opsi konteks langkah dalam langkah dialog apa pun. Untuk informasi selengkapnya, lihat cara Membuat alur percakapan tingkat lanjut menggunakan cabang dan perulangan.
Untuk melanjutkan dialog
Dalam dialog air terjun, gunakan properti nilai konteks langkah untuk mempertahankan status di antara belokan. Nilai apa pun yang ditambahkan ke koleksi ini di giliran sebelumnya tersedia dalam giliran berikutnya. Untuk informasi selengkapnya, lihat cara Membuat alur percakapan tingkat lanjut menggunakan cabang dan perulangan.
Untuk mengakhiri dialog
Dalam dialog air terjun, gunakan metode dialog akhir untuk mengakhiri dialog dengan memunculkannya dari tumpukan. Metode dialog akhir dapat mengembalikan hasil opsional ke konteks induk (seperti dialog yang memanggilnya, atau penangan giliran bot). Ini paling sering dipanggil dari dalam dialog untuk mengakhiri instans dirinya saat ini.
Anda dapat memanggil metode dialog akhir dari mana saja Anda memiliki konteks dialog, tetapi akan muncul ke bot yang dipanggil dari dialog aktif saat ini.
Tip
Praktik terbaik adalah memanggil metode dialog akhir secara eksplisit di akhir dialog.
Untuk menghapus semua dialog
Jika Anda ingin memunculkan semua dialog dari tumpukan, Anda dapat menghapus tumpukan dialog dengan memanggil metode batalkan semua dialog konteks dialog.
Mengulangi dialog
Anda dapat mengganti dialog dengan dialog itu sendiri, membuat perulangan, dengan menggunakan metode dialog ganti . Ini adalah cara yang bagus untuk menangani interaksi yang kompleks dan satu teknik untuk mengelola menu.
Catatan
Jika Anda perlu mempertahankan status internal untuk dialog saat ini, Anda harus meneruskan informasi ke instans baru dialog dalam panggilan ke metode dialog ganti , lalu menginisialisasi dialog dengan tepat.
Mencabangkan percakapan
Konteks dialog mempertahankan tumpukan dialog dan untuk setiap dialog pada tumpukan, melacak langkah mana yang berikutnya. Metode dialog mulai membuat anak dan mendorong dialog tersebut ke bagian atas tumpukan, dan metode dialog akhirnya memunculkan dialog atas dari tumpukan. Dialog akhir biasanya dipanggil dari dalam dialog yang berakhir.
Dialog dapat memulai dialog baru dalam kumpulan dialog yang sama dengan memanggil metode dialog mulai konteks dialog dan menyediakan ID dialog baru, yang kemudian membuat dialog baru menjadi dialog yang saat ini aktif. Dialog asli masih berada di tumpukan, tetapi panggilan ke metode dialog lanjutkan konteks dialog hanya dikirim ke dialog yang berada di atas tumpukan, dialog aktif. Ketika dialog muncul dari tumpukan, konteks dialog akan dilanjutkan dengan langkah berikutnya dari air terjun pada tumpukan di mana ia meninggalkan dialog asli.
Oleh karena itu, Anda dapat membuat cabang dalam alur percakapan Anda dengan menyertakan langkah dalam satu dialog yang dapat memilih dialog secara kondisional untuk memulai dari sekumpulan dialog yang tersedia.
Informasi Tambahan
- Untuk informasi selengkapnya tentang dialog adaptif, lihat pengenalan dialog adaptif.
- Untuk informasi tentang keterampilan, lihat tentang keterampilan.