关于组件和瀑布式对话框

适用于： SDK v4

对话包含几种不同类型的对话。 本文介绍组件、瀑布对话框和提示对话框。 有关一般对话的信息，请参阅 对话库 文章。 有关自适应对话的信息，请参阅 自适应对话简介。

瀑布对话（或瀑布）定义了一系列步骤，使机器人能够引导用户完成线性过程。 这些对话设计为在 组件对话的上下文中工作。

组件对话框是一种容器对话框类型，它允许在集合中的对话相互调用，例如瀑布对话可以调用提示对话或其他瀑布对话。 组件对话管理一组 子 对话，例如瀑布对话、提示等。 可以设计组件对话框来处理特定任务，并在同一机器人中或跨多个机器人重复使用它。

提示对话 （提示）是旨在向用户请求特定类型信息（例如数字、日期或名称等）的对话。 提示旨在配合组件对话中的瀑布对话进行工作。

组件对话

有时，你想要编写要在不同方案中使用的可重用对话，例如地址对话框，要求用户提供街道、城市和邮政编码的值。

组件对话提供了一种策略，用于创建独立对话来处理特定方案，从而将大型对话集分解成更易于管理的部分。 每个部分都有自己的对话集，并避免与包含它的对话框集发生任何名称冲突。 有关详细信息，请参阅 组件对话框操作指南。

瀑布对话

瀑布对话是对话的特定实现，通常用于从用户那里收集信息或引导用户完成一系列任务。 会话的每个步骤都作为一个异步函数实现，该函数采用 瀑布步骤上下文 （step） 参数。 在每个步骤中，机器人 都会提示用户输入 （或可以开始子对话，但通常是提示），等待响应，然后将结果传递到下一步。 第一个函数的结果作为参数传递到下一个函数，依此推。

下图显示了一系列瀑布模型的步骤和进行的堆栈操作。 有关使用对话堆栈的详细信息，请参阅 “使用对话” 部分。

在瀑布步骤中，瀑布对话的上下文存储在其 瀑布步骤上下文中。 步骤上下文类似于对话上下文，并提供对当前轮次上下文和状态的访问权限。 使用瀑布步骤上下文对象从瀑布步骤中与对话集进行交互。

可以在对话中的瀑布步骤中或机器人的轮次处理程序中处理对话的返回值，尽管通常只需要检查机器人轮次逻辑中的对话轮次结果的状态。 在瀑布步骤中，对话在瀑布步骤上下文 的结果 属性中提供返回值。

瀑布流程的上下文属性

瀑布步骤上下文包含以下属性：

• 选项：包含对话框的输入信息。
• 值：包含可添加到上下文中的信息，并将其转发到后续步骤中。
• 结果：包含上一步的结果。

此外，next 方法（C# 中的 NextAsync，JavaScript 和 Python 中的 next）继续执行同一轮瀑布对话的下一步，使您的机器人可以在需要时跳过某个步骤。

提示语

对话框库中的提示提供了一种简单的方法，要求用户获取信息并评估其响应。 例如，对于 数字提示，请指定要请求的问题或信息，提示会自动检查它是否收到了有效的数字响应。 如果确实如此，对话可以继续;如果没有，它将为用户重新发送有效答案。

在幕后，提示是由两个步骤组成的对话。 首先，提示要求输入;第二，它返回有效值，或从顶部开始，并重排。

提示在调用提示时提供 提示选项 ，可在其中指定要提示的文本、验证失败时的重试提示以及用于回答提示的选项。 一般情况下，提示和重试提示属性是活动，但不同编程语言对此的处理方式存在一些变化。

此外，还可以选择在创建时为提示添加一些自定义验证。 例如，假设我们想要使用数字提示获取群大小，但该群大小必须大于 2 且小于 12。 提示首先检查它是否收到有效号码，然后运行自定义验证（如果已提供）。 如果自定义验证失败，它将重新提示用户，如上所示。

当提示完成时，它会显式返回所请求的结果值。 返回该值后，我们可以确定它已通过内置提示验证和可能已提供的任何其他自定义验证。

有关使用各种提示的示例，请查看如何使用 对话框库收集用户输入。

提示类型

在幕后，提示是由两个步骤组成的对话。 首先，系统会提示用户输入；然后，它会返回有效值，或者通过重新提示从头开始。 对话库提供了各种基本提示，每个提示用于收集不同类型的响应。 基本提示可以解释自然语言输入，例如数字的“十”或“十二”，或者日期和时间的“明天”或“星期五上午10点”。

提示	DESCRIPTION	退货
附件提示	请求一个或多个附件，例如文档或图像。	附件对象的集合。
选择提示	从一组选项中请求选择。	找到的选择对象。
确认提示	请求确认。	布尔值。
日期和时间提示	请求输入日期时间。	日期时间解析对象的集合。
数字提示	请求一个数字。	数值。
文本提示	要求输入常规文本。	字符串。

若要提示用户输入，请使用其中一个内置类（如 文本提示）定义提示，并将其添加到对话框集。 提示词具有在对话集中必须唯一的固定 ID。 可以为每个提示设置自定义验证程序，对于某些提示，可以指定 默认区域设置。

提示区域设置

区域设置用于确定选择、确认、日期时间和数字提示的语言特定行为。 对于用户的任何给定输入，如果通道在用户的消息中提供了 区域设置 属性，则使用该属性。 否则，如果已设置提示的默认区域设置，则在调用构造函数时提供该设置或稍后设置，然后将使用该设置。 如果未提供这两个区域设置，则英语（“en-us”）用作区域设置。

区域设置是一个表示语言或语言系列的两个、三个或四个字符的 ISO 639 代码。

提示选项

步骤上下文的 提示 方法的第二个参数采用提示 选项 对象，其对象包含以下属性。

资产	DESCRIPTION
提示	向用户发送最初的活动，以请求他们的输入。
重试提示	如果用户的第一个输入验证失败，则触发活动。
选择	供用户选择的选项列表，用于选择提示。
验证	用于自定义验证程序的其他参数。
样式	定义如何向用户显示选择提示或确认提示的选项。

应始终指定要发送给用户的初始提示活动，以及在用户输入未验证时的重试提示。

如果用户的输入无效，则会向用户发送重试提示;如果未指定重试，则使用初始提示。 但是，如果活动从验证器内部发送回用户，则不会发送重试提示。

提示验证

在将值返回到瀑布图的下一步之前，可以验证提示响应。 验证程序函数具有 提示验证器上下文 参数并返回一个布尔值，指示输入是否通过验证。 提示验证程序上下文包含以下属性：

资产	DESCRIPTION
上下文	机器人的当前回合上下文。
认可	识别器结果，包含关于用户输入的信息，该信息由识别器处理。
选项	包含调用中提供的 提示选项 以启动提示。

提示识别器结果具有以下属性：

资产	DESCRIPTION
成功	指示识别器是否能够分析输入。
价值	识别器的返回值。 如有必要，验证代码可以修改此值。

使用对话框

对话框可以视为一个编程堆栈，我们称之为对话堆栈，轮次处理程序负责引导对话堆栈，并在堆栈为空时充当回退。 该堆栈上最顶层的项被视为 活动对话，而对话上下文会将所有输入定向到活动对话。

对话框开始时，它会被推送到堆栈中，现在是活动对话框。 它保持为活动对话，直到它结束、被替换对话方法移除，或另一个对话被推送到堆栈（通过轮次处理程序或活动对话本身）并成为活动对话。 当新对话结束时，它会从堆栈中弹出，下一个对话框将再次变为活动对话。 这允许 重复对话 或 分支对话，如下所述。

可以使用 运行 对话扩展方法开始或继续根对话。 从机器人代码中，调用对话运行扩展方法可以继续现有对话，或者如果堆栈当前为空，则启动对话的新实例。 控件和用户输入将转到堆栈上的活动对话框。

运行方法需要 状态属性访问器 才能访问对话状态。 访问器创建和使用的方式与其他状态访问器相同，但创建为基于会话状态的自己的属性。 可在 管理状态主题中找到有关管理状态的详细信息，对话状态的使用显示在 顺序聊天流 作说明中。

在对话中，你有权访问对话上下文，并可以使用它启动其他对话、结束当前对话并执行其他作。

启动对话框

在瀑布对话中，可以使用开始对话、提示或替换对话方法，将您想要启动的对话的对话 ID传递到瀑布对话的上下文中。

• 提示和开始对话方法会将引用对话的新实例推送到堆栈顶部。
• 替换对话方法将弹出堆栈中的当前对话，并将替换对话推送到堆栈上。 将取消正在替换的对话框，并清除该实例包含的所有信息。

使用 options 参数将信息传递给对话框的新实例。 可以在对话的任何步骤中，通过步骤上下文中的 options 属性访问传入新对话框的选项。 有关详细信息，请参阅如何使用 分支和循环创建高级聊天流。

继续对话

在瀑布对话中，使用步骤上下文的values属性在轮次之间保留状态。 在上一轮中添加到此集合的任何值在后续轮次中都可用。 有关详细信息，请参阅如何使用 分支和循环创建高级聊天流。

结束对话

在瀑布对话中，使用 结束对话 方法，将对话从堆栈中弹出以结束对话。 结束对话方法可以将可选结果返回到父上下文（例如调用它的对话框或机器人的轮次处理程序）。 这通常从对话内部调用，以结束自身的当前实例。

可以在任何具有对话上下文的位置调用结束对话方法，但在机器人看来，它是从当前活动对话调用的。

小窍门

最佳做法是在对话末尾显式调用 结束对话 方法。

清除所有对话框

如果要从堆栈中弹出所有对话，可以通过调用对话上下文取消 所有对话 方法来清除对话堆栈。

重复对话

可以使用 替换对话框 方法将对话替换为自身、创建循环。 这是处理 复杂交互 的好方法，也是管理菜单的一种技术。

注释

如果需要保留当前对话的内部状态，则需要在调用 替换对话框 方法时将信息传递给对话的新实例，然后相应地初始化对话。

对对话进行分支

对话上下文维护对话堆栈，并对于堆栈中的每个对话，实时跟踪即将进行的步骤。 它的 开始对话 方法创建一个子级并将该对话推送到堆栈的顶部，其 结束对话 方法会弹出堆栈中的顶部对话。 结束对话 通常从结束的对话框中调用。

对话可以通过调用对话上下文的 开始对话 方法并提供新对话的 ID，使新对话成为当前活动对话，从而启动同一对话集中的新对话。 原始对话仍在堆栈上，但对对话上下文 的继续对话 方法的调用仅发送到堆栈顶部的对话框，即 活动对话。 当对话从堆栈中弹出时，对话上下文将恢复到堆栈上瀑布的下一步，从原始对话中继续。

因此，可以在聊天流中创建分支，方法是在一个对话框中包括一个步骤，该步骤可以有条件地选择一个对话以从一组可用对话开始。

其他信息

• 有关自适应对话的详细信息，请参阅 自适应对话简介。
• 有关技能的信息，请参阅 技能。