Вызов и закрытие диалоговых окон в пакете SDK для Teams

В этой статье описывается, как вызывать и закрывать диалоги (ранее называемые модулями задач) с помощью пакета SDK Для Teams (библиотека ИИ Teams). В пакете SDK для Teams диалоговые окна вызываются из действий адаптивной карточки с помощью TaskFetchAction и обрабатываются посредством открытия диалогового окна и отправки событий в App классе .

Регистрация события зависит от языка:

• TypeScript: app.on('dialog.open', ...) и app.on('dialog.submit', ...)
• C#: teamsApp.OnTaskFetch(...) и teamsApp.OnTaskSubmit(...)
• Python: @app.on_dialog_open и @app.on_dialog_submit

Содержимое диалогового окна может быть адаптивной карточкой или веб-страницей на основе URL-адреса.

Диалоговые окна также можно вызывать с помощью других подходов в зависимости от архитектуры приложения:

• На вкладках с помощью клиентской библиотеки TeamsJS. См . раздел Использование диалоговых окон на вкладках.
• Из ботов, использующих Bot Framework или глубокие ссылки. См . раздел Использование диалогов с ботами.
• Из URL-адреса прямой ссылки. Чтобы открыть диалоговое окно, см. раздел Прямая ссылка.

Рекомендации по миграции из Bot Framework в пакет SDK для Teams см. в разделе Миграция из BotBuilder.

В следующей таблице показано, как работают диалоги в пакете SDK для Teams.

Шаг	Диалоговое окно с адаптивной карточкой	Диалоговое окно с URL-адресом веб-страницы
Активация диалогового окна	1. Отправьте пользователю адаптивную карточку с кнопкой TaskFetchAction . Данные действия value указывают тип открываемого диалогового окна. 2. Когда пользователь нажимает кнопку, Teams отправляет в приложение вызов получения задачи.	1. Отправьте пользователю адаптивную карточку с кнопкой TaskFetchAction . 2. Когда пользователь нажимает кнопку, Teams отправляет в приложение вызов получения задачи.
Обработка события открытия диалогового окна	3. В обработчике открытия диалогового окна верните ответ модуля задачи continue, содержащий метаданные диалога (заголовок, измерения и отображаемая адаптивная карточка). В C# используйте TaskInfo с оболочкой ContinueTask . В TypeScript используйте CardTaskModuleTaskInfo. В Python используйте CardTaskModuleTaskInfo в .TaskModuleContinueResponse	3. В обработчике открытия диалогового окна верните ответ модуля задачи continue, содержащий метаданные диалога со свойством url , указывающим на веб-страницу. Домен URL-адреса должен находиться в массиве манифеста validDomains приложения. В C# используйте TaskInfo. В TypeScript используйте UrlTaskModuleTaskInfo. В Python используйте UrlTaskModuleTaskInfo в .TaskModuleContinueResponse
Обработка отправки диалогового окна	4. Когда пользователь нажимает кнопку Action.Submit , Teams отправляет в приложение вызов отправки задачи с данными формы. 5. Вы можете ответить следующим образом: • Ничего не делать (задача завершена) • Отображение сообщения (C#: MessageTask, TypeScript/Python: TaskModuleMessageResponse) • Связывание с другим диалоговым окном (C#: ContinueTask, TypeScript/Python: TaskModuleContinueResponse)	4. Веб-страница вызывает клиентную библиотеку Teams JS для отправки данных обратно. Teams отправляет в приложение вызов отправки задачи с результатом.

В следующем разделе описываются метаданные диалога, определяющие содержимое и внешний вид диалога.

Метаданные диалога

Метаданные диалога определяют содержимое и внешний вид диалога. Каждый язык использует собственные типы для представления этих метаданных:

• C#: TaskInfo (из Microsoft.Teams.Api.TaskModules)
• TypeScript: CardTaskModuleTaskInfo или UrlTaskModuleTaskInfo (из @microsoft/teams.api)
• Python: CardTaskModuleTaskInfo или UrlTaskModuleTaskInfo (из microsoft_teams.api)

В следующей таблице перечислены общие свойства для всех языков:

Атрибут	Тип	Описание
title	string	Этот атрибут выводится под названием приложения, справа от его значка.
height	number или string	Этот атрибут может быть числом, представляющим высоту диалога в пикселях, или small, mediumили large. В C# используйте Union<int, Size>.
width	number или string	Этот атрибут может быть числом, представляющим ширину диалогового окна в пикселях, или small, mediumили large. В C# используйте Union<int, Size>.
url	string	URL-адрес страницы, загруженной <iframe> в диалоговом окне. Домен URL-адреса должен находиться в массиве validDomains приложения в манифесте приложения. Используйте UrlTaskModuleTaskInfo в TypeScript или Python или задайте Url для свойства значение TaskInfo в C#.
card	Вложение	Адаптивная карточка, отображаемая в диалоговом окне. В C# присвойте свойству Card значение AttachmentTaskInfo . В TypeScript используйте с cardAttachment()CardTaskModuleTaskInfo. В Python используйте с card_attachment(AdaptiveCardAttachment(...))CardTaskModuleTaskInfo.

Примечание.

Функция диалогового окна требует, чтобы домены всех URL-адресов, которые вы хотите загрузить, были включены в validDomains массив в манифесте приложения.

В следующем разделе указывается размер диалогового окна, который позволяет пользователю задавать высоту и ширину диалогового окна.

Изменение размера диалогового окна

Значения width и height задайте высоту и ширину диалогового окна в пикселях. В зависимости от размера окна Teams и разрешения экрана эти значения могут быть уменьшены пропорционально при сохранении пропорций.

Если width и height представляют собой small, mediumили large, размер красного прямоугольника на следующем изображении пропорционален размерам доступного пространства, а именно 20 %, 50 % и 60 % для width и 20 %, 50 % и 66 % для height:

В следующем разделе приведены примеры запуска и обработки диалоговых окон с помощью пакета SDK для Teams.

Запуск диалогового окна с помощью TaskFetchAction

Чтобы открыть диалоговое окно, отправьте адаптивную карточку с кнопкой TaskFetchAction . Когда пользователь нажимает кнопку, Teams отправляет вызов задачи, чтобы получить вызов в приложение. Данные каждой value кнопки указывают тип открываемого диалогового окна (например, { "data": "AdaptiveCard" }).

C#

using Microsoft.Teams.Api.Activities;
using Microsoft.Teams.Cards;

teamsApp.OnMessage(async (context) =>
{
    var card = new AdaptiveCard
    {
        Body = new List<CardElement>
        {
            new TextBlock("Task Module Invocation from Adaptive Card")
            {
                Weight = TextWeight.Bolder,
                Size = TextSize.Large
            }
        },
        Actions = new List<Action>
        {
            new TaskFetchAction(new Dictionary<string, object?> { { "data", "AdaptiveCard" } })
            { Title = "Adaptive Card" },
            new TaskFetchAction(new Dictionary<string, object?> { { "data", "CustomForm" } })
            { Title = "Custom Form" },
            new TaskFetchAction(new Dictionary<string, object?> { { "data", "MultiStep" } })
            { Title = "Multi-step Form" }
        }
    };

    await context.Send(new MessageActivity
    {
        Attachments = new List<Attachment>
        {
            new Attachment
            {
                ContentType = new ContentType("application/vnd.microsoft.card.adaptive"),
                Content = card
            }
        }
    });
});

TypeScript

import { Attachment, cardAttachment } from '@microsoft/teams.api';
import { App } from '@microsoft/teams.apps';
import {
  AdaptiveCard,
  TextBlock,
  TaskFetchAction,
} from '@microsoft/teams.cards';

function createTaskModuleAdaptiveCard(): Attachment {
  const card = new AdaptiveCard(
    new TextBlock('Task Module Invocation from Adaptive Card', { weight: 'Bolder', size: 'Large' }),
  ).withVersion('1.4').withActions(
    new TaskFetchAction({ data: 'AdaptiveCard' }).withTitle('Adaptive Card'),
    new TaskFetchAction({ data: 'CustomForm' }).withTitle('Custom Form'),
    new TaskFetchAction({ data: 'MultiStep' }).withTitle('Multi-step Form'),
  );
  return cardAttachment('adaptive', card);
}

app.message(/.*/i, async (context) => {
  await context.send({
    type: 'message',
    attachments: [createTaskModuleAdaptiveCard()],
  });
});

Python

from microsoft_teams.api import MessageActivity, MessageActivityInput
from microsoft_teams.apps import ActivityContext
from microsoft_teams.cards import AdaptiveCard, TextBlock, TaskFetchAction

@app.on_message
async def handle_message(context: ActivityContext[MessageActivity]) -> None:
    adaptive_card = AdaptiveCard(version="1.4").with_body(
        [TextBlock(text="Task Module Invocation from Adaptive Card", weight="Bolder", size="Large")]
    ).with_actions(
        [
            TaskFetchAction(value={"data": "AdaptiveCard"}).with_title("Adaptive Card"),
            TaskFetchAction(value={"data": "CustomForm"}).with_title("Custom Form"),
            TaskFetchAction(value={"data": "MultiStep"}).with_title("Multi-step Form"),
        ]
    )

    message = MessageActivityInput().add_card(adaptive_card)
    await context.send(message)

Обработка события открытия диалогового окна

Когда Teams отправляет вызов получения задачи, приложение возвращает содержимое диалогового окна. Содержимое может быть адаптивной карточкой или URL-адресом веб-страницы. В C# заключите метаданные диалога в ContinueTask ответ. В TypeScript возвращает с TaskModuleResponsetype: 'continue'помощью . В Python возвращает объект InvokeResponse , содержащий TaskModuleContinueResponse.

C#

using System.Text.Json;
using Microsoft.Teams.Api.TaskModules;
using Microsoft.Teams.Cards;
using Microsoft.Teams.Common;

teamsApp.OnTaskFetch(async (context) =>
{
    var activity = context.Activity;
    var json = JsonSerializer.Deserialize<JsonElement>(JsonSerializer.Serialize(activity));
    var data = json.GetProperty("value").GetProperty("data").GetProperty("data").GetString();

    TaskInfo taskInfo;

    if (data == "CustomForm")
    {
        taskInfo = new TaskInfo
        {
            Title = "Custom Form",
            Width = new Union<int, Size>(510),
            Height = new Union<int, Size>(450),
            Url = $"{botEndpoint}/customform",
            FallbackUrl = $"{botEndpoint}/customform"
        };
    }
    else if (data == "MultiStep")
    {
        var step1Card = new AdaptiveCard
        {
            Body = new List<CardElement>
            {
                new TextBlock("Step 1 of 2 - Your Name") { Size = TextSize.Large, Weight = TextWeight.Bolder },
                new TextInput { Id = "name", Label = "Name", Placeholder = "Enter your name", IsRequired = true }
            },
            Actions = new List<Action>
            {
                new SubmitAction().WithTitle("Next").WithData(
                    new Union<string, SubmitActionData>(new SubmitActionData
                    {
                        NonSchemaProperties = new Dictionary<string, object?> { { "submissiontype", "multi_step_1" } }
                    }))
            }
        };

        taskInfo = new TaskInfo
        {
            Title = "Multi-step Form",
            Width = new Union<int, Size>(400),
            Height = new Union<int, Size>(300),
            Card = new Attachment
            {
                ContentType = new ContentType("application/vnd.microsoft.card.adaptive"),
                Content = step1Card
            }
        };
    }
    else
    {
        var dialogCard = new AdaptiveCard
        {
            Body = new List<CardElement>
            {
                new TextBlock("Enter Text Here") { Weight = TextWeight.Bolder },
                new TextInput { Id = "usertext", Placeholder = "add some text and submit", IsMultiline = true }
            },
            Actions = new List<Action> { new SubmitAction { Title = "Submit" } }
        };

        taskInfo = new TaskInfo
        {
            Title = "Adaptive Card: Inputs",
            Width = new Union<int, Size>(400),
            Height = new Union<int, Size>(200),
            Card = new Attachment
            {
                ContentType = new ContentType("application/vnd.microsoft.card.adaptive"),
                Content = dialogCard
            }
        };
    }

    return new Response(new ContinueTask(taskInfo));
});

TypeScript

import {
  Attachment,
  TaskModuleRequest,
  TaskModuleResponse,
  UrlTaskModuleTaskInfo,
  CardTaskModuleTaskInfo,
  cardAttachment,
} from '@microsoft/teams.api';
import { AdaptiveCard, TextBlock, TextInput, SubmitAction } from '@microsoft/teams.cards';

function createTextInputCard(): Attachment {
  const card = new AdaptiveCard(
    new TextBlock('Enter Text Here', { weight: 'Bolder' }),
    new TextInput({ id: 'usertext', placeholder: 'add some text and submit', isMultiline: true }),
  ).withVersion('1.0').withActions(
    new SubmitAction({ title: 'Submit' }),
  );
  return cardAttachment('adaptive', card);
}

function createMultiStepStep1Card(): Attachment {
  const card = new AdaptiveCard(
    new TextBlock('Step 1 of 2 - Your Name', { size: 'Large', weight: 'Bolder' }),
    new TextInput({ id: 'name', label: 'Name', placeholder: 'Enter your name', isRequired: true }),
  ).withVersion('1.4').withActions(
    new SubmitAction({ title: 'Next', data: { submissiontype: 'multi_step_1' } }),
  );
  return cardAttachment('adaptive', card);
}

app.on('dialog.open', async (context) => {
  const taskModuleRequest = context.activity.value as TaskModuleRequest;
  const cardData = taskModuleRequest.data?.data ?? 'AdaptiveCard';

  if (cardData === 'CustomForm') {
    const taskInfo: UrlTaskModuleTaskInfo = {
      title: 'Custom Form',
      width: 510,
      height: 450,
      url: `${BOT_ENDPOINT}/CustomForm/`,
      fallbackUrl: `${BOT_ENDPOINT}/CustomForm/`,
    };
    return { task: { type: 'continue', value: taskInfo } } as TaskModuleResponse;
  }

  if (cardData === 'MultiStep') {
    const taskInfo: CardTaskModuleTaskInfo = {
      title: 'Multi-step Form',
      width: 400,
      height: 300,
      card: createMultiStepStep1Card(),
    };
    return { task: { type: 'continue', value: taskInfo } } as TaskModuleResponse;
  }

  // Default: AdaptiveCard
  const taskInfo: CardTaskModuleTaskInfo = {
    title: 'Adaptive Card: Inputs',
    width: 400,
    height: 200,
    card: createTextInputCard(),
  };
  return { task: { type: 'continue', value: taskInfo } } as TaskModuleResponse;
});

Python

from microsoft_teams.api import (
    AdaptiveCardAttachment,
    CardTaskModuleTaskInfo,
    InvokeResponse,
    TaskFetchInvokeActivity,
    TaskModuleContinueResponse,
    TaskModuleResponse,
    UrlTaskModuleTaskInfo,
    card_attachment,
)
from microsoft_teams.apps import ActivityContext
from microsoft_teams.cards import AdaptiveCard, SubmitAction, SubmitActionData, TextBlock, TextInput

@app.on_dialog_open
async def handle_dialog_open(context: ActivityContext[TaskFetchInvokeActivity]):
    data = context.activity.value.data
    card_data = data.get("data") if isinstance(data, dict) else data

    if card_data == "CustomForm":
        return InvokeResponse(
            body=TaskModuleResponse(
                task=TaskModuleContinueResponse(
                    value=UrlTaskModuleTaskInfo(
                        title="Custom Form",
                        width=510,
                        height=450,
                        url=f"{os.getenv('BOT_ENDPOINT', 'http://localhost:3978')}/customform",
                        fallback_url=f"{os.getenv('BOT_ENDPOINT', 'http://localhost:3978')}/customform",
                    )
                )
            )
        )

    elif card_data == "MultiStep":
        dialog_card = AdaptiveCard(version="1.4").with_body([
            TextBlock(text="Step 1 of 2 - Your Name", size="Large", weight="Bolder"),
            TextInput().with_id("name").with_label("Name").with_placeholder("Enter your name").with_is_required(True),
        ]).with_actions([
            SubmitAction().with_title("Next").with_data(
                SubmitActionData().with_data({"submissiontype": "multi_step_1"})
            ),
        ])

        return InvokeResponse(
            body=TaskModuleResponse(
                task=TaskModuleContinueResponse(
                    value=CardTaskModuleTaskInfo(
                        title="Multi-step Form",
                        width=400,
                        height=300,
                        card=card_attachment(AdaptiveCardAttachment(content=dialog_card)),
                    )
                )
            )
        )

    dialog_card = AdaptiveCard(version="1.0").with_body([
        TextBlock(text="Enter Text Here", weight="Bolder"),
        TextInput().with_id("usertext").with_placeholder("add some text and submit").with_is_multiline(True),
    ]).with_actions([
        SubmitAction().with_title("Submit"),
    ])

    return InvokeResponse(
        body=TaskModuleResponse(
            task=TaskModuleContinueResponse(
                value=CardTaskModuleTaskInfo(
                    title="Adaptive Card: Inputs",
                    width=400,
                    height=200,
                    card=card_attachment(AdaptiveCardAttachment(content=dialog_card)),
                )
            )
        )
    )

Обработка отправки диалогового окна

Когда пользователь нажимает Action.Submit в диалоговом окне, Teams отправляет задачу отправить вызов в приложение. Вы можете ответить, выполнив задачу, отобразив сообщение или открыв другое диалоговое окно (например, для цепочки многоэтапных форм).

C#

using System.Text.Json;
using Microsoft.Teams.Api.TaskModules;
using Microsoft.Teams.Cards;
using Microsoft.Teams.Common;

teamsApp.OnTaskSubmit(async (context) =>
{
    var activity = context.Activity;
    var json = JsonSerializer.Deserialize<JsonElement>(JsonSerializer.Serialize(activity));
    var submitData = JsonSerializer.Deserialize<Dictionary<string, object>>(
        json.GetProperty("value").GetProperty("data").GetRawText());
    var submissionType = submitData?.GetValueOrDefault("submissiontype")?.ToString();

    if (submissionType == "multi_step_1")
    {
        var name = submitData["name"]?.ToString();
        var step2Card = new AdaptiveCard
        {
            Body = new List<CardElement>
            {
                new TextBlock("Step 2 of 2 - Your Email") { Size = TextSize.Large, Weight = TextWeight.Bolder },
                new TextInput { Id = "email", Label = "Email", Placeholder = "Enter your email", IsRequired = true }
            },
            Actions = new List<Action>
            {
                new SubmitAction().WithTitle("Submit").WithData(
                    new Union<string, SubmitActionData>(new SubmitActionData
                    {
                        NonSchemaProperties = new Dictionary<string, object?>
                        {
                            { "submissiontype", "multi_step_2" },
                            { "name", name! }
                        }
                    }))
            }
        };

        var taskInfo = new TaskInfo
        {
            Title = "Multi-step Form: Step 2",
            Width = new Union<int, Size>(400),
            Height = new Union<int, Size>(300),
            Card = new Attachment
            {
                ContentType = new ContentType("application/vnd.microsoft.card.adaptive"),
                Content = step2Card
            }
        };

        return new Response(new ContinueTask(taskInfo));
    }

    if (submissionType == "multi_step_2")
    {
        await context.Send($"Hi {submitData["name"]}, thanks for submitting! Your email is {submitData["email"]}");
        return new Response(new MessageTask("Multi-step form completed!"));
    }

    var usertext = submitData?.GetValueOrDefault("usertext")?.ToString();
    await context.Send($"You submitted: {usertext}");
    return new Response(new MessageTask("Thanks for submitting!"));
});

TypeScript

import {
  TaskModuleRequest,
  TaskModuleResponse,
  CardTaskModuleTaskInfo,
} from '@microsoft/teams.api';

app.on('dialog.submit', async (context) => {
  const taskModuleRequest = context.activity.value as TaskModuleRequest;
  const data = taskModuleRequest.data || {};
  const submissionType = typeof data === 'object' ? data.submissiontype : undefined;

  if (submissionType === 'multi_step_1') {
    const taskInfo: CardTaskModuleTaskInfo = {
      title: 'Multi-step Form: Step 2',
      width: 400,
      height: 300,
      card: createMultiStepStep2Card(data.name),
    };
    return { task: { type: 'continue', value: taskInfo } } as TaskModuleResponse;
  }

  if (submissionType === 'multi_step_2') {
    const { name, email } = data;
    await context.send(`Hi ${name}, thanks for submitting! Your email is ${email}`);
    return { task: { type: 'message', value: 'Multi-step form completed!' } } as TaskModuleResponse;
  }

  // Default: adaptive card text input
  const usertext = data?.usertext;
  await context.send(`You submitted: ${usertext}`);
  return { task: { type: 'message', value: 'Thanks for submitting!' } } as TaskModuleResponse;
});

Python

from microsoft_teams.api import (
    AdaptiveCardAttachment,
    CardTaskModuleTaskInfo,
    InvokeResponse,
    TaskModuleContinueResponse,
    TaskModuleMessageResponse,
    TaskModuleResponse,
    TaskSubmitInvokeActivity,
    card_attachment,
)
from microsoft_teams.apps import ActivityContext
from microsoft_teams.cards import AdaptiveCard, SubmitAction, SubmitActionData, TextBlock, TextInput

@app.on_dialog_submit
async def handle_dialog_submit(context: ActivityContext[TaskSubmitInvokeActivity]):
    data = context.activity.value.data
    submission_type = data.get("submissiontype") if isinstance(data, dict) else None

    if submission_type == "multi_step_1":
        name = data.get("name")
        next_card = AdaptiveCard(version="1.4").with_body([
            TextBlock(text="Step 2 of 2 - Your Email", size="Large", weight="Bolder"),
            TextInput().with_id("email").with_label("Email").with_placeholder("Enter your email").with_is_required(True),
        ]).with_actions([
            SubmitAction().with_title("Submit").with_data(
                SubmitActionData().with_data({"submissiontype": "multi_step_2", "name": name})
            ),
        ])

        return InvokeResponse(
            body=TaskModuleResponse(
                task=TaskModuleContinueResponse(
                    value=CardTaskModuleTaskInfo(
                        title="Multi-step Form: Step 2",
                        width=400,
                        height=300,
                        card=card_attachment(AdaptiveCardAttachment(content=next_card)),
                    )
                )
            )
        )

    if submission_type == "multi_step_2":
        name = data.get("name")
        email = data.get("email")
        await context.send(f"Hi {name}, thanks for submitting! Your email is {email}")
        return InvokeResponse(
            body=TaskModuleResponse(task=TaskModuleMessageResponse(value="Multi-step form completed!"))
        )

    usertext = data.get("usertext") if data else None
    await context.send(f"You submitted: {usertext}")
    return InvokeResponse(
        body=TaskModuleResponse(task=TaskModuleMessageResponse(value="Thanks for submitting!"))
    )

Рекомендации по использованию клавиатуры и специальных возможностей

Для диалоговых окон на основе URL-адресов, которые загружают HTML-содержимое, убедитесь в специальных возможностях клавиатуры:

• Используйте атрибут tabindex в тегах HTML для управления элементами, которые можно сфокусировать, а также для определения последовательной навигации с помощью клавиш TAB и SHIFT-TAB .
• Обработайте клавишу ESC соответствующим образом на javaScript для диалоговой страницы.

Microsoft Teams обеспечивает правильную навигацию с помощью клавиатуры из заголовка диалогового окна в HTML и наоборот.

Пример кода

Название примера	Описание	.NET	Node.js	Python
Модули задач бота	В этом примере приложения показано, как использовать диалоги (называемые модулями задач в TeamsJS версии 1.x) с помощью пакета SDK для ИИ Для Teams.	Просмотр	Просмотр	Просмотр

Следующий этап

Использование диалоговых окон на вкладках

См. также

• Карточки и диалоговые окна
• Общие сведения о пакете SDK для Teams
• Диалоговые окна в пакете SDK для Teams
• Адаптивные карточки в пакете SDK для Teams
• Миграция из BotBuilder