您现在访问的是微软AZURE全球版技术文档网站,若需要访问由世纪互联运营的MICROSOFT AZURE中国区技术文档网站,请访问 https://docs.azure.cn.

使用模式语言自定义用户体验Customize user experience with pattern language

备注

本主题适用于 SDK v3 版本。This topic applies to SDK v3 release. 可以在此处找到最新版 SDK (v4) 的文档。You can find the documentation for the latest version of the SDK v4 here.

自定义提示或重写默认模板时,可以使用模式语言指定提示的内容和/或格式。When you customize a prompt or override a default template, you can use pattern language to specify the contents and/or format of the prompt.

提示和模板Prompts and templates

提示定义发送给用户以请求信息片段或请求确认的消息。A prompt defines the message that is sent to the user to request a piece of information or ask for confirmation. 可以使用 Prompt 属性自定义提示,或者通过 IFormBuilder.Field 隐式自定义提示。You can customize a prompt by using the Prompt attribute or implicitly through IFormBuilder.Field.

窗体使用模板来自动构建提示和其他内容,例如帮助。Forms use templates to automatically construct prompts and other things such as help. 可以使用 Template 属性重写某个类或字段的默认模板。You can override the default template of a class or field by using the Template attribute.

提示

FormConfiguration.Templates 类定义一组内置模板,这些模板提供有关如何使用模式语言的极佳示例。The FormConfiguration.Templates class defines a set of built-in templates that provide good examples of how to use pattern language.

模式语言的元素Elements of pattern language

模式语言使用大括号 ({}) 来标识要在运行时替换为实际值的元素。Pattern language uses curly braces ({}) to identify elements that will be replaced at runtime with actual values. 下表列出了模式语言的元素。This table lists the elements of pattern language.

元素Element 说明Description
{<format>} 显示当前字段(该属性应用到的字段)的值。Shows the value of the current field (the field that the attribute applies to).
{&} 显示当前字段的说明(除非另有指定,否则是该字段的名称)。Shows the description of the current field (unless otherwise specified, this is the name of the field).
{<field><format>} 显示命名字段的值。Shows the value of the named field.
{&<field>} 显示命名字段的说明。Shows the description of the named field.
{||} 显示当前选项,可以是字段的当前值、“无首选项”或枚举的值。Shows the current choice(s), which could be the current value of a field, "no preference" or the values of an enumeration.
{[{<field><format>} ...]} 显示命名字段中的值列表,该列表中的各个值以 SeparatorLastSeparator 分隔。Shows a list of values from the named fields using Separator and LastSeparator to separate the individual values in the list.
{*} 为每个活动字段显示一行;每行包含字段说明和当前值。Shows one line for each active field; each line contains the field description and current value.
{*filled} 为包含实际值的每个活动字段显示一行;每行包含字段说明和当前值。Shows one line for each active field that contains an actual value; each line contains the field description and current value.
{<nth><format>} 应用到模板第 n 个参数的常规 C# 格式说明符。A regular C# format specifier that applies to the nth argument of a template. 有关可用参数的列表,请参阅 TemplateUsageFor the list of available arguments, see TemplateUsage.
{?<textOrPatternElement>...} 条件替代。Conditional substitution. 如果引用模式元素的所有对象包含值,则会替代值,并使用整个表达式。If all referred to pattern elements have values, the values are substituted and the whole expression is used.

对于上面列出的元素:For the elements listed above:

  • <field> 占位符是 form 类中的字段名称。The <field> placeholder is the name of a field in your form class. 例如,如果类包含名称为 Size 的字段,则你可以指定 {Size} 作为模式元素。For example, if your class contains a field with the name Size, you could specify {Size} as the pattern element.

  • 模式元素中的省略号 ("...") 指示该元素可能包含多个值。An ellipses ("...") within a pattern element indicates that the element may contain multiple values.

  • <format> 占位符是 C# 格式说明符。The <format> placeholder is a C# format specifier. 例如,如果类包含名称为 Rating、类型为 double 的字段,则你可以指定 {Rating:F2} 作为模式元素来以两位数的精度显示数据。For example, if the class contains a field with the name Rating and of type double, you could specify {Rating:F2} as the pattern element to show two digits of precision.

  • <nth> 占位符引用模板的第 n 个参数。The <nth> placeholder references the nth argument of a template.

Prompt 属性中的模式语言Pattern language within a Prompt attribute

此示例使用 {&} 元素显示 Sandwich 字段的说明,并使用{||} 元素显示该字段的选项列表。This example uses the {&} element to show the description of the Sandwich field and the {||} element to show the list of choices for that field.

[Prompt("What kind of {&} would you like? {||}")]
public SandwichOptions? Sandwich;

生成的提示如下:This is the resulting prompt:

What kind of sandwich would you like?
1. BLT
2. Black Forest Ham
3. Buffalo Chicken
4. Chicken And Bacon Ranch Melt
5. Cold Cut Combo
6. Meatball Marinara
7. Oven Roasted Chicken
8. Roast Beef
9. Rotisserie Style Chicken
10. Spicy Italian
11. Steak And Cheese
12. Sweet Onion Teriyaki
13. Tuna
14. Turkey Breast
15. Veggie
>

设置参数格式Formatting parameters

提示和模板支持以下格式参数。Prompts and templates support these formatting parameters.

使用情况Usage 说明Description
AllowDefault 适用于 {||} 模式元素。Applies to {||} pattern elements. 确定窗体是否应显示字段的当前值作为可能的选项。Determines whether the form should show the current value of the field as a possible choice. 如果为 true,则显示当前值作为可能值。If true, the current value is shown as a possible value. 默认为 trueThe default is true.
ChoiceCase 适用于 {||} 模式元素。Applies to {||} pattern elements. 确定是否规范化每个选项的文本(例如,是否将每个单词的第一个字母大写)。Determines whether the text of each choice is normalized (e.g., whether the first letter of each word is capitalized). 默认为 CaseNormalization.NoneThe default is CaseNormalization.None. 有关可能值,请参阅 CaseNormalizationFor possible values, see CaseNormalization.
ChoiceFormat 适用于 {||} 模式元素。Applies to {||} pattern elements. 确定是要以编号列表还是项目符号列表的形式显示选项列表。Determines whether to show a list of choices as a numbered list or a bulleted list. 若要使用编号列表,请将 ChoiceFormat 设置为 {0}(默认值)。For a numbered list, set ChoiceFormat to {0} (default). 若要使用项目编号列表,请将 ChoiceFormat 设置为 {1}For a bulleted list list, set ChoiceFormat to {1}.
ChoiceLastSeparator 适用于 {||} 模式元素。Applies to {||} pattern elements. 确定内联选项列表是否在最后一个选项的前面包含分隔符。Determines whether an inline list of choices includes a separator before the last choice.
ChoiceParens 适用于 {||} 模式元素。Applies to {||} pattern elements. 确定是否在括号中显示内联选项列表。Determines whether an inline list of choices is shown within parentheses. 如果为 true,则在括号中显示选项列表。If true, the list of choices is shown within parentheses. 默认为 trueThe default is true.
ChoiceSeparator 适用于 {||} 模式元素。Applies to {||} pattern elements. 确定内联选项列表是否在除最后一个选项以外的每个选项的前面包含分隔符。Determines whether an inline list of choices includes a separator before every choice except the last choice.
ChoiceStyle 适用于 {||} 模式元素。Applies to {||} pattern elements. 确定是要内联还是逐行的形式显示选项列表。Determines whether the list of choices is shown inline or per line. 默认值为 ChoiceStyleOptions.Auto,确定在运行时是要以内联还是列表形式显示选项。The default is ChoiceStyleOptions.Auto which determines at runtime whether to show the choice inline or in a list. 有关可能值,请参阅 ChoiceStyleOptionsFor possible values, see ChoiceStyleOptions.
Feedback 仅适用于提示。Applies to prompts only. 确定窗体是否回显用户的选项,以指示窗体能够识别所做的选择。Determines whether the form echoes the user's choice to indicate that the form understood the selection. 默认值为 FeedbackOptions.Auto,即,仅当有一部分用户输入内容不可识别时,才回显该内容。The default is FeedbackOptions.Auto which echoes the user's input only if part of it is not understood. 有关可能值,请参阅 FeedbackOptionsFor possible values, see FeedbackOptions.
FieldCase 确定是否规范化字段说明的文本(例如,是否将每个单词的第一个字母大写)。Determines whether the text of the field's description is normalized (e.g., whether the first letter of each word is capitalized). 默认值为 CaseNormalization.Lower,即,将说明转换为小写。The default is CaseNormalization.Lower which converts the description to lowercase. 有关可能值,请参阅 CaseNormalizationFor possible values, see CaseNormalization.
LastSeparator 适用于 {[]} 模式元素。Applies to {[]} pattern elements. 确定项数组是否在最后一个项的前面包含分隔符。Determines whether an array of items includes a separator before the last item.
Separator 适用于 {[]} 模式元素。Applies to {[]} pattern elements. 确定项数组是否在数组中除最后一项以外的每个项的前面包含分隔符。Determines whether an array of items includes a separator before every item in the array except the last item.
ValueCase 确定是否规范化字段值的文本(例如,是否将每个单词的第一个字母大写)。Determines whether the text of the field's value is normalized (e.g., whether the first letter of each word is capitalized)_. 默认值为 CaseNormalization.InitialUpper,即,将每个单词的第一个字母转换为大写。The default is CaseNormalization.InitialUpper which converts the first letter of each word to uppercase. 有关可能值,请参阅 CaseNormalizationFor possible values, see CaseNormalization.

包含格式参数的 Prompt 属性Prompt attribute with formatting parameter

此示例使用 ChoiceFormat 参数来指定应以项目符号列表的形式显示选项列表。This example uses the ChoiceFormat parameter to specify that the list of choices should be displayed as a bulleted list.

[Prompt("What kind of {&} would you like? {||}", ChoiceFormat="{1}")]
public SandwichOptions? Sandwich;

生成的提示如下:This is the resulting prompt:

What kind of sandwich would you like?
* BLT
* Black Forest Ham
* Buffalo Chicken
* Chicken And Bacon Ranch Melt
* Cold Cut Combo
* Meatball Marinara
* Oven Roasted Chicken
* Roast Beef
* Rotisserie Style Chicken
* Spicy Italian
* Steak And Cheese
* Sweet Onion Teriyaki
* Tuna
* Turkey Breast
* Veggie
>

示例代码Sample code

有关演示如何使用 Bot Framework SDK for .NET 实现 FormFlow 的完整示例,请参阅 GitHub 中的多对话机器人示例Contoso Flowers 机器人示例For complete samples that show how to implement FormFlow using the Bot Framework SDK for .NET, see the Multi-Dialog Bot sample and the Contoso Flowers Bot sample in GitHub.

其他资源Additional resources