在选项卡中使用任务模块Using task modules in tabs

将任务模块添加到选项卡后,可以大大简化用户对需要数据输入的任何工作流的体验。Adding a task module to your tab can greatly simplify your user's experience for any workflows that require data input. 任务模块允许您在工作组感知弹出窗口中收集其输入信息。Task modules allow you to gather their input in a Teams-aware popup. 此示例的一个很有用的示例是编辑 Planner 卡片;您可以使用任务模块来创建类似的体验。A good example of this is editing Planner cards; you can use task modules to create a similar experience.

若要支持任务模块功能, Microsoft 团队客户端 SDK中添加了两个新函数:To support the task module feature, two new functions were added to the Microsoft Teams client SDK:

microsoftTeams.tasks.startTask(
    taskInfo: TaskInfo,
    submitHandler?: (err: string, result: string | any) => void
): void;

microsoftTeams.tasks.submitTask(
    result?: string | any,
    appIds?: string | string[]
): void;

我们来看看每个方法的工作方式。Let's see how each of them work.

从选项卡调用任务模块Invoking a task module from a tab

若要从选项卡调用任务模块,请使用 microsoftTeams.tasks.startTask() 传递TaskInfo 对象和可选的 submitHandler 回调函数。To invoke a task module from a tab use microsoftTeams.tasks.startTask() passing a TaskInfo object and an optional submitHandler callback function. 如上文所述,有两种情况需要考虑:As described earlier, there are two cases to consider:

  1. 的值 TaskInfo.url 设置为 URL。The value of TaskInfo.url is set to a URL. 将显示 "任务模块" 窗口,并 TaskModule.url<iframe> 其加载为内部。The task module window appears and TaskModule.url is loaded as an <iframe> inside it. 该页面上的 JavaScript 应调用 microsoftTeams.initialize()JavaScript on that page should call microsoftTeams.initialize(). 如果 submitHandler 页面上有一个函数,并且调用时出现错误 microsoftTeams.tasks.startTask() ,则会调用,并将其 submitHandler err 设置为错误字符串,以指示如下所述below的错误。If there is a submitHandler function on the page and there is an error when invoking microsoftTeams.tasks.startTask(), then submitHandler is invoked with err set to the error string indicating the error as described below.
  2. 的值 taskInfo.card自适应卡片的 JSONThe value of taskInfo.card is the JSON for an Adaptive card. 在这种情况下,在 submitHandler 用户关闭或按下自适应卡片上的按钮时,显然没有任何要调用的 JavaScript 函数; 通过将结果传递给 bot,接收用户输入的内容的唯一方法。In this case there's obviously not any JavaScript submitHandler function to call when the user closes or presses a button on the Adaptive card; the only way to receive what the user entered is by passing the result to a bot. 若要从选项卡中使用自适应卡片任务模块,您的应用程序必须包括用于从用户获取任何信息的 bot。To use an Adaptive card task module from a tab your app must include a bot to get any information back from the user. 下面对此进行了说明。This is explained below.

示例:调用任务模块Example: Invoking a task module

下面的代码适用于任务模块示例The code below is adapted from the task module sample. 任务模块如下所示:Here's what the task module looks like:

任务模块-自定义窗体

submitHandler这非常简单; 它只是回显控制台的值 err resultThe submitHandler is very simple; it just echoes the value of err or result to the console:

let taskInfo = {
    title: null,
    height: null,
    width: null,
    url: null,
    card: null,
    fallbackUrl: null,
    completionBotId: null,
};

taskInfo.url = "https://contoso.com/teamsapp/customform";
taskInfo.title = "Custom Form";
taskInfo.height = 510;
taskInfo.width = 430;
submitHandler = (err, result) => {
    console.log(`Submit handler - err: ${err}`);
    console.log(`Submit handler - result\rName: ${result.name}\rEmail: ${result.email}\rFavorite book: ${result.favoriteBook}`);
};
microsoftTeams.tasks.startTask(taskInfo, submitHandler);

提交任务模块的结果Submitting the result of a task module

submitHandler函数与一起使用 TaskInfo.urlThe submitHandler function is used with TaskInfo.url. submitHandler函数驻留在网页中 TaskInfo.urlThe submitHandler function resides in the TaskInfo.url web page. 如果调用任务模块时出现错误 submitHandler ,将立即使用 err 指示发生了哪种错误的字符串来调用函数。If there's an error when invoking the task module your submitHandler function will be immediately invoked with an err string indicating which error occurred. submitHandler err 当用户按下位于任务模块右上角的 X 时,也可以使用字符串调用函数。The submitHandler function is also called with an err string when the user presses the X at the upper right of task module.

如果没有调用错误,并且用户没有按 X 关闭它,则用户在完成时按下一个按钮。If there's no invocation error and the user doesn't press X to dismiss it, the user presses a button when finished. 根据任务模块中的 URL 或自适应卡片的不同,将发生以下情况:Depending on whether it's a URL or an Adaptive card in the task module, here's what happens:

HTML/JavaScript ( TaskInfo.urlHTML/JavaScript (TaskInfo.url)

验证用户输入的内容后,您就可以调用 microsoftTeams.tasks.submitTask() SDK 函数(在以后 submitTask() 出于可读性目的而引用)。Once you've validated what the user has entered you call the microsoftTeams.tasks.submitTask() SDK function (referred to hereafter as submitTask() for readability purposes). submitTask()如果只想要团队关闭任务模块,则可以不带任何参数调用,但大多数时候需要将一个对象或字符串传递给您的 submitHandlerYou can call submitTask() without any parameters if you just want Teams to close the task module, but most of the time you'll want to pass an object or a string to your submitHandler.

将您的结果作为第一个参数传递。Pass your result as the first parameter. 团队将调用的 submitHandler 位置 err null ,并且 result 将为您传递到的对象/字符串 submitTask()Teams will invoke submitHandler where err will be null and result will be the object/string you passed to submitTask(). 如果 submitTask() 使用参数进行调用 result ,则必须传递一个或多 appIdappId 字符串数组:这允许团队验证发送结果的应用程序是否与调用任务模块的应用程序相同。If you do call submitTask() with a result parameter, you must pass an appId or an array of appId strings: this allows Teams to validate that the app sending the result is the same one which invoked the task module.

自适应卡片( TaskInfo.cardAdaptive card (TaskInfo.card)

如果调用任务模块时使用的是 submitHandler ,当用户按下按钮时, Action.Submit 卡片中的值将作为的值返回 resultIf you invoked the task module with a submitHandler, when the user presses an Action.Submit button the values in the card will be returned as the value of result. 如果用户按 Esc 按钮或按 X, err 则将改为返回。If the user presses the Esc button or presses the X, err will be returned instead. 或者,如果您的应用程序包含一个 bot 以及一个选项卡,您只需在 appId 对象的值中包含 bot 的 completionBotId TaskInfoAlternatively, if your app contains a bot in addition to a tab you can simply include the appId of the bot as the value of completionBotId in the TaskInfo object. 自适应卡片正文(由用户填写)将在 task/submit invoke 用户按下按钮时通过消息发送到机器人 Action.SubmitThe Adaptive card body (as filled in by the user) will be sent to the bot via a task/submit invoke message when the user presses an Action.Submit button. 您接收的对象的架构与您收到的用于任务/提取和任务/提交邮件的架构非常相似;唯一的区别在于,JSON 对象的架构是一个自适应卡片对象,而不是包含自适应卡片对象的对象,就像在使用自适应卡片时使用 bot一样。The schema for the object you receive is very similar to the schema you receive for task/fetch and task/submit messages; the only difference is that the schema of the JSON object is an Adaptive card object as opposed to an object containing an Adaptive card object as when Adaptive cards are used with bots.

示例:提交任务模块的结果Example: submitting the result of a task module

使用 HTML 表单撤回上面的任务模块中的表单Recall the form in the task module above with an HTML form. 以下是定义表单的位置:Here's where the form is defined:

<form method="POST" id="customerForm" action="/register" onSubmit="return validateForm()">

此窗体上有五个字段,但我们只对其中三个字段的值感兴趣,例如: nameemailfavoriteBookThere are five fields on this form but we're only interested in the values of three of them for this example: name, email, and favoriteBook.

下面是 validateForm() 调用的函数 submitTask()Here's the validateForm() function that calls submitTask():

function validateForm() {
    var customerInfo = {
        name: document.forms["customerForm"]["name"].value,
        email: document.forms["customerForm"]["email"].value,
        favoriteBook: document.forms["customerForm"]["favoriteBook"].value
    }
    microsoftTeams.tasks.submitTask(customerInfo, "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx");
    return true;
}

任务模块调用错误Task module invocation errors

以下是 err 可由您接收到的可能值 submitHandlerHere are the possible values of err that can be received by your submitHandler:

问题Problem 错误消息(值为 errError message (value of err)
TaskInfo.url已指定和的值 TaskInfo.cardValues for both TaskInfo.url and TaskInfo.card were specified. "同时指定了卡片和 url 的值。"Values for both card and url were specified. 允许使用其中一个或另一个,但不是两者。One or the other, but not both, are allowed."
TaskInfo.urlTaskInfo.card 指定也不指定。Neither TaskInfo.url nor TaskInfo.card specified. "必须为卡片或 url 指定值。""You must specify a value for either card or url."
无效 appIdInvalid appId. "AppId 无效。""Invalid appId."
用户已按 X 按钮,然后关闭它。User pressed X button, closing it. "用户取消/关闭了任务模块"。"User cancelled/closed the task module."