關於元件和瀑布式對話
適用于： SDK v4
對話方塊有幾種不同的類型。 本文說明元件、瀑布式和提示對話方塊。 如需一般對話的相關資訊，請參閱 對話方塊程式庫 一文。 如需調適型對話的相關資訊，請參閱 調適型對話簡介。
瀑布式對話 (或瀑布式) 定義一連串的步驟，讓您的 Bot 能夠引導使用者完成線性程式。 這些對話方塊的設計目的是在 元件對話的內容中運作。
元件對話是一種容器對話類型，可讓集合中的對話呼叫集合中的其他對話，例如瀑布式對話呼叫提示對話或其他瀑布式對話。 元件對話會管理一組 子 對話，例如瀑布式對話、提示等等。 您可以設計元件對話方塊來處理特定工作，並在相同 Bot 中或跨多個 Bot 重複使用。
提示對話方塊 (提示) 是設計來要求使用者輸入特定資訊類型的對話方塊，例如數位、日期或名稱等等。 提示的設計目的是在元件對話方塊中使用瀑布式對話。
元件對話
您有時想要撰寫可重複使用的對話，以便使用於不同的案例中，例如要求使用者提供街道、城市和郵遞區號值的地址對話。
「元件對話」提供以下策略：建立獨立的對話來處理特定案例，並將大型對話集分割成更多可管理的片段。 這些片段都有自己的對話集，而且會避免與所屬對話集發生任何名稱衝突。 如需詳細資訊，請參閱 元件對話方塊操作說明。
瀑布式對話
瀑布式對話是特定的對話實作，常用來向使用者收集資訊或引導使用者完成一系列的工作。 每個交談步驟都會以非同步函式的形式實作，而且採用「瀑布式步驟內容」(step) 參數。 在每一個步驟中，Bot 會提示使用者輸入 (或開始子對話方塊，但通常是提示) 、等候回應，然後將結果傳遞至下一個步驟。 第一個函式的結果將作為引數傳遞至下一個函式，依此類推。
下圖顯示瀑布步驟序列和所發生的堆疊作業。 底下的使用對話一節會詳細說明對話堆疊的使用方式。
在瀑布式步驟內，瀑布式對話的內容會儲存在其瀑布式步驟內容中。 步驟內容類別似于對話方塊內容，並提供目前回合內容和狀態的存取權。 請使用瀑布步驟內容物件，從瀑布步驟內與對話方塊集合互動。
您所能處理的傳回值可來自對話中瀑布式步驟內的對話，或來自 Bot 的開啟回合處理常式，儘管您通常只需要檢查 Bot 回合邏輯的對話回合結果狀態。 在瀑布步驟內，對話方塊會在瀑布步驟內容的「結果」屬性中提供傳回值。
瀑布式步驟內容屬性
瀑布步驟內容包含下列屬性：
- 選項：包含對話的輸入資訊。
- 值：包含您可以新增至內容，而後轉入後續步驟中的資訊。
- 結果：包含上一個步驟的結果。
此外， 下一 個方法會在 C# 中 (NextAsync ， 接下來 在 JavaScript 和 Python 中) 會繼續進行瀑布式對話的下一個步驟，讓您的 Bot 視需要略過特定步驟。
提示
Dialogs 程式庫中的提示，可讓您輕鬆地向使用者詢問資訊並評估其回應。 例如，針對 數位提示，您可以指定您要求的問題或資訊，而提示會自動檢查它是否收到有效的數位回應。 如果這麼做，交談可以繼續;如果沒有，則會重新指派使用者以取得有效的答案。
在幕後，提示為兩個步驟的對話方塊。 第一步，提示會要求輸入；第二步，其會傳回有效值，或利用重新提示從頂端開始。
呼叫提示時，提示會有「提示選項」，您可以在其中指定要提示的文字、驗證失敗時的重試提示，以及回答提示的選項。 一般而言，提示和重試提示屬性是活動，但有一些不同程式設計語言處理方式的變化。
此外，您可以在建立提示時，選擇為您的提示新增一些自訂驗證。 例如，假設我們想要使用數字提示來取得派對大小，但該派對大小必須大於 2 且小於 12。 提示會先檢查它是否收到有效的號碼，然後在提供時執行自訂驗證。 如果自訂驗證失敗，則會如上所示重新配置使用者。
提示完成時，其會明確地傳回所要求的結果值。 傳回該值時，我們可以確定它已通過內建提示驗證，以及可能已提供的任何其他自訂驗證。
如需使用各種提示的範例，請查看如何使用 Dialogs 程式庫來收集使用者輸入。
提示類型
在幕後，提示為兩個步驟的對話方塊。 首先，提示會要求輸入;第二，它會傳回有效值，或從頂端以重新指派重新開機。 對話方塊程式庫提供各種基本提示，每個提示都用於收集不同類型的回應。 基本提示可解譯自然語言輸入，例如 "ten" 或 "a dozen" 是指數字，或 "tomorrow" 或 "Friday at 10am" 是指日期時間。
| Prompt | 描述 | 傳回值 |
|---|---|---|
| 附件提示 | 要求一或多個附件，例如文件或影像。 | 「附件」物件的集合。 |
| 選擇提示 | 要求從一組選項中選擇。 | 「找到的選擇」物件。 |
| 確認提示 | 要求確認。 | 布林值。 |
| 日期時間提示 | 要求日期時間。 | 「日期時間解析」物件的集合。 |
| 數字提示 | 要求數字。 | 數值。 |
| 文字提示 | 要求一般文字輸入。 | 字串。 |
若要提示使用者提供輸入，請使用其中一個內建類別 (例如文字提示) 定義提示，然後將其新增至對話方塊集。 提示已修正在對話集內必須是唯一的識別碼。 您可以讓每個提示都有自訂驗證程式，而對於某些提示，您可以指定「預設地區設定」。
提示地區設定
地區設定用來決定選擇、確認、日期時間和數字提示的特定語言行為。 對於來自使用者的任何指定輸入，如果通道在使用者的訊息中提供了 locale 屬性，則會使用該屬性。 否則，如果在呼叫提示的建構函式時提供提示的「預設地區設定」，或藉由稍後設定，則會使用該預設地區設定。 如果未提供這些地區設定，則會使用英文 (「en-us」) 作為地區設定。
地區設定是兩個、三個或四個字元 ISO 639 程式碼，代表語言或語言系列。
提示選項
步驟內容 prompt 方法的第二個參數會採用提示選項物件，其具有下列屬性。
| 屬性 | 描述 |
|---|---|
| Prompt | 要傳送給使用者、要求他們輸入的初始活動。 |
| Retry prompt | 如果使用者的第一個輸入未驗證，則傳送使用者的活動。 |
| Choices | 可供使用者從中選擇、搭配選擇提示使用的選擇清單。 |
| Validations | 要與自訂驗證程式搭配使用的其他參數。 |
| Style | 定義要如何對使用者提供選項提示或確認提示的選項。 |
您應該一律指定要傳送給使用者的初始提示活動，並在使用者的輸入未驗證時重試實例提示。
如果使用者的輸入無效，則會將重試提示傳送給使用者;如果沒有指定重試，則會使用初始提示。 不過，如果從驗證程式內回傳活動給使用者，便不會傳送任何重試提示。
提示驗證
您可以先驗證提示回應，再將值傳回至瀑布的下一個步驟。 驗證程式函式具有「提示驗證程式內容」參數並且會傳回布林值，指出輸入是否通過驗證。 提示驗證程式內容包含下列屬性：
| 屬性 | 描述 |
|---|---|
| 內容 | Bot 目前的回合內容。 |
| Recognized | 「提示辨識器結果」，其中包含使用者輸入的相關資訊 (如辨識器所處理)。 |
| 選項 | 包含在呼叫中所提供用來啟動提示的「提示選項」。 |
提示辨識器結果具有下列屬性：
| 屬性 | 描述 |
|---|---|
| 已成功 | 表示辨識器是否能夠剖析輸入。 |
| ReplTest1 | 來自辨識器的傳回值。 如有必要，驗證碼可以修改此值。 |
使用對話
對話可被視為程式設計堆疊，我們稱之為「對話堆疊」，其由回合處理常式引導，而如果堆疊是空的，則會作為後援。 該堆疊上最上層的專案會被視為 使用中的對話方塊，而對話內容會將所有輸入導向至使用中的對話方塊。
當對話方塊開始時，它會推送至堆疊，而現在是使用中的對話方塊。 它會維持使用中的對話方塊，直到結束、 由取代對話方塊 方法移除，或由回合處理常式或作用中對話本身推入堆疊 (另一個對話方塊，) 變成使用中的對話方塊。 當新的對話結束時，它會從堆疊取出，而下一個對話方塊會再次變成作用中的對話方塊。 這可允許重複對話方塊或建立對話分支，如下所述。
您可以使用 執行 對話方塊擴充方法，開始或繼續根對話。 從 Bot 程式碼中，呼叫對話執行擴充方法會繼續現有的對話，或如果堆疊目前是空的，則會啟動對話的新實例。 控制項和使用者輸入會移至堆疊上的使用中對話方塊。
run 方法需要 狀態屬性存取子 才能存取對話方塊狀態。 存取子的建立和使用方式與其他狀態存取子相同，但是會根據交談狀態建立為其自己的專屬屬性。 在管理狀態主題中可找到管理狀態的詳細資訊，而對話狀態的使用方式則會顯示在循序交談流程操作說明中。
從對話中，您可以存取對話內容，並可以使用它來啟動其他對話、結束目前的對話方塊，以及執行其他作業。
開始對話方塊
從瀑布式對話中，使用開始對話、提示或取代對話方塊方法，傳遞您想要開始進入瀑布式對話內容的對話方塊識別碼。
- 提示和開始對話方法會將參考對話的新實例推送至堆疊頂端。
- replace dialog 方法會將目前的對話從堆疊取出，並將取代對話推送至堆疊。 被取代的對話已被取消，而該執行個體包含的資訊已處置。
使用 options 參數，將資訊傳遞至對話的新執行個體。 傳遞至新對話方塊的選項，可透過步驟內容在任何對話方塊步驟中的「選項」屬性來存取。 如需詳細資訊，請參閱如何使用 分支和迴圈建立進階對話流程。
繼續對話
在瀑布式對話方塊中，使用步驟內容的 values 屬性在回合之間保存狀態。 在後續回合中可使用在先前回合中新增至這個集合的值。 如需詳細資訊，請參閱如何使用 分支和迴圈建立進階對話流程。
結束對話方塊
在瀑布式對話中，使用 結束對話 方法，將對話從堆疊中快顯來結束對話。 結束對話方塊方法可以將選擇性的結果傳回父內容 (，例如呼叫它的對話方塊，或 Bot 的回合處理常式) 。 此方法最常從對話中進行呼叫，以結束本身目前的執行個體。
您可以從具有對話內容的任何地方呼叫 end dialog 方法，但是會對 Bot 顯示為從目前作用中的對話進行呼叫。
提示
最佳做法是在對話結尾明確呼叫 結束對話 方法。
清除所有對話
如果您想要將所有對話方塊從堆疊中移除，您可以藉由呼叫對話方塊內容的 cancel all dialogs 方法來清除對話方塊堆疊。
重複對話方塊
您可以使用取代對話方塊方法取代對話方塊本身，進而建立迴圈。 這是處理 複雜互動 的絕佳方式，以及管理功能表的一種技術。
注意
如果您需要保存目前對話方塊的內部狀態，您必須在呼叫 取代對話方塊 方法時，將資訊傳遞給對話的新實例，然後適當地初始化對話方塊。
產生對話分支
對話內容會維護對話堆疊，並針對堆疊上的每個對話，追蹤接下來是哪個步驟。 begin dialog 方法會建立一個子項目並將對話推送至堆疊頂端，而其 end dialog 方法則會將頂端對話從堆疊中取出。 End dialog 通常會從即將結束的對話中進行呼叫。
對話方塊可以藉由呼叫對話方塊內容的「開始對話方塊」方法，並提供新對話方塊的識別碼，在同一對話集合內開始新的對話方塊，然後讓新的對話成為目前使用中的對話方塊。 原始對話方塊仍在堆疊中，但呼叫對話方塊內容的「繼續 (continue) 對話方塊」方法只會傳送到堆疊頂端的對話方塊，也就是「使用中的對話方塊」。 當對話方塊從堆疊中移除時，對話方塊內容會從原始對話方塊停止的地方，繼續 (resume) 使用堆疊中瀑布的下一個步驟。
因此，藉由包含在對話方塊中，可以有條件地從一組可用的對話方塊中選擇對話方塊來開始的步驟，您即可在對話流程內建立分支。