在自适应卡片中键入提前搜索

项目
08/14/2023

自适应卡片中的键入头搜索功能在组件上 Input.ChoiceSet 提供了增强的搜索体验。它提供用于在搜索字段中输入文本的选项列表。可以将类型头搜索与自适应卡片合并，以搜索和选择数据。

可以使用类型头搜索进行以下搜索：

静态搜索
动态搜索

静态类型头搜索

静态类型头搜索允许用户从自适应卡片有效负载中指定的 Input.ChoiceSet 值进行搜索。静态类型头搜索可用于向用户显示多个选项。静态搜索中的有效负载大小随着有效负载中指定的选项数而增加。当用户开始输入文本时，将筛选部分匹配输入的选项。下拉列表突出显示与搜索匹配的输入字符。

下图演示了静态类型头搜索：

动态类型头搜索

动态类型头搜索可用于从大型数据集中搜索和选择数据。数据集是从卡有效负载中指定的数据集动态加载的。 typeahead 功能有助于在用户键入时筛选出选项。

桌面设备
移动设备

Android 和 iOS 移动客户端支持自适应卡片中的类型头搜索。

应用场景

John 是一名在 Xbox 零售商店工作的商店员工。应用商店使用机器人从客户那里收到新的购买请求。客户可以从成千上万的游戏中搜索。自适应卡片中的类型头搜索用于搜索和选择客户的选择。

在自适应卡片中使用类型头搜索

用户 A 打开存储机器人。
用户 A 针对 新客户请求向机器人发送命令。机器人使用具有 Input.ChoiceSet 组件的自适应卡进行响应。
用户 A 使用类型头搜索根据客户的选择搜索和选择信息。

下图演示了类型搜索的移动体验：

注意

使用动态搜索（例如基于查询的消息扩展）无法获得丰富的卡体验。

实现类型头搜索

Input.ChoiceSet 是自适应卡中的重要输入组件之一。可以将 typeahead 搜索控件添加到 Input.ChoiceSet 组件以实现类型头搜索。可以使用以下选项搜索和选择所需信息：

下拉列表，例如展开的选择。
单选按钮，例如单选按钮。
复选框，例如多个选择。

注意

控件 Input.ChoiceSet 基于样式和 isMultiSelect 属性。
若要在群聊中使用动态类型头搜索，用户必须在应用清单中将范围添加到 groupchat 机器人安装范围，并将其安装到该特定群组聊天。
下拉列表中的选项数限制为 15 个。

架构属性

以下属性是用于启用类型头搜索的 Input.ChoiceSet 架构新增属性：

属性	类型	必需	说明
style	精简版 Expanded Filtered	否	将筛选样式添加到静态类型支持的验证列表中。
choices.data	Data.Query	否	通过从后端提取一组远程选项，在用户键入时启用动态类型。
值	字符串	否	必须选择的初始选项 (或选项集) 。对于多选，请指定以逗号分隔的值字符串。

Data.Query 定义

属性	类型	必需	说明
type	Data.Query	是	指定它是 Data.Query 对象。
数据	字符串	是	指定动态提取的数据类型。
值	字符串	否	使用用户提供给 `ChoiceSet`的输入填充对机器人的调用请求。
count	数字	否	填充对机器人的调用请求，以指定必须返回的元素数。如果用户想要发送其他数量，机器人将忽略它。
skip	数字	否	填充对机器人的调用请求，以指示用户希望在列表中分页和继续前进。

示例

示例有效负载，其中包含静态和动态类型头搜索以及单选和多选选项，如下所示：

{
  "type": "AdaptiveCard",
  "body": [
    {
      "columns": [
        {
          "width": "1",
          "items": [
            {
              "size": null,
              "url": "https://urlp.asm.skype.com/v1/url/content?url=https%3a%2f%2fi.imgur.com%2fhdOYxT8.png",
              "height": "auto",
              "type": "Image"
            }
          ],
          "type": "Column"
        },
        {
          "width": "2",
          "items": [
            {
              "size": "extraLarge",
              "text": "Game Purchase",
              "weight": "bolder",
              "wrap": true,
              "type": "TextBlock"
            }
          ],
          "type": "Column"
        }
      ],
      "type": "ColumnSet"
    },
    {
      "text": "Please fill out the below form to send a game purchase request.",
      "wrap": true,
      "type": "TextBlock"
    },
    {
      "columns": [
        {
          "width": "auto",
          "items": [
            {
              "text": "Game: ",
              "wrap": true,
              "height": "stretch",
              "type": "TextBlock"
            }
          ],
          "type": "Column"
        }
      ],
      "type": "ColumnSet"
    },
    {
      "columns": [
        {
          "width": "stretch",
          "items": [
            {
              "choices": [
                {
                  "title": "Call of Duty",
                  "value": "call_of_duty"
                },
                {
                  "title": "Death's Door",
                  "value": "deaths_door"
                },
                {
                  "title": "Grand Theft Auto V",
                  "value": "grand_theft"
                },
                {
                  "title": "Minecraft",
                  "value": "minecraft"
                }
              ],
              "style": "filtered",
              "placeholder": "Search for a game",
              "id": "choiceGameSingle",
              "type": "Input.ChoiceSet"
            }
          ],
          "type": "Column"
        }
      ],
      "type": "ColumnSet"
    },
    {
      "columns": [
        {
          "width": "auto",
          "items": [
            {
              "text": "Multi-Game: ",
              "wrap": true,
              "height": "stretch",
              "type": "TextBlock"
            }
          ],
          "type": "Column"
        }
      ],
      "type": "ColumnSet"
    },
    {
      "columns": [
        {
          "width": "stretch",
          "items": [
            {
              "choices": [
                {
                  "title": "Static Option 1",
                  "value": "static_option_1"
                },
                {
                  "title": "Static Option 2",
                  "value": "static_option_2"
                },
                {
                  "title": "Static Option 3",
                  "value": "static_option_3"
                }
              ],
              "value": "Static_option_2",
              "isMultiSelect": true,
              "style": "filtered",
              "choices.data": {
                "type": "Data.Query",
                "dataset": "xbox"
              },
              "id": "choiceGameMulti",
              "type": "Input.ChoiceSet"
            }
          ],
          "type": "Column"
        }
      ],
      "type": "ColumnSet"
    },
    {
      "columns": [
        {
          "width": "auto",
          "items": [
            {
              "text": "Needed by: ",
              "wrap": true,
              "height": "stretch",
              "type": "TextBlock"
            }
          ],
          "type": "Column"
        },
        {
          "width": "stretch",
          "items": [
            {
              "id": "choiceDate",
              "type": "Input.Date"
            }
          ],
          "type": "Column"
        }
      ],
      "type": "ColumnSet"
    },
    {
      "text": "Buy and download digital games and content directly from your Xbox console, Windows 10 PC, or at Xbox.com.",
      "wrap": true,
      "type": "TextBlock"
    },
    {
      "text": "Earn points for what you already do on Xbox, then redeem your points on real rewards. Play more, get rewarded. Start earning today.",
      "wrap": true,
      "type": "TextBlock"
    }
  ],
  "actions": [
    {
      "data": {
        "msteams": {
          "type": "invoke",
          "value": {
            "type": "task/submit"
          }
        }
      },
      "title": "Request Purchase",
      "type": "Action.Submit"
    }
  ],
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "version": "1.2"
}

用于调用请求和响应的代码片段

调用请求

{
    "name": "application/search",
    "type": "invoke",
    "value": {
        "queryText": "fluentui",
        "queryOptions": {
            "skip": 0,
            "top": 15
        },
        "dataset": "npm"
    },
    "locale": "en-US",
    "localTimezone": "America/Los_Angeles",
    // …. other fields
}

响应

protected override async Task<InvokeResponse> OnInvokeActivityAsync(ITurnContext<IInvokeActivity> turnContext, CancellationToken cancellationToken)
{
    if (turnContext.Activity.Name == "application/search")
    {
 var packages = new[] {
   new { title = "A very extensive set of extension methods", value = "FluentAssertions" },
   new { title = "Fluent UI Library", value = "FluentUI" }};

 var searchResponseData = new
 {
     type = "application/vnd.microsoft.search.searchResponse",
     value = new
     {
  results = packages
     }
 };
 var jsonString = JsonConvert.SerializeObject(searchResponseData);
 JObject jsonData = JObject.Parse(jsonString);
 return new InvokeResponse()
 {
     Status = 200,
     Body = jsonData
 };
    }

    return null;
}

  async onInvokeActivity(context) {
    if (context._activity.name == 'application/search') {
      // let searchQuery = context._activity.value.queryText;  // This can be used to filter the results
      var successResult = {
        status: 200,
        body: {
          "type": "application/vnd.microsoft.search.searchResponse",
          "value": {
            "results": [
              {
                "value": "FluentAssertions",
                "title": "A very extensive set of extension methods"
              },
              {
                "value": "FluentUI",
                "title": "Fluent UI Library"
              }
            ]
          }
        }
      }

      return successResult;

    }
  }

{
    "status": 200,
    "body" : {
        "type": "application/vnd.microsoft.search.searchResponse",
        "value": {
           "results": [
                {
                    "value": "FluentAssertions",
                    "title": "A very extensive set of extension methods."
                },
                {
                    "value": "FluentUI",
                    "title": "Fluent UI Library"
                }
            ]
        }
    }
}

代码示例

示例名称	说明	.NET	Node.js	清单
自适应卡片上的 Typeahead 搜索控件	此示例演示如何在自适应卡片中使用静态和动态类型头搜索控件。	View	View	View