通过

自适应对话中的输入 - 参考指南

  • 项目

适用于：SDK v4

Bot Framework SDK 定义用于收集和验证用户输入的各种输入对话。

输入类型 输入类 说明 返回
基类 InputDialog 这是所有输入类从中派生的基类。 它定义所有共享属性。 一个 对象。
文本 TextInput 用于要求用户提供字词或句子。 一个字符串。
Number NumberInput 用于要求用户提供数字。 数字值。
确认 ConfirmInput 用于请求用户确认。 一个布尔值。
多项选择 ChoiceInput 用于请求从一组选项中选择一个选项。 所选内容的值或索引。
文件或附件 AttachmentInput 用于请求/允许用户上传文件。 附件对象的集合。
日期或时间 DateTimeInput 用于要求用户提供日期和/或时间。 日期时间对象的集合。
Oauth 登录 OAuthInput 用于让用户能够登录到安全站点。 令牌响应。

InputDialog

Bot Framework SDK 提供的输入类均派生自基本输入对话，此对话派生自对话类。 所有输入对话都具有以下公共属性：

AllowInterruptions

一个布尔表达式。 如果父对话中断输入对话，则为 true；否则为 false。

注意

输入父对话也可以中断。 这意味着当 AllowInterruptions 为 true 时，将运行输入父自适应对话中的识别器并计算其触发器。

AlwaysPrompt

一个布尔表达式。 如果为 true，则始终提示输入；如果为 false，则仅在绑定属性为 null 或为空时提示。

DefaultValue

表示输入对话的默认结果的自适应表达式。 如果用户输入失败了 max turn count 轮次，则该输入对话将结束并将默认值设置为此属性。

DefaultValueResponse

用户输入在其验证中失败了 MaxTurnCount 轮次且指定了 DefaultValue 时，要发送的响应。

InvalidPrompt

已识别用户输入，但验证失败时，用于重新提示输入的活动模板。 （如果输入失败了 max turn count 轮次，则将使用 默认值 并发送 默认值响应。）

注意

InvalidPrompt 属性只能与验证属性一起使用。

MaxTurnCount

整数表达式。 请求输入的次数上限。 如果超过此限制，将使用默认值并发送默认值响应。

提示

最初用于提示用户输入的活动模板。

properties

要将输入对话绑定到的属性的内存路径，或计算结果为该内存路径的表达式。 内存路径将用于获取输入对话的初始值。 它还将用于存储此对话的结果。 Prompt 和 Value 属性都经过识别和验证步骤，因此无效的初始值将导致出现提示。

使用此项定义要将输入对话绑定到的属性。 例如：

UnrecognizedPrompt

未识别用户输入时，用于重新提示输入的活动模板。 （如果输入失败了 max turn count 轮次，则将使用 默认值 并发送 默认值响应。）

验证

布尔表达式的列表。 如果其中任何表达式的计算结果为 false，则已识别的输入无效。 可使用 this.value 在验证表达式中检查用户输入。 验证使用自适应表达式表示

值

一个字符串表达式。 要从每轮获取输入的属性的内存路径。 如果输入对话的属性的计算结果为 null 或为空，则此属性将用作该对话的初始值。 如果该对话的 property 和 value 属性的计算结果均为 null 或为空，则该对话将提示输入。

有关 Value 属性的注意事项：

  • Value 属性是自适应表达式。
  • 如果表达式返回 null，则输入对话可能尝试直接从输入中拉取数据。
  • 如果表达式为值，则它将用作输入。
  • 通过 Value 属性，你可以定义将数据（如识别器结果）绑定到输入对话的方式。

示例：

  • 将输入绑定到在输入中识别的任何年龄实体：“=@age”
  • 将 @age 或 @number 用作输入：“=coalesce(@age, @number)”

提示

可在下面的 NumberInput 部分看到使用代码示例中的这些 InputDialog 属性的示例。

TextInput

如果希望逐字接受用户输入作为机器人尝试收集的特定信息的值，请使用文本输入。 示例包括“用户名”和“电子邮件主题”。

TextInput 操作继承了 InputDialog 中定义的所有属性，并定义了一个附加属性：

  • OutputFormat：可使用自适应表达式修改字符串，例如，在下面的代码示例中，OutputFormat 表达式会将用户名的每个单词的首字母大写。

NumberInput

要求用户输入数字。

NumberInput 操作继承了 InputDialog 中定义的所有属性，并定义了以下两个附加属性：

  1. DefaultLocale：设置将使用的处理输入的默认区域设置，除非调用方传递了一个区域设置。 支持的区域设置为西班牙语、荷兰语、英语、法语、德语、日语、葡萄牙语、中文。
  2. OutputFormat：可使用自适应表达式采取操作，以便以某种方式操作数字。 例如，可以编写一个表达式，将输入的给定华氏度温度数值转换为其等效的摄氏度值，对输入的值执行数学计算（例如添加税收和运费），或仅执行类型转换以指定值为浮点数还是整数，如以下示例代码所示。

ConfirmInput

当你向用户提出问题并希望确认他们的回答后，“确认输入”非常有用。 与“多选”操作（使机器人向用户显示可选的列表）不同，确认提示要求用户做出二进制（是/否）决策。

ConfirmInput 操作继承了 InputDialog 中定义的所有属性，并定义了以下附加属性：

  1. ChoiceOptions：用于设置向用户显示的确认选项的显示格式，这是一个计算结果为 ChoiceSet 对象的自适应表达式。 如果首次尝试识别 ConfirmInput 失败，此 ChoiceSet 对象将仅用作备份。 执行 ConfirmInput 操作时，它首先尝试将输入作为布尔值进行计算。 如果此操作失败，则进行第二次尝试，这次使用针对 ChoiceSet 进行计算的选项识别器。
  2. ConfirmChoices：选项，或计算结果为将向用户显示的选项的自适应表达式。
  3. DefaultLocale：设置待使用输入处理的默认区域设置，除非调用方传递了一个区域设置。 支持的区域设置为西班牙语、荷兰语、英语、法语、德语、日语、葡萄牙语、中文
  4. OutputFormat：ConfirmInput 操作的默认输出格式为布尔值。 可以使用 OutputFormat 属性来替代该值，此属性是可用于根据需要修改返回结果的自适应表达式。 例如，你可以使用它来进行 ConfirmInput 操作以返回数字：OutputFormat = "if(this.value == true, 1, 0)"。 如果已设置此属性，则表达式的输出为对话返回的值。
  5. Style：这可定义在确认用户输入时向其显示的列表类型。 这将使用 ListStyle 枚举，其中包含：
    1. None：不要包含任何提示选项。
    2. Auto：自动选择适用于当前通道的样式。
    3. Inline：将选项作为内联列表添加到提示。
    4. List：将选项作为编号列表添加到提示。
    5. SuggestedAction：将选项作为建议的操作添加到提示。
    6. HeroCard：将选项作为带按钮的 HeroCard 添加到提示。

ChoiceInput

“选项输入”是一组以多选形式向用户显示的选项，使你能够向用户呈现可选的选项列表。

ChoiceInput 操作继承了 InputDialog 中定义的所有属性，并定义了以下附加属性：

  1. ChoiceOptions：此属性用于设置向用户显示的确认选项的显示格式。
  2. Choices：一个自适应表达式，其计算结果为 ChoiceSet，其中包含可供用户选择的[已排序]选项列表。
  3. DefaultLocale：设置待使用输入处理的默认区域设置，除非调用方传递了一个区域设置。 支持的区域设置为西班牙语、荷兰语、英语、法语、德语、日语、葡萄牙语、中文
  4. OutputFormat：一个自适应表达式，其计算结果为 ChoiceOutputFormat 枚举值之一。
  5. Style：这可定义在确认用户输入时向其显示的列表类型。 这将使用 ListStyle 枚举，其中包含：
    1. None：不要包含任何提示选项。
    2. Auto：自动选择适用于当前通道的样式。
    3. Inline：将选项作为内联列表添加到提示。
    4. List：将选项作为编号列表添加到提示。
    5. SuggestedAction：将选项作为建议的操作添加到提示。
    6. HeroCard：将选项作为带按钮的 HeroCard 添加到提示。
  6. RecognizerOptions：FindChoicesOptions 或计算结果为 FindChoicesOptions 的表达式。 FindChoicesOptions 具有以下属性：
    1. NoValue：一个布尔值。 如果搜索每个选项的 value 属性，则为 true；否则为 false。 默认为 false。
    2. NoAction：一个布尔值。 如果搜索每个选项的 action 属性的标题，则为 true；否则为 false。 默认为 false。
    3. RecognizeNumbers：一个布尔值。 如果允许使用数字识别器回退输入以匹配输入选项，则为 true；否则为 false。 默认为 true。
    4. RecognizeOrdinals：一个布尔值。 如果允许使用序号识别器回退输入以匹配输入选项，则为 true；否则为 false。 默认为 true。

DateTimeInput

要求提供日期/时间。

DateTimeInput 操作继承了 InputDialog 中定义的所有属性，并定义了以下附加属性：

  1. DefaultLocale：设置待使用输入处理的默认区域设置，除非调用方传递了一个区域设置。 支持的区域设置为西班牙语、荷兰语、英语、法语、德语、日语、葡萄牙语、中文。
  2. OutputFormat：DateTimeInput 的默认输出是 DateTimeResolutions 的数组，通过此属性，你可以定义自适应表达式。 无论其计算结果是否为日期时间，返回的值都将成为对话的 property 属性的最终值。

AttachmentInput

用于向用户请求附件作为输入。

AttachmentInput 操作继承了 InputDialog 中定义的所有属性，并定义了此附加属性：

  • OutputFormat：AttachmentOutputFormat 或计算结果为 AttachmentOutputFormat 的表达式。 有效的 AttachmentOutputFormat 值为：
    1. All：以列表形式返回所有附件。
    2. First：仅返回第一个附件。

OAuthInput

用于请求用户登录。

OAuthInput 操作继承了 InputDialog 中定义的所有属性，并定义了以下附加属性：

  1. ConnectionName：在机器人的“Azure 机器人服务设置”页中配置的 OAuth 连接的名称。
  2. Text：要在登录卡片中显示的附加文本。
  3. Title：要在登录卡片中显示的标题文本。
  4. Timeout：这是 OAuthInput 等待完成用户身份验证的毫秒数。 默认值为 900,000 毫秒，即 15 分钟。

OAuthInput 操作还定义了两种新方法：

  1. GetUserTokenAsync：此方法尝试检索用户的令牌。
  2. SignOutUserAsync：此方法注销用户。

OAuthInput 操作返回一个 TokenResponse 对象，该对象包含 ChannelId、ConnectionName、Token、Expiration 的值。 在下面的示例中，返回值放置在turn内存范围：turn.oauth 内。 可按 LoginSteps() 方法所示从其中访问值：new SendActivity("Here is your token '${turn.oauth.token}'.")。

以下链接提供有关 Microsoft Bot Framework SDK 中身份验证主题的一般信息。 此信息不是针对自适应对话定制或特定的。