Bileşen ve şelale iletişim kutuları hakkında
ŞUNLAR IÇIN GEÇERLIDIR: SDK v4
İletişim kutuları birkaç farklı türde gelir. Bu makalede bileşen, şelale ve istem iletişim kutuları açıklanmaktadır. Genel olarak iletişim kutuları hakkında bilgi için iletişim kutusu kitaplığı makalesine bakın. Uyarlamalı iletişim kutuları hakkında bilgi için uyarlamalı iletişim kutularına giriş bölümüne bakın.
Şelale iletişim kutusu (veya şelale), botunuzun kullanıcıya doğrusal bir işlemde yol göstermesine olanak sağlayan bir adım dizisini tanımlar. Bu iletişim kutuları, bir bileşen iletişim kutusu bağlamında çalışacak şekilde tasarlanmıştır.
Bileşen iletişim kutusu, kümedeki iletişim kutularının kümedeki diğer iletişim kutularını çağırmasına olanak tanıyan bir kapsayıcı iletişim kutusu türüdür; örneğin, şelale iletişim kutusu arama istemi iletişim kutuları veya başka bir şelale iletişim kutusu. Bileşen iletişim kutuları şelale iletişim kutuları , istemler vb. gibi alt iletişim kutularını yönetir. Belirli görevleri işlemek ve bunu aynı botta veya birden çok botta yeniden kullanmak için bir bileşen iletişim kutusu tasarlayabilirsiniz.
İstem iletişim kutuları (istemler), kullanıcıdan sayı, tarih veya ad gibi belirli türlerdeki bilgileri isteyecek şekilde tasarlanmış iletişim kutularıdır. İstemler, bir bileşen iletişim kutusundaki şelale iletişim kutularıyla çalışacak şekilde tasarlanmıştır.
Bileşen iletişim kutuları
Bazen kullanıcıdan sokak, şehir ve posta kodu değerlerini sağlamasını isteyen adres iletişim kutusu gibi farklı senaryolarda kullanmak istediğiniz yeniden kullanılabilir bir iletişim kutusu yazmak isteyebilirsiniz.
Bileşen iletişim kutusu, büyük bir iletişim kutusunu daha yönetilebilir parçalara ayırarak belirli senaryoları işlemek için bağımsız iletişim kutuları oluşturmaya yönelik bir strateji sağlar. Bu parçaların her birinin kendi iletişim kutusu kümesi vardır ve bu parçaları içeren iletişim kutusu kümesiyle ad çakışmalarını önler. Daha fazla bilgi için nasıl yapılır bileşeni iletişim kutusuna bakın.
Şelale iletişim kutuları
Şelale iletişim kutusu, kullanıcıdan bilgi toplamak veya kullanıcıya bir dizi görev boyunca yol göstermek için yaygın olarak kullanılan belirli bir iletişim kutusu uygulamasıdır. Konuşmanın her adımı, şelale adımı bağlamı (step) parametresini alan zaman uyumsuz bir işlev olarak uygulanır. Bot her adımda kullanıcıdan giriş ister (veya bir alt iletişim kutusu başlatabilir, ancak genellikle bir istemdir), yanıt bekler ve ardından sonucu bir sonraki adıma geçirir. İlk işlevin sonucu, bir sonraki işleve bağımsız değişken olarak geçirilir ve bu şekilde devam edilir.
Aşağıdaki diyagramda şelale adımları dizisi ve gerçekleşen yığın işlemleri gösterilmektedir. İletişim kutusu yığınının kullanımıyla ilgili ayrıntılar, kullanma iletişim kutuları bölümünde aşağıdadır.
Şelale adımları içinde, şelale iletişim kutusunun bağlamı şelale adımı bağlamında depolanır. Adım bağlamı iletişim kutusu bağlamı ile benzerdir ve geçerli dönüş bağlamı ile durumuna erişim sağlar. Şelale adımının içinden bir iletişim kutusu kümesiyle etkileşim kurmak için şelale adımı bağlam nesnesini kullanın.
Bir iletişim kutusundaki şelale adımında veya botunuzun açık dönüş işleyicisindeki bir iletişim kutusundan bir dönüş değeri işleyebilirsiniz, ancak genellikle yalnızca botunuzun dönüş mantığından gelen iletişim kutusunun dönüş sonucunu denetlemeniz gerekir. Bir şelale adımında iletişim kutusu, şelale adımı bağlamın sonuç özelliğindeki dönüş değerini sağlar.
Şelale adımı bağlam özellikleri
Şelale adımı bağlamı aşağıdaki özellikleri içerir:
- Seçenekler: İletişim kutusu için giriş bilgilerini içerir.
- Değerler: bağlama ekleyebileceğiniz bilgileri içerir ve sonraki adımlara taşınır.
- Sonuç: Önceki adımda elde edilen sonucu içerir.
Buna ek olarak, sonraki yöntem (C# dilinde NextAsync , JavaScript ve Python'da sonraki ) aynı sırayla şelale iletişim kutusunun bir sonraki adımına devam eder ve botunuzun gerekirse belirli bir adımı atlamasını sağlar.
Ister
İletişim kutuları kitaplığındaki istemler, kullanıcıdan bilgi istemek ve yanıtlarını değerlendirmek için kolay bir yol sağlar. Örneğin, bir sayı istemi için, istediğiniz soruyu veya bilgileri belirtirsiniz ve istem otomatik olarak geçerli bir sayı yanıtı alıp almadığınızı denetler. Varsa, konuşma devam edebilir; aksi takdirde, kullanıcıyı geçerli bir yanıt için yeniden oluşturur.
Arka planda istemler iki adımlı bir iletişim kutusu olur. İlk olarak, istem giriş ister; ikinci olarak geçerli değeri döndürür veya yeniden oluşturma ile üstten başlar.
İstemler, istem çağrıldığında verilen istem seçeneklerine sahiptir; burada sorulacak metni, doğrulama başarısız olursa yeniden deneme istemini ve istemi yanıtlama seçeneklerini belirtebilirsiniz. Genel olarak, istem ve yeniden deneme istemi özellikleri etkinliklerdir, ancak bunun farklı programlama dillerinde nasıl işlendiğinin bazı varyasyonları vardır.
Ayrıca, bunu oluştururken isteminiz için bazı özel doğrulamalar eklemeyi de seçebilirsiniz. Örneğin, sayı istemini kullanarak bir parti boyutu almak istediğimizi, ancak bu parti boyutunun 2'den büyük ve 12'den küçük olması gerektiğini varsayalım. İstem önce geçerli bir sayı alınıp alınmadığını denetler, ardından sağlanmışsa özel doğrulamayı çalıştırır. Özel doğrulama başarısız olursa, kullanıcıyı yukarıdaki gibi yeniden oluşturur.
Bir istem tamamlandığında, istenen sonuç değerini açıkça döndürür. Bu değer döndürülürken hem yerleşik istem doğrulamasını hem de sağlanmış olabilecek ek özel doğrulamayı geçirdiğinden emin olabiliriz.
Çeşitli istemleri kullanma örnekleri için, kullanıcı girişini toplamak için iletişim kutusu kitaplığının nasıl kullanılacağına göz atın.
İstem türleri
Arka planda istemler iki adımlı bir iletişim kutusu olur. İlk olarak, istem giriş ister; ikinci olarak geçerli değeri döndürür veya yeniden oluşturma işlemiyle üstten yeniden başlatılır. İletişim kutusu kitaplığı, her biri farklı bir yanıt türü toplamak için kullanılan çeşitli temel istemler sunar. Temel istemler, bir sayı için "on" veya "bir düzine" veya tarih-saat için "yarın" veya "Cuma saat 10:00" gibi doğal dil girişini yorumlayabilir.
| İstem | Description | Döndürülenler |
|---|---|---|
| Ek istemi | Belge veya resim gibi bir veya daha fazla ek ister. | Ek nesneleri koleksiyonu. |
| Seçim istemi | Bir dizi seçenek arasından seçim ister. | Bulunan seçim nesnesi. |
| İstemi onayla | Onay ister. | Boole değeri. |
| Tarih-saat istemi | Tarih-saat ister. | Tarih-saat çözümleme nesnelerinden oluşan bir koleksiyon. |
| Sayı istemi | Bir sayı ister. | Sayısal bir değer. |
| Metin istemi | Genel metin girişi ister. | Bir dize. |
Kullanıcıdan giriş istemesi için, metin istemi gibi yerleşik sınıflardan birini kullanarak bir istem tanımlayın ve bunu iletişim kutunuza ekleyin. İstemler, bir iletişim kutusu kümesi içinde benzersiz olması gereken sabit kimliklere sahiptir. Her istem için özel bir doğrulayıcınız olabilir ve bazı istemler için varsayılan bir yerel ayar belirtebilirsiniz.
Komut istemi yerel ayarı
Yerel ayar, dile özgü seçimin davranışını belirlemek, onaylamak, tarih-saat ve sayı istemlerini belirlemek için kullanılır. Kullanıcıdan gelen herhangi bir giriş için, kanal kullanıcının iletisinde bir yerel ayar özelliği sağladıysa, bu kullanılır. Aksi takdirde, istemin varsayılan yerel ayarı ayarlanırsa, istem oluşturucuyu çağırırken sağlayarak veya daha sonra ayarlayarak bu kullanılır. Bu yerel ayarlardan hiçbiri sağlanmazsa, yerel ayar olarak İngilizce ("en-us") kullanılır.
Yerel ayar, bir dili veya dil ailesini temsil eden iki, üç veya dört karakterlik BIR ISO 639 kodudur.
İstem seçenekleri
Adım bağlamının istem yönteminin ikinci parametresi, aşağıdaki özelliklere sahip bir istem seçenekleri nesnesi alır.
| Özellik | Açıklama |
|---|---|
| İstem | Kullanıcıya girişlerini istemek için gönderilecek ilk etkinlik. |
| Yeniden deneme istemi | İlk girişi doğrulanmamışsa kullanıcıya gönderme etkinliği. |
| Seçenekler | Kullanıcının seçim istemiyle kullanmak üzere aralarından seçim yapabileceğiniz seçeneklerin listesi. |
| Doğrulamalar | Özel doğrulayıcı ile kullanılacak ek parametreler. |
| Stil | Seçim istemi veya onay istemi seçeneklerinin kullanıcıya nasıl sunulacağını tanımlar. |
Her zaman kullanıcıya gönderilecek ilk istem etkinliğini ve kullanıcının girişi doğrulanmadığında örnekler için yeniden deneme istemi belirtmeniz gerekir.
Kullanıcının girişi geçerli değilse, yeniden deneme istemi kullanıcıya gönderilir; yeniden deneme belirtilmediyse, ilk istem kullanılır. Ancak, bir etkinlik doğrulayıcı içinden kullanıcıya geri gönderilirse, yeniden deneme istemi gönderilmez.
İstem doğrulama
Değeri şelalenin bir sonraki adımına döndürmeden önce bir istem yanıtını doğrulayabilirsiniz. Doğrulayıcı işlevinin bir istem doğrulayıcı bağlam parametresi vardır ve girişin doğrulamayı geçip geçmediğini belirten bir Boole değeri döndürür. İstem doğrulayıcı bağlamı aşağıdaki özellikleri içerir:
| Özellik | Açıklama |
|---|---|
| Bağlam | Bot için geçerli dönüş bağlamı. |
| Tanınan | Tanıyıcı tarafından işlenen kullanıcı girişi hakkında bilgi içeren bir istem tanıyıcı sonucu. |
| Seçenekler | Çağrıda istemi başlatmak için sağlanan istem seçeneklerini içerir. |
İstem tanıyıcısı sonucu aşağıdaki özelliklere sahiptir:
| Özellik | Açıklama |
|---|---|
| Başarılı | Tanıyıcının girişi ayrıştırıp ayrıştıramadığını gösterir. |
| Değer | Tanıyıcıdan döndürülen değer. Gerekirse doğrulama kodu bu değeri değiştirebilir. |
İletişim kutularını kullanma
İletişim kutuları, iletişim kutusu yığını olarak adlandırdığımız, dönüş işleyicisi onu yönlendiren ve yığın boşsa geri dönüş görevi gören programlı bir yığın olarak düşünülebilir. Bu yığındaki en üstteki öğe etkin iletişim kutusu olarak kabul edilir ve iletişim kutusu bağlamı tüm girişleri etkin iletişim kutusuna yönlendirir.
Bir iletişim kutusu başladığında yığına gönderilir ve artık etkin iletişim kutusudur. İki durumdan biri bitene, değiştir iletişim kutusu yöntemi tarafından kaldırılana veya başka bir iletişim kutusu yığına (dönüş işleyicisi veya etkin iletişim kutusu tarafından) gönderilene kadar etkin iletişim kutusu olarak kalır ve etkin iletişim kutusu olur. Bu yeni iletişim kutusu sona erdiğinde, yığından çıkarılır ve sonraki iletişim kutusu yeniden etkin iletişim kutusuna dönüşür. Bu, aşağıda açıklanan iletişim kutusunun yinelenmesine veya bir konuşmanın dallanmasına olanak tanır.
Çalıştırma iletişim kutusu uzantısı yöntemini kullanarak bir kök iletişim kutusu başlatabilir veya devam edebilirsiniz. Bot kodundan, iletişim kutusu çalıştırma uzantısı yöntemini çağırmak var olan iletişim kutusuna devam eder veya yığın şu anda boşsa iletişim kutusunun yeni bir örneğini başlatır. Denetim ve kullanıcı girişi yığındaki etkin iletişim kutusuna gider.
Çalıştırma yöntemi, iletişim kutusu durumuna erişmek için bir durum özelliği erişimcisi gerektirir. Erişimci, diğer durum erişimcileriyle aynı şekilde oluşturulur ve kullanılır, ancak konuşma durumuna göre kendi özelliği olarak oluşturulur. Durumu yönetmeyle ilgili ayrıntılar, durumu yönetme konusunda bulunabilir ve iletişim durumunun kullanımı sıralı konuşma akışında nasıl yapılır bölümünde gösterilir.
İletişim kutusunun içinden iletişim kutusu bağlamı erişiminiz vardır ve bunu kullanarak diğer iletişim kutularını başlatabilir, geçerli iletişim kutusunu sonlandırabilir ve diğer işlemleri gerçekleştirebilirsiniz.
İletişim kutusu başlatmak için
Şelale iletişim kutusunun içinden başlatmak istediğiniz iletişim kutusunun iletişim kutusu kimliğini, başlangıç iletişim kutusunu, istemi veya değiştirme iletişim kutusunu kullanarak şelale iletişim kutusunun bağlamı içine geçirin.
- İstem ve başlatma iletişim kutusu yöntemleri, başvuruda bulunılan iletişim kutusunun yeni bir örneğini yığının en üstüne iletir.
- Değiştir iletişim kutusu yöntemi geçerli iletişim kutusunu yığından açar ve değiştirme iletişim kutusunu yığına iter. Değiştirilen iletişim kutusu iptal edilir ve örneğin içerdiği tüm bilgiler atılır.
İletişim kutusunun yeni örneğine bilgi geçirmek için options parametresini kullanın. Yeni iletişim kutusuna geçirilen seçeneklere, iletişim kutusunun herhangi bir adımındaki adım bağlamının seçenekler özelliği aracılığıyla erişilebilir. Daha fazla bilgi için bkz. Dalları ve döngüleri kullanarak gelişmiş konuşma akışı oluşturma.
İletişim kutusuna devam etmek için
Şelale iletişim kutusunda, dönüşler arasında durumu kalıcı hale getirmek için adım bağlamın values özelliğini kullanın. Önceki bir dönüşte bu koleksiyona eklenen tüm değerler sonraki dönüşlerde kullanılabilir. Daha fazla bilgi için bkz. Dalları ve döngüleri kullanarak gelişmiş konuşma akışı oluşturma.
İletişim kutusunu sonlandırmak için
Şelale iletişim kutusunda, bir iletişim kutusunu yığından çıkararak sonlandırmak için end iletişim kutusu yöntemini kullanın. End iletişim kutusu yöntemi, üst bağlama isteğe bağlı bir sonuç döndürebilir (örneğin, onu çağıran iletişim kutusu veya bot'un dönüş işleyicisi). Bu genellikle iletişim kutusunun içinden çağrılır ve kendi geçerli örneğini sonlanır.
İletişim kutusu bağlamı olan her yerden end iletişim kutusu yöntemini çağırabilirsiniz, ancak geçerli etkin iletişim kutusundan çağrıldığı bota görünür.
İpucu
İletişim kutusunun sonundaki end iletişim kutusu yöntemini açıkça çağırmak en iyi yöntemdir.
Tüm iletişim kutularını temizlemek için
Tüm iletişim kutularını yığından açmak istiyorsanız, iletişim kutusunun tüm iletişim kutularını iptal et yöntemini çağırarak iletişim kutusu yığınını temizleyebilirsiniz.
İletişim kutusunu yineleme
Değiştir iletişim kutusu yöntemini kullanarak bir iletişim kutusunu kendi kendine değiştirebilir, döngü oluşturabilirsiniz. Bu, karmaşık etkileşimleri işlemek için harika bir yoldur ve menüleri yönetmek için bir tekniktir.
Not
Geçerli iletişim kutusunun iç durumunu kalıcı hale getirmek istiyorsanız, değiştir iletişim kutusu yöntemi çağrısında iletişim kutusunun yeni örneğine bilgi iletmeniz ve ardından iletişim kutusunu uygun şekilde başlatmanız gerekir.
Konuşmayı dallanma
İletişim kutusu bağlamı, iletişim kutusu yığınını korur ve yığındaki her iletişim kutusu için sonraki adımı izler. Başlangıç iletişim kutusu yöntemi bir alt öğe oluşturur ve bu iletişim kutusunu yığının en üstüne iletir ve bitiş iletişim kutusu yöntemi de üstteki iletişim kutusunu yığından açar. End iletişim kutusu genellikle biten iletişim kutusunun içinden çağrılır.
İletişim kutusu, iletişim kutusunun başlangıç iletişim kutusu yöntemini çağırarak ve yeni iletişim kutusunun kimliğini sağlayarak aynı iletişim kutusu kümesi içinde yeni bir iletişim kutusu başlatabilir ve bu da yeni iletişim kutusunu o anda etkin olan iletişim kutusu yapar. Özgün iletişim kutusu hala yığındadır, ancak iletişim kutusunun devam iletişim kutusu yöntemine yapılan çağrılar yalnızca yığının üst kısmındaki etkin iletişim kutusuna gönderilir. Bir iletişim kutusu yığından çıkarıldığında, iletişim kutusu bağlamı özgün iletişim kutusundan ayrıldığı yığında şelalenin bir sonraki adımıyla devam eder.
Bu nedenle, bir dizi kullanılabilir iletişim kutusundan başlamak için koşullu olarak bir iletişim kutusu seçebilen bir adım ekleyerek konuşma akışınızda bir dal oluşturabilirsiniz.
Ek bilgiler
- Uyarlamalı iletişim kutuları hakkında daha fazla bilgi için uyarlamalı iletişim kutularına giriş bölümüne bakın.
- Beceriler hakkında bilgi için bkz. beceriler hakkında.