Вызов и закрытие модулей задач

Модули задач можно вызывать из вкладок, ботов или глубоких ссылок. Ответ может быть как в HTML, JavaScript, так и в качестве адаптивной карты. Существует большая гибкость с точки зрения вызова модулей задач и реагирования на взаимодействие пользователя. В следующей таблице кратко излагается, как это работает:

Вызывается с помощью Модуль задач с HTML или JavaScript Модуль задач с адаптивной картой
JavaScript на вкладке 1. Используйте функцию Teams SDK с необязательной функцией tasks.startTask() submitHandler(err, result) вызова.

2. В коде модуля задач, когда пользователь выполнил действия, вызываем функцию Teams SDK с объектом tasks.submitTask() result в качестве параметра. Если был указан вызов, Teams вызывает его submitHandler в качестве tasks.startTask() result параметра. Если при призыве произошла ошибка, функция tasks.startTask() submitHandler называется err строкой.

3. Вы также можете указать при completionBotId вызове teams.startTask() . Затем вместо result этого отправляется бот.
1. Вызов Teams клиентской SDK-функции с объектом TaskInfo и содержащим JSON для адаптивной карты, чтобы показать в всплывающее всплывающее представление модуля tasks.startTask() TaskInfo.card задач.

2. Если вызов был указан в , Teams вызывает его строкой, если произошла ошибка при вызове или если пользователь закрывает всплывающее всплывающее сообщение модуля задач с помощью X в правом верхнем submitHandler tasks.startTask() err tasks.startTask() ряду.

3. Если пользователь нажимает кнопку, его объект возвращается Action.Submit data в качестве значения result .
Кнопка карточки бота 1. Кнопки бот-карты в зависимости от типа кнопки могут вызывать модули задач двумя способами: URL-адресом глубокой ссылки или отправкой task/fetch сообщения.

2. Если действие кнопки является типом кнопки для адаптивных карт, событие HTTP POST отправляется type task/fetch Action.Submit task/fetch invoke боту. Бот отвечает на СООБЩЕНИЕ с помощью HTTP 200 и тело отклика, содержащее оболочку вокруг объекта TaskInfo. Дополнительные сведения см. в ссылке task/fetch на ссылку на модуль задач с помощью . Teams отображает модуль задач.

3. После выполнения действий пользователем вызываем Teams SDK с объектом tasks.submitTask() result в качестве параметра. Бот получает task/submit invoke сообщение, содержаное result объект.

4. У вас есть три различных способа ответа на сообщение, не делая ничего, что является успешно выполненной задачей, отобразив сообщение пользователю в всплывающее окно или путем запроса другого окна модуля task/submit задач. Дополнительные сведения см. в подробном обсуждении. task/submit
  • Как и кнопки на картах Bot Framework, кнопки адаптивных карт поддерживают два способа вызова модулей задач, глубокие ссылки URL-адресов с кнопками и использование Action.openUrl task/fetch Action.Submit кнопок.


  • Модули задач с адаптивными картами работают очень похоже на HTML или JavaScript. Главное отличие состоит в том, что, поскольку при использовании адаптивных карт javaScript нет javaScript, звонить tasks.submitTask() нельзя. Вместо этого Teams принимает объект и возвращает его в качестве data Action.Submit полезной нагрузки task/submit события. Дополнительные сведения см. в дополнительных task/submit сведениях.
URL-адрес глубокой ссылки
синтаксис URL-адреса
1. Teams вызывает модуль задач, который является URL-адресом, который отображается внутри указанного в параметре <iframe> url глубокой ссылки. Нет submitHandler вызова.

2. В JavaScript страницы в модуле задач позвоните, чтобы закрыть его с объектом в качестве параметра, так же, как при вызове его с вкладки или кнопки карты tasks.submitTask() result бота. Однако логика завершения несколько отличается. Если логика завершения находится на клиенте, если бота нет, нет вызова, поэтому любая логика завершения должна быть в коде, предшествующего submitHandler tasks.submitTask() вызову. Ошибки вызовов сообщаются только через консоль. Если у вас есть бот, можно указать параметр в глубокой ссылке, чтобы completionBotId отправить result объект через task/submit событие.
1. Teams вызывает модуль задач, который является телом карточки JSON адаптивной карты, заданным как url-кодированное значение параметра card глубокой ссылки.

2. Пользователь закрывает модуль задач, выбрав X в правом верхнем справа от модуля задачи или нажав кнопку Action.Submit на карточке. Так как нет вызова, у пользователя должен быть бот для отправки значения submitHandler полей адаптивной карты. Пользователь должен использовать параметр в глубокой ссылке, чтобы указать бота, чтобы отправить данные completionBotId с помощью task/submit invoke события.

В следующем разделе указывается объект, который определяет TaskInfo определенные атрибуты для модуля задач.

Объект TaskInfo

Объект TaskInfo содержит метаданные для модуля задач. Определите url для встроенного iFrame или card адаптивной карты. В следующей таблице содержится определение объекта:

Атрибут Тип Описание
title string Этот атрибут отображается ниже имени приложения и справа от значка приложения.
height number или string Этот атрибут может быть числом, представляющим высоту модуля задач в пикселях, или small , medium или large . Дополнительные сведения см. в деле размеров модуля задач.
width number или string Этот атрибут может быть числом, представляющим ширину модуля задач в пикселях, или small medium , или large . Дополнительные сведения см. в деле размеров модуля задач.
url string Этот атрибут — URL-адрес страницы, загружаемой в <iframe> модуль задач. Домен URL-адреса должен быть в массиве validDomains приложения в манифесте приложения.
card Адаптивная карта или вложение бота адаптивной карты Этот атрибут — JSON для адаптивной карты, которая появится в модуле задач. Если пользователь отзовется от бота, используйте адаптивную карту JSON в объекте Bot attachment Framework. На вкладке пользователь должен использовать адаптивную карту. Дополнительные сведения см. в вложении в бот-карту Adaptive Card или Adaptive Card.
fallbackUrl string Этот атрибут открывает URL-адрес на вкладке браузера, если клиент не поддерживает функцию модуля задач.
completionBotId string Этот атрибут указывает бот-ID приложения для отправки результатов взаимодействия пользователя с модулем задач. Если указано, бот получает событие с объектом task/submit invoke JSON в полезной нагрузке события.

Примечание

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

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

Размер модуля задач

Использование целого набора для и , задает высоту и ширину модуля TaskInfo.width TaskInfo.height задач в пикселях. Однако в зависимости от размера окна и разрешения экрана команды они уменьшаются пропорционально при сохранении соотношения аспектов шириной или высотой.

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

Пример модуля задач

Модули задач, вызываемые со вкладки, можно динамически реамизировать. После вызова можно вызвать, где свойства высоты и ширины объекта tasks.startTask() tasks.updateTask(newSize) newSize соответствуют спецификации TaskInfo, например { height: 'medium', width: 'medium' } .

В следующем разделе приводится пример встраив модулей задач в видео YouTube и PowerApp.

Модуль задач CSS для модулей задач HTML или JavaScript

Модули задач на основе HTML или JavaScript имеют доступ ко всей области модуля задач ниже заголовка. Хотя это обеспечивает большую гибкость, если вы хотите, чтобы обивка по краям совпадала с элементами заголовки и избегала ненужных свитков, пользователь должен предоставить правильный CSS. В следующих разделах вы можете привести несколько примеров для нескольких примеров использования.

Пример 1. Видео На YouTube

YouTube предлагает возможность встраить видео на веб-страницах. Легко встраить видео на веб-страницах в модуль задач с помощью простой веб-страницы забоя.

Видео YouTube

В следующем коде приводится пример HTML для веб-страницы без CSS:

<!DOCTYPE html>
<html lang="en">
<head>
  ⋮
</head>
<body>
  <div id="embed-container">
    <iframe width="1000" height="700" src="https://www.youtube.com/embed/rd0Rd8w3FZ0" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen=""></iframe>
  </div>
</body>
</html>

В следующем коде приводится пример CSS:

#embed-container iframe {
    position: absolute;
    top: 0;
    left: 0;
    width: 95%;
    height: 95%;
    padding-left: 20px;
    padding-right: 20px;
    padding-top: 10px;
    padding-bottom: 10px;
    border-style: none;
}

Пример 2. PowerApp

Для встраить PowerApp пользователь может использовать тот же подход. Поскольку высота или ширина любого отдельного PowerApp настраиваются, пользователь может настроить высоту и ширину для достижения нужной презентации.

PowerApp управления активами

В следующем коде приводится пример HTML для PowerApp:

<iframe width="720" height="520" src="https://web.powerapps.com/webplayer/iframeapp?source=iframe&screenColor=rgba(104,101,171,1)&appId=/providers/Microsoft.PowerApps/apps/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"></iframe>

В следующем коде приводится пример CSS:

#embed-container iframe {
    position: absolute;
    top: 0;
    left: 0;
    width: 94%;
    height: 95%;
    padding-left: 20px;
    padding-right: 20px;
    padding-top: 10px;
    padding-bottom: 10px;
    border-style: none;
}

В следующем разделе приводится подробная информация об отзове вашей карты с помощью адаптивной карты или вложения бот-карты адаптивной карты.

Адаптивная карта или вложение бота адаптивной карты

В зависимости от того, как вы назовете, необходимо использовать адаптивную карту или вложение бота адаптивной карты, которая является адаптивной картой, завернутой в объект card вложения.

При наводке со вкладки пользователю необходимо использовать адаптивную карту.

В следующем коде приводится пример адаптивной карты:

{
    "type": "AdaptiveCard",
    "body": [
        {
            "type": "TextBlock",
            "text": "Here is a ninja cat:"
        },
        {
            "type": "Image",
            "url": "http://adaptivecards.io/content/cats/1.png",
            "size": "Medium"
        }
    ],
    "version": "1.0"
}

В следующем коде приводится пример вложения бот-карты адаптивной карты при наложении от бота:

{
    "contentType": "application/vnd.microsoft.card.adaptive",
    "content": {
        "type": "AdaptiveCard",
        "body": [
            {
                "type": "TextBlock",
                "text": "Here is a ninja cat:"
            },
            {
                "type": "Image",
                "url": "http://adaptivecards.io/content/cats/1.png",
                "size": "Medium"
            }
        ],
        "version": "1.0"
    }
}

В следующем разделе приводится подробная информация о синтаксисе глубокой ссылки модуля задач, включая TaskInfo объект и APP_ID BOT_APP_ID .

Глубокая ссылка модуля задач — это сериализация объекта TaskInfo со следующими двумя другими деталями и необязательно APP_ID BOT_APP_ID :

https://teams.microsoft.com/l/task/APP_ID?url=<TaskInfo.url>&height=<TaskInfo.height>&width=<TaskInfo.width>&title=<TaskInfo.title>&completionBotId=BOT_APP_ID

https://teams.microsoft.com/l/task/APP_ID?card=<TaskInfo.card>&height=<TaskInfo.height>&width=<TaskInfo.width>&title=<TaskInfo.title>&completionBotId=BOT_APP_ID

Для типов данных и допустимых значений <TaskInfo.url> для , , , и , <TaskInfo.card> <TaskInfo.height> <TaskInfo.width> <TaskInfo.title> см. объект TaskInfo.

Совет

URL-адрес кодирует глубокую ссылку при использовании card параметра, например encodeURI() функции JavaScript.

В следующей таблице приводится информация о APP_ID BOT_APP_ID и:

Значение Тип Обязательный Описание
APP_ID string Да ID приложения, выдавлив модуль задач. Массив validDomains в манифесте для должен содержать домен, если APP_ID находится в url url URL-адресе. ID приложения уже известен, когда модуль задач вызывается со вкладки или бота, поэтому он не включен TaskInfo в .
BOT_APP_ID string Нет Если задано значение, объект отправляется с completionBotId result помощью сообщения task/submit invoke указанному боту. BOT_APP_ID должно быть указано как бот в манифесте приложения, то есть вы не можете отправить его любому боту.

Примечание

APP_ID и может быть одинаковым во многих случаях, если у приложения есть рекомендуемый бот для использования в качестве BOT_APP_ID ID приложения, если он есть.

В следующем разделе приводится подробная информация об использовании клавиатуры с модулем задач вашего приложения.

Рекомендации по клавиатуре и доступности

С помощью модулей задач на основе HTML или JavaScript необходимо убедиться, что модуль задач вашего приложения можно использовать с помощью клавиатуры. Программы чтения с экрана также зависят от возможности навигации с помощью клавиатуры. Это включает в себя следующие две вещи:

  • Использование атрибута tabindex в тегах HTML для управления элементами, которые могут быть сфокусированы. Кроме того, используйте атрибут tabindex, чтобы определить, где он участвует в последовательной навигации клавиатуры обычно с клавишами Tab и Shift-Tab.

  • Обработка ключа Esc в JavaScript для модуля задач. В следующем коде приводится пример обработки ключа Esc:

    // Handle the Esc key
    document.onkeyup = function(event) {
    if ((event.key === 27) || (event.key === "Escape")) {
      microsoftTeams.submitTask(null); // this will return an err object to the completionHandler()
      }
    }
    

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

Пример кода

Название примера Описание .NET Node.js
Пример модуля задач bots-V4 Примеры для создания модулей задач. View View
Пример вкладок модуля задач и ботов-V3 Примеры для создания модулей задач. View View

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

См. также